Course13:IT Advanced 2 - 08 Custom certificates

From innovaphone wiki
Jump to navigation Jump to search

Why and how custom certificates must be deployed

What certificates are about

Certificates serve to identify a party in a conversation. When talking about myApps, this conversation is a secure TLS connection between myApps (running in a browser or natively) and either the PBX or the Application platform.


Very often, only the server needs to identify to the client. This is the case for example when a client establishes a secure HTTPS connection to a server. In this case, only the server needs to present (and therefore have) a valid certificate. Valid in this case means
  • that the other end trusts the content of the certificate. This happens if it trusts the issuer of the certificate
  • that the name noted in the certificate matches the name used by the client to access the server

In our case, the PBX and the AP are the servers, so they need a certificate that identify themselves and is issued by an authority that is trusted by the client. The certificate is requested and verified by the client.


(Further Hints) Note that failing to install proper certificates creates subtle issues all over the place. However, these issues are not very obvious and therefore hard to debug. So please do yourself and our support team a favour and do not skip this step.

No need to verify the clients identity?

In fact, certificates could also be used to verify the client's identity. When this is done, it is said to be an MTLS (mutual transport level security) connection .


However, using MTLS is optional and it is not done for myApps connections. The AP and PBX use other methods to authenticate the user.

What if we deploy a reverse proxy ?

As we already learned, the RP is used to facilitate remote connections from myApps to the PBX and AP (and other services).

Although in this case the myApps client thinks it is talking to the PBX and the AP, technically it does not. Instead, it talks to the RP which in turn establishes separate connections to the target server on behalf of the myApps client.


So the RP's certificate needs to identify it as both being the PBX and the AP. How can that be achieved?

Fortunately, there is what is known as a wildcard certificate. Instead of specifying a certain name (e.g. apps.dvl-ckl2.net), it specifies a whole class of names and is therefore considered valid for all of them. This is done by including a star (*) as part of the name in the certificate (e.g. *.dvl-ckl2.net).

So what is the bottom line of all that?

The bottom line is that you need to
  • create or purchase a valid wildcard certificate that matches your domain. So if your domain is domain.tld then the certificate must be valid for *.domain.tld
  • you must install this certificate on
    1. all of your APs
    2. all of your PBXs (master and slaves)
    3. your RP

Wait a moment, it is possible to create the wildcard certificate myself?

In fact, if you have access to a certificate authority, then you can create your own certificates. For example, if you run a windows domain, then you have a certificate authority and can do this.

However, this would require that all of the possible myApps clients actually accept your certificate authority, including all browsers and all mobile phones. This may be the case in certain scenarios, however, generally this is not the case.

So you need to purchase and install it on your devices.

Certificate properties

To create or purchase a working certificate, you need to ensure the following properties
  • the certificate's name must match the domain name of your devices. According to www.png RFC2459,
    • if your domain is dvl-ckl2.net and your AP therefore has the DNS name apps.dvl-ckl2.net, then the certificate's name must be *.dvl-ckl2.net
    • However, if you use second-level sub-domains, e.g. apps.customer.dvl-ckl2.net, then the certificate's name must be *.customer.dvl-ckl2.net
  • the length of the public key must not exceed 2048 bits. This is to limit the CPU consumption on our devices, see fish-help.png Certificate management for details
  • for the same reason, SHA224 or SHA256 should be used as hashes
  • likewise, the signature algorithm should be SHA-256 with RSA encryption
  • the certificate usage modes should include Digital Signature, Key Encipherment, Server Authentication and Client Authentication

Certificate file format

With our devices, you will need your certificate in wikipedia.ico PEM file format.

This is a text (although not human readable) file format that looks something like
-----BEGIN CERTIFICATE-----
MIIFtjCCBJ6gAwIBAgISBLvb8dpwGMTMI+CmwF/fbz
...
YmeOFDBrd/yDp/n1wgFftinghKZYxAXrH+8=
-----END CERTIFICATE-----
This is a public key. However, you must make sure that in this file, there is not only the public key of your wildcard certificate. It also needs to include the complete certificate chain down to the certificate issuer. If so, you will see at least two -----BEGIN CERTIFICATE----- sections in your file.

Finally, also the private key of your wildcard certificate must be present in your file (being the last component). It looks slightly different:
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAwVQr+9xeC/8+zAbvz8Wnyu07Cat2JroKHPWrR/WWz0mJ4NFv
lSThAsTvXwSd1EnMiCA7Ur6FQffaiGDoKzIlNAK0kCvdKACILtH3ZpdojhNRZOFR
...
yQscYqtERSst9RywNEGpWBjdPNYZrCX05Ju42fxEAImP67N2a23R+Q==
-----END RSA PRIVATE KEY-----

(Further Hints) You must absolutely make sure that this private key information is not disclosed to anybody else! The public keys however are not sensitive information and you may share them with anybody you like.

Depending on your certificate supplier, you may have received a single PEM file with all necessary components. However, you may also have received separate files (which for example might be called cert.pem for your public key, chain.pem for the certificate chain and privkey.pem for your private key). If so, simply create a fourth file where you concatenate your public key, the certificate chain and your private key.

(Further Hints) Remember to keep this file in a safe place.

What if you don't have a .pem file ?

If you don't have a .pem file at hand but a .pfx, you can convert it using openssl:
openssl pkcs12 -in file.pfx -out file.pem -nodes
For more information, refer to the www.png openssl documentation .


Certificate chain order

The chain of public keys in your PEM file (the certificate chain) must be
  • complete and
  • properly sorted

Completeness

To understand the completeness of a certificate chain, you need to understand that each certificate is derived from another certificate. The parent certificate is known as the issuer. In order to be complete, the certificate chain must include the public key of the certificate itself, the public key of it's issuer, the public key of the issuer of the issuer and so forth.

Of course, the chain is not endless. It ends with a certificate that is issued by itself (a.k.a self-signed). This certificate is known as the root certificate while the ones in between are known as intermediate certificates.

Sort order

The public keys in your chain must be sorted so that they start with the certificate itself, followed by the issuer, followed by the issuers issuer and so forth down to the root certificate. At the end, the private key of the certificate itself must be present. No other private keys must be present.

See fish-help.png Concept App Platform for an example.

Missing root certificate

If you receive only the public key of your certificate, ask for the complete certificate chain. Sometimes however, you will receive the almost complete chain with the root certificate missing. This is because valid root certificates are considered well-known and therefore usually do not need to be installed (as they are already present in modern browsers).

In this case, you can safely search the web for a downloadable PEM version of the root certificate's public key.


Installing your certificate on a PBX or RP

On innovaphone devices, you can install a new so-called device certificate in the advanced UI at General/Certificates. You screenshot.png select your PEM file in the Device certificate section and press the Upload button then.

After uploading, you see that screenshot.png the device certificate has changed (don't be confused by the certificate's name pappstrasse.ckls.net in the screenshot, it is not a valid wildcard certificate name - you meanwhile know better smile ).

You finally should add the root certificate's public key to the trust list of the device. To do that, you screenshot.png tick the check-mark next to the root certificate and click on Trust.

In the end, it should look similar to this:


At this point, you can nicely check that your certificate is good (i.e. complete and ordered). Note that the certificate chain is displayed in reverse order though (starting with the root certificate's public key as opposed to your PEM file, where it needs to be in the reverse order).

(Further Hints) Remember that you have to do this on all of your PBXs (master and slaves) as well as on your RP.

Installing your certificate on the AP

To install your wildcard certificate on your Application platform, you need to start the AP manager, go to Settings / Security and screenshot.png click on Click to select a new web server certificate (PEM format).

The AP however is a bit more picky than other innovaphone devices are when it comes to installing a device certificate. In our case, it will complain if the keys in the PEM file are either unordered or incomplete. It will screenshot.png complain about the certificate chain being invalid. Admittedly, this is not very specific but as you have already verified your PEM file when you uploaded it to the PBX, you won't run into this issue anyway tongueout (if you nevertheless experience this issue, re-read sections Certificate file format and Certificate chain order above).

If the PEM file was good, there is simply no feedback at all (so no news is good news here). However you can still verify the certificate using your browser. Simply access your AP with a browser (using something like https://apps.dvl-ckl2.net) and have the site's certificate displayed (usually using a lock symbol next to the browser's address line).

(Further Hints) If you have uploaded a bad certificate to your AP, you can uninstall it using the procedure described in fish-help.png Concept App Platform.