5. Using SSL¶
5.1. What is SSL?¶
SSL is a transport level protocol over TCP that is designed to provide communication security in two major ways:
- Encrypt data;
- Authenticate peers.
The first thing does not require any additional explanations and configurations.
The second one is based on cryptographic certificates. Each certificate consists from a public and a private parts. Private Key is a secret part of the certificate. Public key (often referred as Certificate itself) can be shared with anybody.
A certificate can basically be issued by anyone, so to solve a verification problem a trusted third party is required.
This party is called CA (Center Authority). One or both users send their certificates to CA. CA has its own certificate, just like everyone else. CA signs the certificate with its private key and takes responsibilities for all signed certificates.
Public CA key is openly available. Now, user A can download and verify user B’s certificate (if he trusts CA, that is).
Every server that works with SSL should have a certificate.
For client it’s mostly optional. In separate cases a certificate might be required to check user’s identity.
5.2. What can SSL provide?¶
The main benefits from the use of SSL:
|Server with self-signed certificate||Protects from communication sniffing. Does not protect from Man-In-the-Middle attacks (MITM)|
|Server with CA-signed certificate||Protects from communication sniffing. Client can verify server identity. In most cases protects from MITM attacks.|
|Server and client with CA-signed certificate||Both sides can verify each other. This method provides mutual authentication.|
5.3. Using SSL for DB connections¶
5.3.1. Server part¶
Configuring Postgresql with SSL is well documented. You can read it here: http://www.postgresql.org/docs/9.0/static/ssl-tcp.html
All copies of Сerebro client applications are supplied with default built-in CA certificate issued by our company. You may request us to issue an individual certificate for you or verify it if you have one. Please send your requests to mailto://email@example.com or leave a ticket in our helpdesk: https://support.cerebrohq.com.
Your request should contain the following information:
- CN – usually it is an external URL to access the database;
- Company name;
- Name of the employee that would use the certificate;
- Your company phone number. We reserve the right to contact you to confirm any information provided by you;
- Certificate Signing Request (CSR), if you need to have your own certificate signed.
5.3.2. Cerebro client part¶
To enable SSL in Cerebro client application, check the box This server requires a secure connection (SSL) in the Database field of the Set connection options window
5.3.3. Client certificates of your own¶
To access the database you may use client certificates even if they are unsigned or signed by some other third party.
If you insist that your employees and partners must use your certificates, you should provide them with files client[.pg].crt, client[.pg].key and ca.crt. The files must be in PEM format. For reference, you can look at the files provided by us by default. They are located in <Path to Cerebro>/etc folder.
By default, Cerebro looks up user`s folder ($HOME/%APPDATA%)/cerebro for certificate files at first, and then - in <Path to Cerebro>/etc.
Any of these folders should contain only one set of files.
If users have no need to connect to more than one Cerebro database, they may put the certificate files into one of these directories. Otherwise, they need to have a separate folder for each certificate to avoid their accidental overwriting by some other files. Click Connection options on the Cerebro client application login screen to specify the folder with the corresponding certificate.
To set up a certificate directory you need to click Connection options… link at Cerebro login screen. In the opened window you can use plus button to add another connection preset. In Database section you should activate this server requires a secure connection (SSL) checkbox and then set a directory to look for certificate files.
5.4. SSL and Cargador (File Storage)¶
As Cargador provides several different services, the SSL configuration might be a little tricky.
The Cargador services are listed below:
|Cerebro client file navigation||Server||localGate|
|Cerebro client file import||Server||localGate|
|Providing upload and download for external Cargador||Server||foreignGate|
|Upload and download from external Cargador||Client|
Each of these services can be configured to use SSL in its own way.
The Cargador service shares SSL and plain TCP connection on same port. The client and server will decide to use or skip SSL when they establish the connection.
5.4.1. General Cargador SSL settings¶
All Сargador SSL options are set in cargador[.win | linux].conf configuration file. The configuration file has XML format.
You can get full description of the configuration file by executing following command in terminal:
cargador --describe_xml_conf cargador
All generic settings are placed in <config>/<ssl> structure.
Those settings define the defaults for all particular connections.
You have to specify two mandatory parameters: certificate and its private key.
<config> <ssl> <certFile type="string"> — открытая часть сертификата в PEM-формате <certPrivateKey type="string"> — ключ сертификата в PEM- формате <privateKeyPsswd type="string"> — пароль от ключа <mode type="string"> общие режимы работы. Строка вида <key1=value1>[; <key2>=<value2>] method=[disable, ssl23 (*), tls1, ssl2, ssl3] - задает протокол SSL enable = [off, preferred (*), always] - отключить, предпочтительно, всегда <verifyCA type="bool"> — требовать сертификат собеседника подписанный CA <caCertFile type="string"> — файл сертификата CA <verboseInfo type="bool"> — выдавать диагностику по SSL <libraryCrypto type="string"> — путь до библиотеки crypto <librarySSL type="string"> — путь до библиотеки ssl </ssl> </config>
We noticed bugs with SSL.v2 in OpenSSL 0.9.8, 1.0.1, 1.0.1. Therefore, we recommend using SSL v.3 or TLS instead.
5.4.2. Server part of Cargador¶
As shown in the table above, Cargador has four server ports. You may configure those ports for SSL independently.
For each port, you may define the following parameters:
<ssl> <certFile type="string"> <certPrivateKey type="string"> <privateKeyPsswd type="string"> <mode type="string"> режимы работы. enable = [off, preferred (*), always] - отключить, предпочтительно, всегда <verifyCA type="bool"> <verboseInfo type="bool"> </ssl>
Syntax and meaning are the same as for generic configuration, excluding some irrelevant parameters.
In total, four ports are available:
- <config>/<tcpServer>/< foreignGate>/<ssl>
5.4.3. Cargador Client part¶
In most cases, there is no need to change settings in the client application,
except the case when you want to apply client certificates to restrict access to your file storage server.
Here are the steps:
An administrator creates a CA certificate of their own.
This certificate becomes a CA, trusted by corporate Сargador.
In the cargador [.win | linux].conf you should define the following parameter:
/config/tcpServer/foreignGate/ssl/mode : enable=always
In the same file the following is set:
/config/tcpServer/foreignGate/ssl/verifyCA : true
You should issue your own certificate and sign it by your CA.
Apply certificate to your file storage from Cerebro interface.
The parties which need to have access to your Cargador service, must be provided with the CA signed certificates as well. These certificates must be used while registering their file storage in Cerebro.
Attention! From now on, your storage will only be accessible by users from companies which own your certificate.
This model uses client certificates for corporate file storage authentication. You, as well as your partners, specify certificates signed by your CA when registering a file storage in Cerebro database. When attempting to connect, SSL will check if a client certificate is signed by your particular CA.
When generating a certificate, the OU (Organization Unit) field has a special meaning. It encodes usage restrictions for the certificate. Namely, the ability to use the file storage to which the certificate is assigned as an uploading point. This tool allows you to specify who can use your corporate Cargador to upload files and for which projects. The format of the field is:
OU=upload:[*<-любой проект>] | [имя проекта1][:имя проекта2]...
Project names are case-insensitive.
Be careful when creating a self-signed certificate – make sure to give yourself a permission to upload files on any project:
To add a certificate, log in Cerebro, open Administrator window (Main menu/Tools/Administrator…) and switch to the File Storages tab.
Select a file storage and press Import a new certificate button. A new window will appear where you will be able to select certificate and a private key. You may change or delete a certificate at any time.
If you want your business partners from other companies to use your file storage, you must provide them with certificates and private keys created for them and signed by your CA. The partners, in their turn, must log in Cerebro and add your file storage there, specifying its address and applying their certificates. When issuing a certificate you may set its expiration date, if needed.
5.5. Host based authentication (HBA)¶
HBA is another way to restrict undesirable access to Cargador facilities.
HBA is a list of entries. Each entry has the following format:
<host> <from type="ipmask" /> — IP-маска вида <B1.B2.B3.B4/masked> <access type="string"> — тип доступа. Возможны значения вида deny, plain, ssl, any (*) </host>
- If HBA list is empty, access will be implicitly granted.
- When HBA list is not empty, IP address of incoming peer will be consecutively compared to the mask set in from field. If IP address matches connection will be either accepted or denied based on access parameter.
- If IP address does not match any HBA entries, access will be implicitly denied.