4D Doc Center : Using SSL Protocol

4D v13.4

Using SSL Protocol

The 4D Web server can communicate in secured mode through the SSL protocol (Secured Socket Layer).

SSL Protocol Definition

The SSL protocol has been designed to secure data exchanges between two applications —mainly between a Web server and a browser. This protocol is widely used and is compatible with most Web browsers.

At the network level, the SSL protocol is inserted between the TCP/IP layer (low level) and the HTTP high level protocol. SSL has been designed mainly to work with HTTP.

Network configuration using SSL:

Note: The SSL protocol can also be used to secure standard 4D Server client/server connections as well as SQL server connections. For more information, refer to the section Encrypting Client/Server Connections in the 4D Server Reference manual as well as the Configuration of 4D SQL Server section in the SQL Reference manual.

The SSL protocol is designed to authenticate the sender and receiver and to guarantee the confidentiality and integrity of the exchanged information:

Authentication: The sender and receiver identities are confirmed.
Confidentiality: The sent data is encrypted so that no third person can understand the message.
Integrity: The received data has not been changed, by accident or malevolently.

SSL uses a public key encryption technique based on a pair of asymmetric keys for encryption and decryption: a public key and a private key.
The private key is used to encrypt data. The sender (the web site) does not give it to anyone. The public key is used to decrypt the information and is sent to the receivers (Web browsers) through a certificate. When using SSL with the Internet, the certificate is delivered through a certification authority, such as Verisign®. The Web site pays the Certificate Authority to deliver a certificate which guaranties the server authentication and contains the public key allowing to exchange data in a secured mode.

Note: For more information on the encryption method and the public and private key issues, refer to the ENCRYPT BLOB command description.

How to get a certificate?

A 4D Web server working in secured mode means that you need a digital certificate from a certification authority. This certificate contains various information such as the site ID as well as the public key used to communicate with the site. This certificate is transmitted to the Web browsers connecting to this site. Once the certificate has been identified and accepted, the communication is made in secured mode.

Note: A browser authorizes only the certificates issued by a certification authority referenced in its properties.

The certification authority is chosen according to several criteria. If the certification authority is well known, the certificate will be authorized by many browsers, however the price to pay will be expensive.

To get a SSL certificate:

1. Generate a private key using the GENERATE ENCRYPTION KEYPAIR command.

Warning: For security reasons, the private key should always be kept secret. Actually, it should always remain with the Web server machine. The Key.pem file must be placed in the Database structure folder.

2. Use the GENERATE CERTIFICATE REQUEST command to issue a certificate request.

3. Send the certificate request to the chosen certificate authority.
To fill in a certificate request, you might need to contact the certification authority. The certification authority checks that the information transmitted are correct. The certificate request is generated in a BLOB using the PKCS format. This format allows to copy and paste the keys as text and to send them via E-mail without modifying the key content. For example, you can save the BLOB containing the certificate request in a text document (using the BLOB TO DOCUMENT command), then open and copy and paste its content in a mail or a Web form to be sent to the certification authority.

4. Once you get your certificate, create a text file named “cert.pem” and paste the contents of the certificate into it.
You can receive a certificate in different ways (usually by E-mail or HTML form). The 4D Web Server accepts all platform-related text formats for certificates (Mac OS, PC, Linux...). However, the certificate must be in PKCS format.

5. Place the “cert.pem” file in the Database structure folder.
The Web server can now work in a secured mode. A certificate is valid between 6 months to a year.

SSL installation and activation within 4D

If you want to use the SSL protocol with the 4D Web server, the following components should be installed on the server, at different locations:

4DSLI.DLL (Windows) or 4DSLI.bundle (Mac OS): Secured Layer Interface dedicated to the SSL management.
This file is installed by default, it is placed:
- Under Windows, next to the executable file of the 4D or 4D Server application
- Under Mac OS, in the Native Components subfolder of the 4D or 4D Server package.

key.pem (document containing the private encryption key) and cert.pem (document containing the certificate):
- with 4D in local mode or 4D Server, these files must be placed next to the database structure file
- with 4D in remote mode, these files must be located in the local resources folder of the database on the remote machine (for more information about the location of this folder, refer to the 4D Client Database Folder paragraph in the description of the Get 4D folder command). Note that you must copy these files manually on the remote machine.

Note: 4DSLI is also necessary to use the encryption commands ENCRYPT BLOB and DECRYPT BLOB.

The installation of these elements makes it possible to use SSL for connections to the 4D Web server. However, in order for SSL connections to be accepted by the 4D Web server, you must “activate” the SSL. This parameter is accessible on the Configuration tab of the Web page in the Database Settings:

By default, the SSL connections are allowed. You can uncheck this option if you do not want to use SSL functionalities with your Web server, or if another Web server allowing secure connections is operating on the same machine.

The TCP port dedicated to SSL data exchange is 443 by default. This port number can be modified in the HTTPS Port Number area in order, for example, to reinforce the security of the Web server (for more information about this pont, refer to the Web Server Settings section). The TCP port defined on this page of the Database Settings is used for standard mode Web server connections.

Note: The other settings defined for the 4D Web Server management (password, timeout, cache size, etc.) are applied, regardless of whether or not the server is operating in SSL mode.

Browser connection with SSL

For a Web connection to be carried out in secure mode, the URL sent by the browser simply needs to begin with “https” (instead of “http”).
In this case, a warning dialog appears on the browser. If the user clicks OK, the Web server sends the certificate to the browser.

The encryption algorithm used for the connection is then decided by the browser and the Web server. The server offers several symetric encryption algorithms (RC2, RC4, DES...). The most powerful common algorithm is used.

Warning: The level of encryption allowed depends on current laws in the country of use. The level of encryption offered by 4D Web Server depends on the version of the encryption system library used. By default, 4D provides an "Export" version of the library whereby symetric algorithms are limited to 40 bits.

Management of the connection mode

Using SSL with 4D Web server does not require any specific system configuration. However, you should keep in mind that a SSL Web server can also work in a non-secured mode. The connection mode can switch to another mode if the browser so requires (for example, in the browser URL area, the user can replace “HTTPS” by “HTTP”). The developer can forbid or redirect requests made in a non-secured mode. You can get the current connection mode using the WEB Is secured connection command.