MirOS Manual: ssl(8)

SSL(8)                   BSD System Manager's Manual                    SSL(8)

NAME

     ssl - details for libssl and libcrypto

DESCRIPTION

     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 SSL libraries (libssl and libcrypto) implement the SSL version 2, SSL
     version 3, and TLS version 1 protocols. SSL version 2 and 3 are most com-
     monly used by the https protocol for encrypted web transactions, as can
     be done with httpd(8). The libcrypto library is also used by various pro-
     grams such as ssh(1), sshd(8), and isakmpd(8).

RANDOM DATA SOURCE

     OpenBSD uses the arandom(4) device as the default source for random data
     when needed by the routines in libcrypto and libssl. If the arandom(4)
     device does not exist or is not readable, many of the routines will fail.
     This is most commonly seen by users as the RSA routines failing in appli-
     cations such as ssh(1), and httpd(8).

     It is important to remember when using a random data source for certifi-
     cate and key generation that the random data source should not be visible
     by people who could duplicate the process and come up with the same
     result. You should ensure that nobody who you don't trust is in a posi-
     tion to read the same random data used by you to generate keys and certi-
     ficates. The arandom(4) device ensures that no two users on the same
     machine will see the same data. See openssl(1) for more information on
     how to use different sources of random data.

SERVER CERTIFICATES

     The most common uses of SSL/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 3DES 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.

GENERATING DSA SERVER CERTIFICATES

     Generating a DSA certificate involves several steps. First, you generate
     a DSA parameter set with a command like the following:

           # openssl dsaparam 1024 -out dsa1024.pem

     Would generate DSA parameters for 1024 bit DSA keys, and save them to the
     file dsa1024.pem.

     Once you have the DSA parameters generated, you can generate a certifi-
     cate and unencrypted private key using the command:

           # openssl req -x509 -nodes -newkey dsa:dsa1024.pem \
             -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem

     To generate an encrypted private key, you would use:

           # openssl req -x509 -newkey dsa:dsa1024.pem \
             -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem

GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS

     To support https transactions in httpd(8) you will need to generate an
     RSA certificate.

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

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

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

     The next step is to generate a Certificate Signing Request which is used
     to get a Certifying 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 Certifying Authority who will
     sign the key.

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

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

     With /etc/ssl/server.crt and /etc/ssl/private/server.key in place, you
     should be able to start httpd(8) with the -DSSL flag, 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 Certifying Authority. Once your Certifying 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 Certifying Authority, and then restarting
     httpd(8)

USING SSL/TLS WITH SENDMAIL
     By default, sendmail(8) expects both the keys and certificates to reside
     in /etc/mail/certs, not in the /etc/ssl directory. The default paths may
     be overridden in the sendmail.cf file. See starttls(8) for information on
     configuring sendmail(8) to use SSL/TLS.

SEE ALSO

     openssl(1), ssh(1), ssl(3), arandom(4), httpd(8), isakmpd(8), rc(8),
     sendmail(8), sshd(8), starttls(8)

HISTORY

     Prior to Sept 21, 2000, there were problems shipping fully functional im-
     plementations of these protocols, as such shipment would include shipping
     into the United States. RSA Data Security Inc (RSADSI) held the patent on
     the RSA algorithm in the United States, and because of this, free imple-
     mentations 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 ci-
     pher 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. Predict-
     ably, RSADSI would prefer that web browsers used their patented algo-
     rithm, 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 commer-
     cially available software. Prior to version 2.8, OpenBSD allowed users to
     download RSA enabled versions of the shared libssl and libcrypto li-
     braries which allowed users to enable full function without recompiling
     the applications. This method is now no longer needed, as the fully func-
     tional libraries ship with the system. However, this entire debacle is
     worth remembering when choosing software and vendors.

     This document first appeared in OpenBSD 2.5.

BUGS

     The world needs more DSA capable SSL and SSH services.

MirOS BSD #10-current         September 19, 2001                             2

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.