.\" $OpenBSD: ssl.8,v 1.45 2008/12/16 17:40:04 espie Exp $ .\" .\" Copyright (c) 1999 Theo de Raadt, Bob Beck .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: December 16 2008 $ .Dt SSL 8 .Os .Sh NAME .Nm ssl .Nd details for libssl and libcrypto .Sh 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. .Pp The SSL libraries (libssl and libcrypto) implement the .Ar SSL version 2 , .Ar SSL version 3 , and .Ar TLS version 1 protocols. .Ar SSL version 2 and .Ar 3 are most commonly used by the .Ar https protocol for encrypted web transactions, as can be done with .Xr httpd 8 . The libcrypto library is also used by various programs such as .Xr ssh 1 , .Xr sshd 8 , and .Xr isakmpd 8 . .Sh RANDOM DATA SOURCE .Ox uses the .Xr arandom 4 device as the default source for random data when needed by the routines in libcrypto and libssl. If the .Xr 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 .Ar RSA routines failing in applications such as .Xr ssh 1 , and .Xr httpd 8 . .Pp It is important to remember when using a random data source for certificate 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 position to read the same random data used by you to generate keys and certificates. The .Xr arandom 4 device ensures that no two users on the same machine will see the same data. See .Xr openssl 1 for more information on how to use different sources of random data. .Sh SERVER CERTIFICATES The most common uses of .Ar 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 .Pa /etc/ssl directory, with the keys in the .Pa /etc/ssl/private directory. .Pp Private keys can be encrypted using .Ar 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. .Sh GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS To support .Ar https transactions in .Xr httpd 8 you will need to generate an .Ar RSA certificate. .Bd -literal -offset indent # openssl genrsa -out /etc/ssl/private/server.key 1024 .Ed .Pp Or, if you wish the key to be encrypted with a passphrase that you will have to type in when starting servers .Bd -literal -offset indent # openssl genrsa -des3 -out /etc/ssl/private/server.key 1024 .Ed .Pp The next step is to generate a .Ar Certificate Signing Request which is used to get a .Ar Certifying Authority (CA) to sign your certificate. To do this use the command: .Bd -literal -offset indent # openssl req -new -key /etc/ssl/private/server.key \\ -out /etc/ssl/private/server.csr .Ed .Pp This .Pa server.csr file can then be given to .Ar Certifying Authority who will sign the key. .Pp You can also sign the key yourself, using the command: .Bd -literal -offset indent # openssl x509 -req -days 365 -in /etc/ssl/private/server.csr \\ -signkey /etc/ssl/private/server.key -out /etc/ssl/server.crt .Ed .Pp With .Pa /etc/ssl/server.crt and .Pa /etc/ssl/private/server.key in place, you should be able to start .Xr httpd 8 with the .Ar -DSSL flag, enabling .Ar https transactions with your machine on port 443. .Pp 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 .Pa /etc/ssl/server.crt with the certificate signed by your Certifying Authority, and then restarting .Xr httpd 8 .Sh GENERATING DSA SERVER CERTIFICATES Generating a .Ar DSA certificate involves several steps. First, you generate a .Ar DSA parameter set with a command like the following: .Bd -literal -offset indent # openssl dsaparam 1024 -out dsa1024.pem .Ed .Pp Would generate .Ar DSA parameters for 1024 bit .Ar DSA keys, and save them to the file .Pa dsa1024.pem . .Pp Once you have the .Ar DSA parameters generated, you can generate a certificate and unencrypted private key using the command: .Bd -literal -offset indent # openssl req -x509 -nodes -newkey dsa:dsa1024.pem \\ -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem .Ed .Pp To generate an encrypted private key, you would use: .Bd -literal -offset indent # openssl req -x509 -newkey dsa:dsa1024.pem \\ -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem .Ed .Sh USING SSL/TLS WITH SENDMAIL By default, .Xr sendmail 8 expects both the keys and certificates to reside in .Pa /etc/mail/certs , not in the .Pa /etc/ssl directory. The default paths may be overridden in the sendmail.cf file. See .Xr starttls 8 for information on configuring .Xr sendmail 8 to use .Ar SSL/TLS . .Sh SEE ALSO .Xr openssl 1 , .Xr ssh 1 , .Xr ssl 3 , .Xr arandom 4 , .Xr httpd 8 , .Xr isakmpd 8 , .Xr rc 8 , .Xr sendmail 8 , .Xr sshd 8 , .Xr starttls 8 .Sh HISTORY Prior to Sept 21, 2000, there were problems shipping fully functional implementations of these protocols, as such shipment would include shipping .Ar into the United States. .Ar RSA Data Security Inc (RSADSI) held the patent on the .Ar RSA algorithm in the United States, and because of this, free implementations of .Ar RSA were difficult to distribute and propagate. (The .Ar RSA patent was probably more effective at preventing the adoption of widespread international integrated crypto than the much maligned ITAR restrictions were). Prior to .Ox 2.8 , these libraries shipped without the .Ar RSA algorithm -- all such functions were stubbed to fail. Since .Ar RSA is a key component of .Ar SSL version 2 , this meant that .Ar SSL version 2 would not work at all. .Ar SSL version 3 and .Ar TLS version 1 allow for the exchange of keys via mechanisms that do not involve .Ar 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 .Xr ssh 1 uses RSA, so it was similarly encumbered. .Pp For instance, another typical alternative is .Ar DSA , which is not encumbered by commercial patents (and lawyers). .Pp The .Ar https protocol used by web browsers (in modern incarnations) allows for the use of .Ar SSL version 3 and .Ar TLS version 1 , which in theory allows for encrypted web transactions without using .Ar RSA . Unfortunately, all the popular web browsers buy their cryptographic code from .Ar RSADSI . Predictably, .Ar RSADSI would prefer that web browsers used their patented algorithm, and thus their libraries do not implement any .Ar non-RSA cipher and keying combination. The result of this was that while the .Ar 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, .Ox allowed users to download .Ar RSA enabled versions of the shared libssl and libcrypto libraries which allowed users to enable full function 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. .Pp This document first appeared in .Ox 2.5 . .Sh BUGS The world needs more .Ar DSA capable .Ar SSL and .Ar SSH services.