OpenBSD manual page server

Manual Page Search Parameters
SSL(8) System Manager's Manual SSL(8)

ssl — details for libssl and libcrypto

This document describes some of the issues relating to the use of the OpenSSL libssl and libcrypto libraries. This document is intended as an overview of what the libraries do, and what uses them.

The libssl and libcrypto libraries implement the TLS version 1 protocol. It is most commonly used by the HTTPS protocol for encrypted web transactions, as can be done with httpd(8). The libcrypto library is also used by various programs such as ssh(1), sshd(8), and isakmpd(8).

The most common uses of TLS will require you to generate a server certificate, which is provided by your host as evidence of its identity when clients make new connections. The certificates reside in the /etc/ssl directory, with the keys in the /etc/ssl/private directory.

Private keys can be encrypted using AES and a passphrase to protect their integrity should the encrypted file be disclosed. However, it is important to note that encrypted server keys mean that the passphrase needs to be typed in every time the server is started. If a passphrase is not used, you will need to be absolutely sure your key file is kept secure.

To support HTTPS transactions in httpd(8) you will need to generate an RSA certificate. Start by creating a private key of the desired length:

# openssl genrsa -out /etc/ssl/private/server.key 4096

Or, if you wish the key to be encrypted with a passphrase that you will have to type in when starting servers

# openssl genrsa -aes256 -out /etc/ssl/private/server.key 4096

If you are only generating a private key to use with acme-client(1) (for example, with a non-default key length) you may stop here.

Otherwise, the next step is to generate a Certificate Signing Request (CSR) which is used to get a Certificate Authority (CA) to sign your certificate. To do this use the command:

# openssl req -new -key /etc/ssl/private/server.key \
  -out /etc/ssl/private/server.csr

This server.csr file can then be given to a Certificate Authority who will sign the key.

You can also sign the key yourself, using the command:

# openssl x509 -sha256 -req -days 365 \
  -in /etc/ssl/private/server.csr \
  -signkey /etc/ssl/private/server.key \
  -out /etc/ssl/server.crt

Note that standard web browsers do not use the common name of a subject, but instead require that subject alt names are provided. This requires the use of -extfile server.ext when self-signing.

# this is an example server.ext file
subjectAltName=DNS:example.com,DNS:www.example.com

With /etc/ssl/server.crt and /etc/ssl/private/server.key in place, you should be able to start httpd(8) with SSL configured, enabling HTTPS transactions with your machine on port 443.

You will most likely want to generate a self-signed certificate in the manner above along with your certificate signing request to test your server's functionality even if you are going to have the certificate signed by another Certificate Authority. Once your Certificate Authority returns the signed certificate to you, you can switch to using the new certificate by replacing the self-signed /etc/ssl/server.crt with the certificate signed by your Certificate Authority, and then restarting httpd(8).

First, generate a private ECDSA key. The following command will use a NIST/SECG curve over a 384-bit prime field:

# openssl ecparam -name secp384r1 -genkey \
  -noout -out /etc/ssl/private/eccert.key

Note that some Certificate Authorities will only issue certificates for keys generated using prime256v1 parameters.

If you are only generating a private key to use with acme-client(1), you may stop here. Otherwise, the next step is to generate a Certificate Signing Request (CSR) which is used to get a Certificate Authority (CA) to sign your certificate. To do this use the command:

# openssl req -key /etc/ssl/private/eccert.key -new \
  -out /etc/ssl/private/eccert.csr

This eccert.csr file can then be given to a CA who will sign the key.

You can also sign the key yourself, using the command:

# openssl x509 -sha256 -req -days 365 \
  -in /etc/ssl/private/eccert.csr \
  -signkey /etc/ssl/private/eccert.key \
  -out /etc/ssl/eccert.crt

acme-client(1), openssl(1), ssh(1), ssl(3), httpd(8), isakmpd(8), rc(8), smtpd(8), sshd(8), starttls(8)

Prior to Sept 21, 2000, there were problems shipping fully functional implementations of these protocols, as such shipment would include shipping the United States. RSA Data Security Inc (RSADSI) held the patent on the RSA algorithm in the United States, and because of this, free implementations of RSA were difficult to distribute and propagate. (The RSA patent was probably more effective at preventing the adoption of widespread international integrated crypto than the much maligned ITAR restrictions were.) Prior to OpenBSD 2.8, these libraries shipped without the RSA algorithm -- all such functions were stubbed to fail. Since RSA is a key component of SSL version 2, this meant that SSL version 2 would not work at all. SSL version 3 and TLS version 1 allow for the exchange of keys via mechanisms that do not involve RSA, and would work with the shipped version of the libraries, assuming both ends could agree to a cipher suite and key exchange that did not involve RSA. Likewise, the SSH1 protocol in ssh(1) uses RSA, so it was similarly encumbered.

For instance, another typical alternative is DSA, which is not encumbered by commercial patents (and lawyers).

The HTTPS protocol used by web browsers (in modern incarnations) allows for the use of SSL version 3 and TLS version 1, which in theory allows for encrypted web transactions without using RSA. Unfortunately, all the popular web browsers buy their cryptographic code from RSADSI. Predictably, RSADSI would prefer that web browsers used their patented algorithm, and thus their libraries do not implement any non-RSA cipher and keying combination. The result of this was that while the HTTPS protocol allowed for many cipher suites that did not require the use of patented algorithms, it was very difficult to use these with the popular commercially available software. Prior to version 2.8, OpenBSD allowed users to download RSA enabled versions of the shared libssl and libcrypto libraries which allowed users to enable full functionality without recompiling the applications. This method is now no longer needed, as the fully functional libraries ship with the system. However, this entire debacle is worth remembering when choosing software and vendors.

Due to multiple flaws in the protocols, SSL version 2 was removed in OpenBSD 5.2 and SSL version 3 was disabled in OpenBSD 5.7. Users and programs should use TLS version 1.2 instead.

This document first appeared in OpenBSD 2.5.

February 12, 2021 OpenBSD-7.0