1    Domain SSL Certificates

Domain SSL certificates are used for site identity and encryption, so site visitors and service users can be certain the site is genuine and communications are secure.

Domain Names in SSL certificates can be specified as a list of valid domains (example.com, www.example.com, mail.example.com, etc.). The domain list (and therefore certificate) may become quite large for sites with many services addressed as "service"."example.com". Another way of specifying valid domains in certificates is using a wildcard ("*") prefix to specify certificate domain names. The certificate will be valid for "*.example.com where" "*" can be "www", "mail", "iot", etc. (any prefix to base domain name).

Certificates must be created for www.yourdomain and yourdomain (both in same certificate file). This handles the case of the website being addressed as www.yourdomain or yourdomain. In general, domain names in certificates must exactly match the URL used to address the site or be wildcard certificates. Otherwise, clients will consider your site insecure and either refuse to connect or the browser will ask the user for a security exception.

1.1                Types of SSL Certificates

There are three types of SSL certificates, differentiated by degree of trust checking that the certificate issuer has performed. GlobalSign provides an overview of SSL certificate types:

• Domain Validation (DV): It has been proven that the domain(s) exist and are controlled by whoever requested the certificate. Users can be assured that communication with the site is secure. Visitors CANNOT be assured that any personal or business identity information on the site is accurate.

• Organization Validation(OV): SSL Certificates: where the CA checks the right of the applicant to use a specific domain name PLUS it conducts some verification of the organization. Additional organizational information is displayed to clients when clicking on the Secure Site Seal, giving enhanced visibility of who controls the site and associated enhanced trust.
• Extended Validation(EV): SSL Certificates: where the Certificate Authority (CA) checks the right of the applicant to use a specific domain name PLUS it conducts a THOROUGH verification of the organization. The issuance process of EV SSL Certificates is strictly defined in the EV Guidelines, as formally ratified by the CA/Browser forum in 2007, that specify all the steps required for a CA before issuing a certificate.

The type of SSL certificate required depends on the degree of trust you wish your clients to have. If your site is an e-commerce or medical site and you collect sensitive information, personal data such as passwords and credit card numbers, an Extended Validation (EV) certificate is required. This requirement can be omitted if you use a third party payment processor (with EV certificates) such as PayPal, Visa or Mastercard for e-commerce.

Free SSL certificates provide Domain Validation (DV) and only assure site clients that their communications are secure. They are adequate for all sites, including ecommerce, if a third party payment processor is used.

2    Free LetsEncrypt Certificates

LetsEncrypt is a free, automated and open certificate authority supported by many leading internet companies concerned regarding the negative effects of high cost and complexity of commercial SSL certificates. They have done an excellent job, to the dismay of high-cost commercial SSL certificate providers.

2.1                Manual Certificate Method

LetsEncrypt certificates are valid for three months. They must be renewed every three months whether issued manually or automatically.

If your domain is a subdomain of a DNS provider and your DNS provider is not on the "Public Suffix List", you may have to create your SSL certificates manually. Further information regarding the "Public Suffix List" and why DNS providers need to be and how to get on the "list" is available here. Automatic creation / updates of LetsEncrypt SSL certificates may fail due to "rate limiting" for domains from DNS providers not on the "list". The options are to choose a DNS provider from the list or be prepared for rate limiting failures and retries (until success) using automatic certificate updates.

SSL For Free has a very easy to use webpage for creating LetsEncrypt SSL certificates. Go to their site, click "Advanced Options" for instructions regarding how to enter multiple domains. Use the following procedure:

• Enter "https://www.yourdomain https://yourdomain" in the address bar.
• Select "Create Free SSL Certificate"
• You will be presented with three creation options. Choose "Manual Verification" unless you understand how to use and prefer the alternative methods.
• Select "Manually Verify Domain" and follow the instructions.
• Select "Download Certificates".
• Optional: Create an account to manage certificates and be notified when certificates expire.
• You can choose to copy and paste your certificates or, download them. SecureOffice requires certificates to be in directory "/etc/ssl/domains".
• It is suggested to name the certificates "domain.cer" and "domain.key". Alternatively, in directory "/etc/ssl/domains/", Link the certificate files to "domain.cer" and "domain.key". Portions of SecureOffice such as Nginx and SecurePBX depend on certificate files (or linked files) named "/etc/ssl/domains/domain.cer" and "/etc/ssl/domains/domain.key".
• The LetsEncrypt certificate authority (CA) file is pre-installed on SecureOffice by package "ca-certificates".

2.2                Automatic Certificate Method

This method works for unique domain names (yoursite.com, etc) and subdomains of DNS providers who may or may not be on the "Public Suffix List" (described in previous section). Using this method, certificates are created and renewed automatically.

SecureOffice offers a custom application called "luci-app-nginx-certificates" which automatically requests and updates LetsEncrypt certificates. To install it, enter "opkg update; opkg install luci-app-nginx-certificates" at a SecureOffice command prompt.

After installing luci-app-nginx-certificates, using a browser on your LAN, access the SecureOffice / OpenWrt web GUI and navigate to "Services->Domain Certificates". You will see the certificate administration page, as shown below:

Figure 1: Domain Certificates Administration

If "Domain Certificates" does not appear under the "Services" menu, the SecureOffice web server cache must be cleared and restarted. Enter "rm -rf /tmp/luci-*; /etc/init.d/nginx restart" at a command prompt and reload the page.

Change the email address (Global Configuration) to the email address that LetsEncrypt certificate expiry notices should go to. If left blank, LetsEncrypt will not send notices.

Delete the default domain entry by pressing "Delete" (Red button on right under "Certificates").

Enter a descriptive name for your new domain section to the left of the "Add" button. The section name can contain letters, numbers and underscores. It is suggested to use your primary domain with underscores, for example "my_domain_com". Press the "Add" button. A new section named "my_domain_com" will be created.

Note: If creating certificates for Sme-Server, be aware that Sme-Server allows specification of only one certificate and key files. This means that if Sme-Server is hosting multiple virtual domains, one certificate including all hosted domains must be created.

Fill in the following fields:

• Domain Name(s): A list of base domain names with no "www" or "*", for example "example.com". "www" (if not using DNS validation) or "*" (if using DNS validation) are automatically added to the list of domains and do not appear in the OpenWrt GUI. If using multiple domains, the first domain name entered must be your primary domain, the one used at initial SecureOffice registration. This is the domain entry in "/etc/hosts" of the form "<LAN_Address> <domain>", that was entered prior to registering (System->Licensing->Registration). Press "+" to add the first domain.
• Add as many domains required, pressing "+" after each one. Your certificates will appear in directory "/etc/acme/your_primary_domain/" with names "your_primary_domain.cer" and "your_primary_domain.key". These certificates are automatically linked to "/etc/ssl/domains/domain.crt" and "/etc/ssl/domains/domain.key" respectively. The certificates will be valid for all entered domains.
• Using the dropdown, set the "Key Size" to "2048" (most common). Other key sizes and types (2048, 3072, 4096, 8192, ec-256, ec-384 or ec-521) can be selected.

Once the domains and Key Size are entered, the new domain entries will appear as below:

Figure 2: Domain Certificate Entry

SecureOffice supports domain validation using local (HTTP-01) or DNS (DNS-01) LetsEncrypt challenges.

2.3                Non-Wildcard Certificates

• LetsEncrypt verifies each specified domain by contacting each (sub)domain at your site.
• More configuration (Nginx) is required compared to using wildcard certificates.
• Each Nginx server (domain / vhost) entry must have a "location /.well-known/acme-challenge/" block as discussed in domain configuration. This allow LetsEncrypt to read and write the files required for domain verification. If you are using subdomain addressing for servers, each Nginx server / subdomain block must also have this location block
• Using the "DNS Service" dropdown select "Not Using DNS" and leave the "DNS Credentials" fields blank. These are used for LetsEncrypt domain verification using your DNS provider as opposed to verifying by contacting your domain.
• Skip past the wildcard certificates section.

2.4                Wildcard Certificates

• Wildcard certificates are valid for site URL's of the form <anything>.yoursite.com, where "<anything>" can be any domain prefix, as discussed here.
• LetsEncrypt DNS verification works by contacting your DNS provider instead of your site. No Nginx support ("location /.well-known/acme-challenge/" blocks) for LetsEncrypt are required (simpler).
• Not all DNS providers support this method. A list of verified DNS providers can be viewed using the "DNS Service" dropdown.
• Using the "DNS Service" dropdown choose your DNS provider. For example, "dns_dynu" which selects dynu.com (recommended, used by SecureOffice team) as the DNS provider.
• Do an internet or search chosen DNS provider for "<provider> API credentials". For dynu, the required credentials are OAUTH2 keys "client_id" and "secret" which correspond to DNS Credentials "Dynu_ClientId" and "Dynu_Secret" respectively. Each DNS provider has a unique set of credentials which are used as variables during LetsEncrypt verification. For other supported DNS providers, it may be necessary to inspect the provider file in "/usr/lib/acme/dnsapi/" to determine the required variable names. Alternatively, perform an internet search "<DNS provider name> LetsEncrypt acme API".
• Log into your DNS provider account to get the required credentials. Enter them, one at a time in the "DNS Credentials" field of the form "<variable name>=<variable value>", pressing "+" for each one. These entries can contain no spaces.

You will see your updated configuration, as shown below:

Figure 3:DNS Domain Certificate Entry

2.5                Acquiring Certificates

• Test Checkbox: Leave checked until "Update" (fake certificates) using "Test" succeeds.
• Debug Checkbox: Leave checked until "Update" succeeds.
• Force Checkbox: Check to force an update even if valid certificates already exist. Caution: this may result in LetsEncrypt rate limiting you, delaying certificate issuance.
• Auto Update: Leave unchecked until non-Test "Update" succeeds (real certificates) meaning you are ready for automatic updates of real certificates.
• Press "Save & Apply".

Ensure "Test" and "Debug" are selected. Press "Update". A "Command Results" text area will appear, displaying status, any error messages and pass / fail status. Fix any errors before proceeding (may require internet search).

Uncheck "Test", press "Update" again. A "Command Results" text area will appear, displaying status, any error messages and pass / fail status. Fix any errors before proceeding (may require internet search).

One error to watch out for is "Too Many Certificates Issued" which is an indication you are using a subdomain of a DNS provider not on the "Public Suffix List", meaning that you should retry (or, allow automatic reties to proceed until success), or an alternate method of acquiring SSL certificates or a LetsEncrypt compatible DNS provider must be chosen. While you are at it, send a support request to the DNS provider requesting they get on the "Public Suffix List".

After real certificates have been successfully created, check "Auto Update", uncheck "Debug", then "Save & Apply" to have your certificates auto renew and never have to deal with expired SSL certificates and costs again. "Auto Update" schedules a weekly task every Sunday at 11:30 PM which checks for certificate expiry and updates them if necessary.

Certificates can be viewed (and copied) by pressing "Show Certs".

3    Alternative Free SSL Certificates

There are many providers of free SSL certificates which can be found by an internet search. Follow their instructions to acquire certificates.

Be aware that all free SSL certificate providers (except for LetsEncrypt) require manual certificate renewal and expire quickly, with a maximum validity of three months.

Do not use free certificates from WoSign or StartCom, they have lost trust by major browser manufacturers and will not work except for older browsers.

It is also possible to use free self-signed SSL certificates (search internet for instructions) with the disadvantage that the root certificate authority (CA) file must be distributed and installed on all clients (PC's , tablets, phones). This may be useful for the truly paranoid, who do not trust third party certificate providers with their decryption keys and wish to form a private network of trust.

Alternative SSL certificates must be copied to SecureOffice directory "/etc/ssl/domains". The certificate file must be linked to "/etc/ssl/domains/domain.crt" ("ln -sf <certificate file> /etc/ssl/domains/domain.crt"). The key file must be linked to "/etc/ssl/domains/domain.key" ("ln -sf <certificate file> /etc/ssl/domains/domain.key"). This is done automatically for automatic certificate updates. Certificate names and location are crucial for Nginx and other SecureOffice applications.

4      Commercial SSL Certificates

There are many providers of commercial (paid) SSL certificates which can be found by an internet search. Follow their instructions to acquire certificates.

Commercial SSL certificates must be copied to SecureOffice directory "/etc/ssl/domains". The certificate file must be linked to "/etc/ssl/domains/domain.crt" ("ln -sf <certificate file> /etc/ssl/domains/domain.crt"). The key file must be linked to "/etc/ssl/domains/domain.key" ("ln -sf <certificate file> /etc/ssl/domains/domain.key"). This is done automatically for automatic certificate updates. Certificate names and location are crucial for Nginx and other SecureOffice applications.