Adding a CA Signed Security Certificate
We are not able to ship a real certificate with Ignition because security certificates have to be obtained individually from a Certificate Authority (CA). Ignition supports certificates from both your organization's internal CA, as well as commercial CAs (Verisign, GoDaddy, Comodo, etc.). In either case, the procedure for how to install a certificate is listed below.
ignition.conf file by altering the
ignition.ssl.refresh entry (Set to 0 to not refresh).
Get a Certificate Signing Request
Since SSL/TLS requires the installation of a security certificate, filling out the form below will generate a certificate signing request (CSR) to provide to a certificate authority.
- Go to the Config tab of the Gateway Webpage and choose Networking > Web Server.
- You'll see a warning message indicating that SSL/TLS is not enabled.
- Click on Setup SSL/TLS.
- Click on the I don't have all the items above button. The Create Certificate screen is displayed.
Fill in the required fields on the screen, then click the Generate Certificate Signing Request button. This can be brought to a Certificate Authority.
Basic Details Field Definition Common Name
Full DNS name (required). This is typically what you type in your browser URL bar in order to navigate to this Gateway, for example : yourdomain.com
Organization Name Name of company (required). F or example : Inductive Automation. Organization Department Department or section (required). F or example : Engineering Email address. F or example : email@example.com. Country Typically an ISO 3166 2 character code (required). F or example : US State / Province
State, province or region, for example : California
Locality (City) Name of city. For e xample: Folsom Street Street number and street name. For example : 90 Parkshore Dr Postal Code Postal Code Example: 95630 Key Type
The algorithm of the key pair which will be generated for the self signed certificate. Options are RSA or EC. Recommended: RSA
The strength of the generated Key. Recommended: 2048 bits
Expires in The number of days the generated Certificate will be valid. This number will only apply to a self-signed certificate. The certificate authority will determine a final expiration date as needed for the CA signed certificate Subject Alternative Names Field Definition IP Addresses
The IP addresses of all the servers you plan on installing the certificate. Click the Add button for each additional IP address.
DNS names which map to the list of IP addresses above. Click the Add button for each additional DNS name.
Demonstrate Proof of Ownership over your Domain
After providing a CSR to your CA and before your CA issues a new domain-validated (DV) certificate , your CA will require you to demonstrate proof of control over the domain(s) used to access the Ignition Gateway Web Server. These domains should be set as the subject common name and/or subject alternative names in your CSR. Your CA will require you to perform additional actions and to provide additional information if you are seeking an organization validation (OV) class certificate or an extended-validation (EV) certificate . See the Wikipedia article on Public Key Certificates and consult your CA for more details.
Methods for determining control over a domain varies based on the CA. Typical methods include:
- Responding to email sent to the email contact in the domain's whois details
- Responding to email sent to a well-known administrative contact in the domain, e.g. (admin@, postmaster@, etc.)
- Publishing a DNS TXT record
- Publishing a nonce provided by an automated certificate issuing system
The first three methods are performed out-of-band as far as Ignition is concerned. Let’s drill a little bit deeper into the fourth method. Typically, the CA will provide a randomly generated cryptographic string of data which may only be used once. This value is called a “nonce ”. The CA expects you to configure your web server to serve the nonce as a special HTTP resource referenced using a well-known path. Once you configure your web server to serve this resource, you give your CA permission to make an HTTP request with a URL containing the domain you are trying to validate as the hostname component of the URL (which should resolve to an IP address of the host running your web server), an agreed-upon port (usually standard HTTP port 80 or HTTPS port 443, though sometimes this is configurable), and the well-known path as the path component of the URL.
There exists software purpose-built to stand-up a temporary web server for the purpose of exposing the special nonce value to the CA. The idea is that this web server is only listening for HTTP requests until you confirm that the CA has issued an HTTP request to the server and has validated the nonce value as correct, then the web server is shut down. In some cases, using such software is not possible if the Ignition Gateway is already listening on whatever port is required by the validation method. In these cases, shutting down the Ignition Gateway for the purpose of starting up one of these other tools would cause potentially unacceptable downtime.
To work around the downtime issue mentioned in the previous paragraph, Ignition supports two open standard specifications which accomplish the fourth validation method mentioned above. The first is the ACME Protocol’s “HTTP Challenge”, detailed in section 8.3 of RFC 8555 (ACME is the protocol used by Let’s Encrypt ). Ignition’s web server will map HTTP requests with a path pattern of /.well-known/acme-challenge/<challenge-nonce> to files located at $GATEWAY_HOME/.well-known/acme-challenge/<challenge-nonce> (where $GATEWAY_HOME is the path to the home directory of your Ignition Gateway installation). No Gateway restart is required to start serving new files recently added to the above directory to the web. The challenge-nonce placeholder is the nonce value provided by the ACME server which should be base64-url-encoded.
The second method is defined as the “Agreed-Upon Change to Website v2” process and procedure of validation of domain authorization or control, detailed in section 188.8.131.52.18 of version 1.81 of the CA / Browser Forum’s Baseline Requirements for the Issuance and Management of Publicly-Trusted Certificates . Ignition’s web server will map HTTP requests with a path pattern of /.well-known/pki-validation/<challenge-file> to files located at $GATEWAY_HOME/.well-known/pki-validation/<challenge-file> . Again, no Gateway restart is required to start serving new files recently added to the above directory to the web. The challenge-file placeholder in this case is arbitrary–check with your CA for more detailed instructions as to what the value should be.
For both methods above, it is best practice to stop exposing the challenge value to the web by deleting the file on the Gateway filesystem as soon as the CA is done verifying your control over the domain.
These standard challenge mechanisms can be used to automate certificate renewal–in fact, that’s what the ACME Protocol and Let’s Encrypt is all about. To learn more about how to use Ignition with ACME and Let’s Encrypt, see the Let's Encrypt Guide for Ignition .
Install Security Certificates
Once you have an SSL certificate, it needs to be added to Ignition.
- Go to the Config tab of the Gateway Webpage and choose Networking > Web Server.
- You'll see a warning message indicating that SSL/TLS is not enabled. Click on the Click here link.
- The Setup SSL/TLS screen is displayed. Review the following list:
- Private Key
- Certificate Signed By A Certificate Authority (CA)
- Any Intermediate CA Certificates (Provided by your CA)
- Root CA Certificate (Provided by your CA)
- If you have the items, click on the I have all the items above button. If you don't have all the items, click on the I don't have all the items above button, and follow the previous procedure, Get a Certificate Signing Request.
- The Certificate Wizard is displayed. The first step is to import your private key in one of the following three ways.
- Drag and Drop your certificate from your computer onto the screen.
- Click anywhere on the grey box to browse for the private key.
- Click Manually enter data button to type in the private key information
- If the private key is encrypted, click the checkbox to enable a password for this certificate and enter the password in the field. Click Continue.
The next step is to import the server certificate. This is the The DER or PEM encoded X.509 SSL Certificate that Ignition will use for SSL / TLS. Drag and drop the certificate file, browse for it, or manually enter the data.
The next step is to import the certificate chain. This gives you the Intermediate CA Certificate. Drag and drop the certificate file or bundle, browse for it, or manually enter the data.
You'll see a message that the Intermediate CA Certificate was successfully uploaded.
Finally, import the root CA certificate: Drag and drop the certificate file, browse for it, or manually enter the data. You'll see a message that the Root CA Certificate was successfully uploaded.
Click the Continue button.
You'll see a confirmation message that the certificate is installed and SSL/TLS is enabled.
- If you have a redundant installation, you'll need to repeat this procedure on your backup server.
What is a Self-Signed Certificate
SSL/TLS can still be setup without a CA signed certificate by installing a self-signed certificate. This gives you the encryption benefits of SSL, but not the identity validation, and it isn't a "real" certificate. When a self-signed certificate is used to enable SSL/TLS, a web browser will display warnings to users that they shouldn't trust the website. Users will then have to choose to proceed to the "unsafe" connection through Advanced options.
How to Install a Self-Signed Certificate
- Go to Config section of the Gateway Webpage.
- Choose Networking >> Web Server from the menu on the left.
- Under SSL/TLS click on Setup SSL/TLS.
- Select “I don’t have all the items above”.
Under the Basic Details section, fill in all of the required fields (*). This includes the Common Name, Organization Name, Organization Department, and Country.
The Common Name is typically what you input into your browser URL bar in order to navigate to this gateway. If you do not have a dedicated domain for your gateway, use the IP address.
Under Subject Alternative Names , enter in the IP Address along with any DNS associated with your gateway server.
- Select Show Advanced Properties and click on Install Self-Signed Certificate.
This will take you to a page that displays the privacy warning that all connections will now see.
SSL/TLS is now enabled on your Gateway. The URL for your gateway now uses HTTPS and port 8043, which is the default port for SSL.