Installing a valid SSL Web certificate in Access Server
Cryptography is a complex matter to grasp, and SSL certificates, when never having heard of them before, can be a challenge to understand. While installing and managing an SSL certificate for your Access Server may seem overly complex, this article tries to cover all the basics so you can get your Access Server secured in a snap! It’s important to note that SSL certificates only work when you are using an FQDN name for your OpenVPN Access Server installation. FQDN stands for Fully Qualified Domain Name, and an example of this is docs.openvpn.net or openvpn.net. These are names that exist on the Internet and can be resolved with a DNS query. If you do not have such a name set up yet, then arrange that first and configure this properly. Then you can continue with this document and set up an SSL certificate on the FQDN name you have chosen for your server installation.
This article will cover the following:
- An explanation why you should install an SSL certificate.
- How to generate a certificate signing request (CSR) for submission to a commercial certificate authority (CA).
- How to install a commercial SSL certificate in Access Server.
- Some common problems and solutions to these problems.
- How to extend the self-signed certificate validity or change the common name of the self-signed certificate.
- How to revert Access Server to a self-signed certificate (removing a commercial SSL certificate).
Why should you replace the SSL certificate?
You may have noticed when you started using the OpenVPN Access Server product, that you get warnings like warning: your connection is not private or could not verify identity of this server or such dire messages. It’s good that you get these messages as they alert you to the fact that the SSL certificate on this server isn’t valid. Or rather, it is valid as there is encrypting happening between your web browser and the web server, but it is not trusted. Only when an SSL certificate is trusted, will the green padlock icon show up in the address bar and will these messages disappear. It also gets rid of some warnings that you see in the OpenVPN Connect Client when you initially install it, also warning you that the server identity could not be verified.
So to answer the question why you should replace the SSL certificate, first and foremost is getting rid of the warnings. But one of the most important aspects really is that a verified and trusted SSL certificate is a guarantee that you are connected to the server that you think you are connecting to. The identity of the server, that it is the server you want to connect to, is guaranteed if an SSL certificate is properly signed. If you have things set up with a signed and verified SSL certificate, you will see the green padlock icon indicating that you are connected to your server and not to any other server pretending to be your server. If in some way someone succeeds in redirecting your traffic to another server, to try and steal credentials for example, will result in that big bad warnings you see when the SSL certificate is not trusted. Just like what happens initially when you install the Access Server and by necessity an untrusted self-signed certificate is used at first.
We also have some more information about what an SSL certificate is and how it works here.
Generate a Certificate Signing Request
To order to generate the proper keying materials for your Access Server software, you will need a machine with OpenSSL installed. This is most easily done on a Linux system, like for example the Linux operating system that your OpenVPN Access Server is running on. To see if you have OpenSSL already installed try logging on to your Linux server and obtain root privileges and then using the commands below. If you do not have OpenSSL installed, then use the indicated commands below to install it.
See if OpenSSL is installed:
If you get an error use this to install on Debian/Ubuntu systems:
apt-get install openssl
Or on CentOS/Red Hat systems:
yum install openssl
Now that OpenSSL is installed you can use it to create a private key and certificate signing request (4096 bits SHA256):
openssl req -out server.csr -new -newkey rsa:4096 -sha256 -nodes -keyout server.key
You will be asked a set of standardized questions. This is how we answered it in our example situation:
Country Name (2 letter code) [AU]: US State or Province Name (full name) [Some-State]: California Locality Name (eg, city) : San Francisco Organization Name (eg, company) [Internet Widgits Pty Ltd]: Exampletronix, Inc. Organizational Unit Name (eg, section) : IT Support Common Name (eg, YOUR name) : vpn.exampletronix.com <- This is the FQDN name for your server. Email Address :firstname.lastname@example.org Please enter the following 'extra' attributes to be sent with your certificate request A challenge password : An optional company name :
In the example above we didn’t specify a challenge password or optional company name. Some certificate authorities don’t let you specify an optional company name or know how to deal with a challenge password, so it’s our recommendation to leave those last two questions unanswered and just press enter on them to continue. With the steps followed as above we now have a server.key and a server.csr file.
The server.key file is the private key and it is vital that this key is kept safe and secure. You will need this file once your certificate signing request has been approved and a certificate has been issued to you. Also, it is the underpinning of the SSL certificate security model. This private key stays with you and does not go to any other party!
The server.csr file is the certificate signing request. In the questions above you were asked to provide a “Common Name”. That is where the FQDN name where your Access Server can be reached on the Internet is supposed to go. If for example your Access Server has been set up at the address https://vpn.exampletronix.com/ then the Common Name is vpn.exampletronix.com just like in our example. This means that in our example, our certificate signing request is going to be for the subdomain vpn.exampletronix.com on the domain exampletronix.com.
Now you can go to your chosen SSL certificate authority. There are a great many out there. Pick one you like and they will ask you for a certificate signing request and what type of server you are looking to get a certificate for. If asked, the type of certificate you will want is Apache or Apache2 compatible. We don’t actually use Apache software in our OpenVPN Access Server product, but we do use that same type of certificates.
Next copy and paste the contents of the file server.csr or upload it to them as a file. They will then look at it and see the answers you gave earlier. Now comes the part where they are going to try to verify that you are really the owner of the domain exampletronix.com. One way they can do this is to ask you to place a file on your web server, which they will then try to retrieve. Or they can send a verification email to a registered email address that is known at the domain registry for the domain exampletronix.com. These steps they do to ensure that they are dealing with the real owner of the domain exampletronix.com and not with someone pretending to be. Only the real owner would have access to the registered email address or the website running on the domain you are trying to get a certificate signed for.
Once they’ve verified your identity and received payment, they’ll sign a certificate and send it to you. They’ll also send you intermediary files, or they may have these available separately on their website. Intermediary files are their own certificates that complete the chain of trust between the certificate they’re just issued you, and a root certificate authority that is trusted by the majority of web browsers and SSL capable programs. Without the intermediary files it may not be possible to establish a chain of trust between your signed public certificate and a trusted certificate authority.
Installing a commercial SSL certificate in Access Server
This guide shows you how to install a commercial SSL certificate in the Access Server via the Admin UI. But it can also be done via the command line. To be able to install the certificate on your Access Server installation, you will need these files:
- The signed certificate from your certificate authority.
- The CA bundle or intermediary files from your certificate authority.
- The private key you originally created when making the certificate signing request (CSR).
A few notes about these files. The format they should be in is Apache compatible format, also referred to as X509/Base64 or PEM/CER format. If you have mistakenly received files in .p12 or .pfx format or such, then those are of a type that are suitable for Windows platforms, but not for the Linux OpenVPN Access Server product. It is however possible to convert the certificates to the required format using for example the DigiCert Certificate Utility.
The CA (Certificate Authority) bundle, or also called intermediary files, are a set of certificates that complete the chain of trust between your signed certificate for your server, and a root certificate authority that is trusted by web browser and other SSL capable programs. Without these files the certificate may still show up as being untrusted or some errors may show up when trying to verify identity of the server certificate. Sometimes you receive one single file, but in other cases you may receive a number of separate files. You need them to be in one file. Fortunately this can be resolved by opening them up in a text editor like Wordpad or notepad and copying and pasting one after the other into a new file and saving and using that file as the CA bundle or intermediary file from here on in.
The private key must absolutely be the same private key that you originally created and used to create the certificate signing request. You cannot use any other private key with the signed certificate. They are inextricably linked. If you have made the mistake of losing the original private key, your signed certificate is useless and you will have to start over.
To install a commercial SSL certificate, you must first login to the Admin Web UI.
Once logged in, visit the Web Server section in the menu.
Provide the three files necessary for certificate installation, then press the Validate button.
If you have provided all the necessary files correctly, a successful message should appear. Click save.
You may also want to click the Update Running Server button to effect your changes immediately. This may lead to you temporarily losing contact with the web services, but if you close your browser and open it again, it should now connect and show the green padlock if the certificate is installed correctly and trusted.
Recovering stored keys and certificates
The files you have submitted to the Access Server are stored in the configuration database files of the Access Server. In rare cases people have lost these files and need to retrieve them from the Access Server configuration database files. In order to do so you can consult the document describing how to recover SSL web certificates from the config DB.
If you did not provide the necessary files correctly, you may experience some of the problems below.
Certificate doesn’t match private key Your private key does not match the one you have used to sign the CSR that you have submitted to your certificate authority. Make sure you are using the same key file that was used to generate your CSR. If you lost this file, you will need to restart the certificate generation process and ask your certificate authority for a certificate replacement. The private key is unique and cannot be recreated. If you’ve lost it, the signed public certificate also becomes useless.
Problems getting password, bad password read Your private key is encrypted with a passphrase and Access Server does not know how to decrypt the private key (i.e. it does not know what your passphrase is). Decrypt your private key by running the example command below on the command line with the OpenSSL program and then provide Access Server the decrypted private key file. The OpenVPN Access Server does not support using a private key for the web services that is additionally encrypted with a passphrase.
Decrypt a passphrase protected private key with OpenSSL:
openssl rsa -in server.key -out decrypted.key
You will be asked once for your passphrase. The resulting decrypted.key file can be loaded into the OpenVPN Access Server.
PEM_read_bio, no start line This is usually part of an error message like this:
Private Key Load Error [('PEM routines', 'PEM_read_bio', 'no start line')] (OpenSSL.crypto.Error)
This basically means that the private key you have provided is invalid in some way. Make sure that you have provided the correct file, and do not accidentally supply your public certificate as the private key, or vice-versa. The private key field in Access Server only accepts a valid private key.
If you are sure that the file is valid, and Access Server is not accepting the certificate file, it is most likely because of improper formatting of the private key file. For example without line breaks or with linebreaks using a different EOL (End-of-Line) standard that is not acceptable. You may try to manually fix this problem yourself with proper EOL conversion tools, or by contacting your certificate authority for assistance. We often see this problem with certain providers of SSL certificates that generate the private key for you. They may be providing it with Windows-type EOL characters and this can cause a problem. Usually they can help you to obtain a version that is compatible with Linux systems, or you can use a text editing tool to convert the file format to a type that doesn’t contain these additional characters.
Certificate doesn’t match private key, unsupported certificate purpose The file supplied seems like valid keying material, although it doesn’t look like a server certificate was provided. It is possible that the CA bundle and the server certificate were accidentally swapped. Try to swap the order of the CA bundle and the certificate and try again. If this does not work, make sure you are providing the signed certificate you have received from your CA, and not the CSR you have generated on your own machine. The CSR is not needed or wanted by the OpenVPN Access Server, it is only used to do the certificate signing request with your certificate authority.
Certificate Trust Warning: unable to get local issuer certificate This message can occur in a variety of programs that try to verify the identity of a server using its public certificate. It can occur in the Connect Client but it can also occur in a web browser or a test program for SSL connections. The error occurs when the path from your server’s certificate to a trusted root authority certificate could not be established. Certificates are hierarchical and each certificate knows its direct parent above it using a unique fingerprint. Using this method a chain can be formed going from your server certificate, to the certificate issuer, and from there to a (trusted) root authority. Sometimes there are more steps. Sometimes the direct parent is the root authority. But in most cases there are steps in between and these are called intermediaries. If there is one, only one intermediate certificate needs to be added to your chain of certificates, and if there are more, you can copy-paste them into one file, just one after the other, to make an intermediary bundle file that contains all the intermediaries to complete the path of trust. Please note that if you already had a working certificate before, but now have a new one from a different issuer, you will need to update your intermediaries as well.
On the OpenVPN Connect v2 client, the intermediaries are stored on disk with the client and to update this you would need to update the OpenVPN Connect v2. It is therefore best to stick to the same issuer when you need to renew a certificate and your clients are using OpenVPN Connect v2 with server-locked profiles. For user-locked and auto-login it doesn’t make a difference as the web interface only gets called when using server-locked.
On the OpenVPN Connect v3 client, we use the certificate store in the operating system to determine a path of trust.
How to alter the self-signed certificate
If you are using the self-signed certificate and want to keep using it but replace it with a new one, use these commands:
cd /usr/local/openvpn_as/scripts/ ./certool -d /usr/local/openvpn_as/etc/web-ssl --type ca --unique --cn "OpenVPN Web CA" ./certool -d /usr/local/openvpn_as/etc/web-ssl --type server --remove_csr --sn_off --serial 1 --name server --cn vpn.exampletronix.com ./sacli start
Please note that using a self-signed certificate is not as secure as using a valid signed certificate from a certificate authority. You cannot create such signed certificates yourself, you need an external authority that is trusted by default by web browsers and other SSL capable programs to make automatic trusting of your web server’s SSL certificate possible. No matter how you generate self-signed certificates, they will always by default not be trusted by any standard computer system. Only a commercial SSL certificate will make that possible.
The commands given above will have no effect if a commercial SSL certificate is installed on your Access Server as this is stored in the configuration database, and values in the configuration database take precedence over the files stored in the web-ssl directory. Likewise if you have a self-signed certificate, or any certificate, stored in the configuration database, then the files in the web-ssl directory are ignored. If you like you can use the commands in the section below to clear out the certificates from the configuration database. The Access Server will then revert to certificates stored in the web-ssl directory.
How to revert Access Server to a self-signed certificate
If for any reasons you want to uninstall a commercial SSL certificate use the following commands:
cd /usr/local/openvpn_as/scripts/ ./sacli --key "cs.priv_key" ConfigDel ./sacli --key "cs.ca_bundle" ConfigDel ./sacli --key "cs.cert" ConfigDel ./sacli start
You are very likely to receive SSL warnings after you revert to a self-signed SSL certificate, unless the self-signed certificate has been previously manually trusted in your system certificate store(s).