14.6. OpenSSL

Written by Tom Rhodes.

OpenSSL is an open source implementation of the SSL and TLS protocols. It provides an encryption transport layer on top of the normal communications layer, allowing it to be intertwined with many network applications and services.

The version of OpenSSL included in FreeBSD supports the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols and can be used as a general cryptographic library.

OpenSSL is often used to encrypt authentication of mail clients and to secure web based transactions such as credit card payments. Some ports, such as www/apache24 and databases/postgresql91-server, include a compile option for building with OpenSSL. If selected, the port will add support using the security/openssl port. To instead have the port compile against the built in version of OpenSSL, include WITH_OPENSSL_BASE when compiling in OpenSSL support.

Another common use of OpenSSL is to provide certificates for use with software applications. Certificates can be used to verify the credentials of a company or individual. If a certificate has not been signed by an external Certificate Authority (CA), such as http://www.verisign.com, the application that uses the certificate will produce a warning. There is a cost associated with obtaining a signed certificate and using a signed certificate is not mandatory as certificates can be self-signed. However, using an external authority will prevent warnings and can put users at ease.

This section demonstrates how to create and use certificates on a FreeBSD system. Refer to Section 28.5.2, “Configuring an LDAP Server” for an example of how to create a CA for signing one's own certificates.

14.6.1. Generating Certificates

To generate a certificate, the following command is available:

# openssl req -new -nodes -out req.pem -keyout cert.pem
Generating a 1024 bit RSA private key
................++++++
.......................................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:PA
Locality Name (eg, city) []:Pittsburgh
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Company
Organizational Unit Name (eg, section) []:Systems Administrator
Common Name (eg, YOUR name) []:localhost.example.org
Email Address []:trhodes@FreeBSD.org

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:SOME PASSWORD
An optional company name []:Another Name

Notice the response directly after the Common Name prompt shows a domain name. This prompt requires a server name to be entered for verification purposes and placing anything but a domain name yields a useless certificate. Other options, such as the expire time and alternate encryption algorithms, are available. A complete list of options is described in openssl(1).

Two files should now exist in the directory in which this command was issued. The certificate request, req.pem, may be sent to a CA who will validate the entered credentials, sign the request, and return the signed certificate. The second file is named cert.pem and is the private key for the certificate and should be protected at all costs. If this falls in the hands of others it can be used to impersonate the user or the server.

In cases where a signature from a CA is not required, a self signed certificate can be created. First, generate the RSA key:

# openssl dsaparam -rand -genkey -out myRSA.key 1024

Next, generate the CA key:

# openssl gendsa -des3 -out myca.key myRSA.key

Use this key to create the certificate:

# openssl req -new -x509 -days 365 -key myca.key -out new.crt

Two new files should appear in the directory: a certificate authority signature file, myca.key and the certificate itself, new.crt. These should be placed in a directory, preferably under /etc, which is readable only by root. Permissions of 0700 are appropriate and can be set using chmod(1).

14.6.2. Using Certificates

One use for a certificate is to encrypt connections to the Sendmail MTA. This prevents the use of clear text authentication for users who send mail via the local MTA.

Note:

Some MUAs will display error if the user has not installed the certificate locally. Refer to the documentation included with the software for more information on certificate installation.

To configure Sendmail, the following lines should be placed in the local .mc file:

dnl SSL Options
define(`confCACERT_PATH',`/etc/certs')dnl
define(`confCACERT',`/etc/certs/new.crt')dnl
define(`confSERVER_CERT',`/etc/certs/new.crt')dnl
define(`confSERVER_KEY',`/etc/certs/myca.key')dnl
define(`confTLS_SRV_OPTIONS', `V')dnl

In this example, /etc/certs/ stores the certificate and key files locally. After saving the edits, rebuild the local .cf file by typing make install within /etc/mail. Follow that up with make restart which should start the Sendmail daemon.

If all went well, there will be no error messages in /var/log/maillog and Sendmail will show up in the process list.

For a simple test, connect to the mail server using telnet(1):

# telnet example.com 25
Trying 192.0.34.166...
Connected to example.com.
Escape character is '^]'.
220 example.com ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT)
ehlo example.com
250-example.com Hello example.com [192.0.34.166], pleased to meet you
250-ENHANCEDSTATUSCODES
250-PIPELINING
250-8BITMIME
250-SIZE
250-DSN
250-ETRN
250-AUTH LOGIN PLAIN
250-STARTTLS
250-DELIVERBY
250 HELP
quit
221 2.0.0 example.com closing connection
Connection closed by foreign host.

If the STARTTLS line appears in the output, everything is working correctly.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.