1.\" $OpenBSD: ssl.8,v 1.44 2007/05/31 19:19:59 jmc Exp $ 2.\" 3.\" Copyright (c) 1999 Theo de Raadt, Bob Beck 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd $Mdocdate: May 31 2007 $ 27.Dt SSL 8 28.Os 29.Sh NAME 30.Nm ssl 31.Nd details for libssl and libcrypto 32.Sh DESCRIPTION 33This document describes some of the issues relating to the use of 34the OpenSSL libssl and libcrypto libraries. 35This document is intended as an overview of what the libraries do, 36and what uses them. 37.Pp 38The SSL libraries (libssl and libcrypto) implement the 39.Ar SSL version 2 , 40.Ar SSL version 3 , 41and 42.Ar TLS version 1 43protocols. 44.Ar SSL version 2 45and 46.Ar 3 47are most 48commonly used by the 49.Ar https 50protocol for encrypted web transactions, as can be done with 51.Xr httpd 8 . 52The libcrypto library is also used by various programs such as 53.Xr ssh 1 , 54.Xr sshd 8 , 55and 56.Xr isakmpd 8 . 57.Sh RANDOM DATA SOURCE 58.Ox 59uses the 60.Xr arandom 4 61device as the default source for random data when needed by the routines in 62libcrypto and libssl. 63If the 64.Xr arandom 4 65device does not exist or is not readable, many of the routines will fail. 66This is most commonly seen by users as the 67.Ar RSA 68routines failing in applications such as 69.Xr ssh 1 , 70and 71.Xr httpd 8 . 72.Pp 73It is important to remember when using a random data source for certificate 74and key generation that the random data source should not be visible by 75people who could duplicate the process and come up with the same result. 76You should ensure that nobody who you don't trust is in a position to read 77the same random data used by you to generate keys and certificates. 78The 79.Xr arandom 4 80device ensures that no two users on the same machine will see the same 81data. 82See 83.Xr openssl 1 84for more information on how to use different sources of random data. 85.Sh SERVER CERTIFICATES 86The most common uses of 87.Ar SSL/TLS 88will require you to generate a server certificate, which is provided by your 89host as evidence of its identity when clients make new connections. 90The certificates reside in the 91.Pa /etc/ssl 92directory, with the keys in the 93.Pa /etc/ssl/private 94directory. 95.Pp 96Private keys can be encrypted using 97.Ar 3DES 98and a passphrase to protect their integrity should the encrypted file 99be disclosed. 100However, it is important to note that encrypted server keys mean that the 101passphrase needs to be typed in every time the server is started. 102If a passphrase is not used, you will need to be absolutely sure your 103key file is kept secure. 104.Sh GENERATING DSA SERVER CERTIFICATES 105Generating a 106.Ar DSA 107certificate involves several steps. 108First, you generate a 109.Ar DSA 110parameter set with a command like the following: 111.Bd -literal -offset indent 112# openssl dsaparam 1024 -out dsa1024.pem 113.Ed 114.Pp 115Would generate 116.Ar DSA 117parameters for 1024 bit 118.Ar DSA 119keys, and save them to the 120file 121.Pa dsa1024.pem . 122.Pp 123Once you have the 124.Ar DSA 125parameters generated, you can generate a certificate 126and unencrypted private key using the command: 127.Bd -literal -offset indent 128# openssl req -x509 -nodes -newkey dsa:dsa1024.pem \\ 129 -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem 130.Ed 131.Pp 132To generate an encrypted private key, you would use: 133.Bd -literal -offset indent 134# openssl req -x509 -newkey dsa:dsa1024.pem \\ 135 -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem 136.Ed 137.Sh GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS 138To support 139.Ar https 140transactions in 141.Xr httpd 8 142you will need to generate an 143.Ar RSA 144certificate. 145.Bd -literal -offset indent 146# openssl genrsa -out /etc/ssl/private/server.key 1024 147.Ed 148.Pp 149Or, if you wish the key to be encrypted with a passphrase that you will 150have to type in when starting servers 151.Bd -literal -offset indent 152# openssl genrsa -des3 -out /etc/ssl/private/server.key 1024 153.Ed 154.Pp 155The next step is to generate a 156.Ar Certificate Signing Request 157which is used 158to get a 159.Ar Certifying Authority (CA) 160to sign your certificate. 161To do this use the command: 162.Bd -literal -offset indent 163# openssl req -new -key /etc/ssl/private/server.key \\ 164 -out /etc/ssl/private/server.csr 165.Ed 166.Pp 167This 168.Pa server.csr 169file can then be given to 170.Ar Certifying Authority 171who will sign the key. 172.Pp 173You can also sign the key yourself, using the command: 174.Bd -literal -offset indent 175# openssl x509 -req -days 365 -in /etc/ssl/private/server.csr \\ 176 -signkey /etc/ssl/private/server.key -out /etc/ssl/server.crt 177.Ed 178.Pp 179With 180.Pa /etc/ssl/server.crt 181and 182.Pa /etc/ssl/private/server.key 183in place, you should be able to start 184.Xr httpd 8 185with the 186.Ar -DSSL 187flag, enabling 188.Ar https 189transactions with your machine on port 443. 190.Pp 191You will most likely want to generate a self-signed certificate in the 192manner above along with your certificate signing request to test your 193server's functionality even if you are going to have the certificate 194signed by another Certifying Authority. 195Once your Certifying Authority returns the signed certificate to you, 196you can switch to using the new certificate by replacing the self-signed 197.Pa /etc/ssl/server.crt 198with the certificate signed by your Certifying Authority, and then 199restarting 200.Xr httpd 8 201.Sh USING SSL/TLS WITH SENDMAIL 202By default, 203.Xr sendmail 8 204expects both the keys and certificates to reside in 205.Pa /etc/mail/certs , 206not in the 207.Pa /etc/ssl 208directory. 209The default paths may be overridden in the sendmail.cf file. 210See 211.Xr starttls 8 212for information on configuring 213.Xr sendmail 8 214to use 215.Ar SSL/TLS . 216.Sh SEE ALSO 217.Xr openssl 1 , 218.Xr ssh 1 , 219.Xr ssl 3 , 220.Xr arandom 4 , 221.Xr httpd 8 , 222.Xr isakmpd 8 , 223.Xr rc 8 , 224.Xr sendmail 8 , 225.Xr sshd 8 , 226.Xr starttls 8 227.Sh HISTORY 228Prior to Sept 21, 2000, 229there were problems shipping fully functional implementations of these 230protocols, as such shipment would include shipping 231.Ar into 232the United States. 233.Ar RSA Data Security Inc (RSADSI) 234held the patent on the 235.Ar RSA 236algorithm in the United States, and because of this, free 237implementations of 238.Ar RSA 239were difficult to distribute and propagate. 240(The 241.Ar RSA 242patent was probably more effective at preventing the adoption of 243widespread international integrated crypto than the much maligned 244ITAR restrictions were). 245Prior to 246.Ox 2.8 , 247these libraries shipped without the 248.Ar RSA 249algorithm -- all such functions 250were stubbed to fail. 251Since 252.Ar RSA 253is a key component of 254.Ar SSL version 2 , 255this 256meant that 257.Ar SSL version 2 258would not work at all. 259.Ar SSL version 3 260and 261.Ar TLS version 1 262allow for the exchange of keys via mechanisms that do not 263involve 264.Ar RSA , 265and would work with the shipped version of the libraries, 266assuming both ends could agree to a cipher suite and key exchange that 267did not involve RSA. 268Likewise, the SSH1 protocol in 269.Xr ssh 1 270uses RSA, so it was similarly encumbered. 271.Pp 272For instance, another typical alternative is 273.Ar DSA , 274which is not encumbered by commercial patents (and lawyers). 275.Pp 276The 277.Ar https 278protocol used by web browsers (in modern incarnations) 279allows for the use of 280.Ar SSL version 3 281and 282.Ar TLS version 1 , 283which in theory allows for encrypted web transactions without using 284.Ar RSA . 285Unfortunately, all the popular web browsers 286buy their cryptographic code from 287.Ar RSADSI . 288Predictably, 289.Ar RSADSI 290would prefer that web browsers used their patented algorithm, and thus 291their libraries do not implement any 292.Ar non-RSA 293cipher and keying combination. 294The result of this was that while the 295.Ar https 296protocol allowed for many cipher suites that did not require the use 297of patented algorithms, it was very difficult to use these with the 298popular commercially available software. 299Prior to version 2.8, 300.Ox 301allowed users to download 302.Ar RSA 303enabled versions of the shared libssl and libcrypto libraries 304which allowed users to enable full function without recompiling 305the applications. 306This method is now no longer needed, as the fully functional 307libraries ship with the system. 308However, this entire debacle is worth remembering when choosing 309software and vendors. 310.Pp 311This document first appeared in 312.Ox 2.5 . 313.Sh BUGS 314The world needs more 315.Ar DSA 316capable 317.Ar SSL 318and 319.Ar SSH 320services. 321