The DeepSurface needs a valid HTTPS certificate, signed by a trusted certificate authority, so your browser can securely communicate with the web administration interface. While DeepSurface provides a temporary, self-signed certificate during installation, you should plan on installing a permanent one signed by a trusted Certificate Authority (CA). You may install this at any point after running the deepsurface-install
script. This is only required for the main console installations and is not needed for subordinate scanner installations.
In order to obtain a certificate, you first need a fully qualified domain name associated with your DeepSurface web console host. Certificates cannot generally be issued for IP addresses.
To get a certificate, you must request one from a certificate authority. Your organization may manage an internal certificate authority, which is acceptable for use so long as the CA certificate is configured in your browser. Otherwise, you may need to purchase a certificate from a commercial certificate authority. If your DeepSurface web console will be internet-facing, you could also obtain a free certificate from Let's Encrypt. It is likely someone in your organization is already familiar with the process for obtaining an HTTPS certificate for your specific use case.
The process of getting a certificate from a CA is fairly straightforward. A quick overview is as follows:
To generate the keys for the Certificate Signing Request (CSR), log into your DeepSurface console using the dsadmin
user and run the following command from a terminal prompt:
openssl genrsa -des3 -out server.key 2048Generating RSA private key, 2048 bit long modulus ..........................++++++ .......++++++ e is 65537 (0x10001) Enter pass phrase for server.key:
You can now enter your passphrase. For best security, it should contain at least eight characters. The minimum length when specifying -des3
is four characters. As a best practice it should also include numbers and/or punctuation and not be a word in a dictionary. Also remember that your passphrase is case-sensitive.
Re-type the passphrase to verify. Once you have re-typed it correctly, the server key is generated and stored in the server.key
file.
Now create the insecure key, the one without a passphrase, and shuffle the key names:
openssl rsa -in server.key -out server.key.insecure mv server.key server.key.secure mv server.key.insecure server.key
The insecure key is now named server.key, and you can use this file to generate the CSR without a passphrase.
To create the CSR, run the following command at a terminal prompt:
openssl req -new -key server.key -out server.csr
It will prompt you to enter the passphrase. If you enter the correct passphrase, it will prompt you to enter ‘Company Name’, ‘Site Name’, ‘Email ID’, etc. Once you enter all these details, your CSR will be created and it will be stored in the server.csr file.
You can now submit this CSR file to a CA for processing. The CA will use this CSR file and issue the certificate. You will need to use scp
or sftp
to download the CSR to your workstation and submit it to the CA.
In order to install your newly obtained certificate and private key you'll need to first log in to your console host via SSH to the dsadmin
account (or another account with sudo
privileges). You will need to use scp
or sftp
or a similar mechanism to copy the certificate and key files over to the host and then use the deepsurface-manage-certificates
command (run as root) to install the certificate in a location and format that DeepSurface understands. For more information, see the documentation for this command.
In order to provide secure communications, most protocols use some form of TLS (or its predecessor, SSL). For example, HTTPS security is based on this. In order for this to work, TLS services must present a cryptographic certificate to TLS clients when they initially connect. TLS clients then validate the certificate is legitimate and continue the conversation over secure (encrypted and authentic) channel.
A critical part of the certificate validation process is for TLS clients to ensure they know the identity of the server, which is typically represented as a domain name. The certificate presented by TLS servers contains this domain name and is signed by a trusted certificate authority (CA). The TLS client must (amongst other things) trust the authority used, validate the cryptographic signature on the certificate, and validate that the entity it is communicating with matches the desired host.
Operating systems and browsers come shipped with a list of trusted certificates and CAs. As an example, you can find the list of certificates trusted by your web browser in the settings section under.
In cases where an organization's servers are not exposed to the internet, it can be more challenging to obtain a certificate signed by a trusted commercial/public authority. In this case, it is common for organizations to create their own internal certificate authority for the purpose of signing certificates used only by internal services. In order for this to work, all internal hosts which may interact with these services must have a copy of the internal CA's certificate installed.
Note: It is possible for services to be configured with "self-signed" certificates where there is no explicit certificate authority involved. However, this means TLS clients will typically be unable to validate the authenticity of the certificate, in which case the TLS communications are no more secure than using an unencrypted protocol. It is possible to use Trust on first use (TOFU) mechanisms to partially mitigate this risk, but overall it is best to use certificates signed by an authority that is trusted by all TLS clients.
If you want to know more about TLS and HTTPS digital certificates, here are some helpful links: