1.\" $OpenBSD: ssl.8,v 1.42 2003/06/06 19:28:06 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 September 19, 2001 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. 172One such CA is 173.Ar Thawte Certification 174which you can reach at 175.Ar http://www.thawte.com/ . 176Thawte can currently sign RSA keys for you. 177A procedure is being worked out to allow for DSA keys. 178.Pp 179You can also sign the key yourself, using the command: 180.Bd -literal -offset indent 181# openssl x509 -req -days 365 -in /etc/ssl/private/server.csr \\ 182 -signkey /etc/ssl/private/server.key -out /etc/ssl/server.crt 183.Ed 184.Pp 185With 186.Pa /etc/ssl/server.crt 187and 188.Pa /etc/ssl/private/server.key 189in place, you should be able to start 190.Xr httpd 8 191with the 192.Ar -DSSL 193flag, enabling 194.Ar https 195transactions with your machine on port 443. 196.Pp 197You will most likely want to generate a self-signed certificate in the 198manner above along with your certificate signing request to test your 199server's functionality even if you are going to have the certificate 200signed by another Certifying Authority. 201Once your Certifying Authority returns the signed certificate to you, 202you can switch to using the new certificate by replacing the self-signed 203.Pa /etc/ssl/server.crt 204with the certificate signed by your Certifying Authority, and then 205restarting 206.Xr httpd 8 207.Sh USING SSL/TLS WITH SENDMAIL 208By default, 209.Xr sendmail 8 210expects both the keys and certificates to reside in 211.Pa /etc/mail/certs , 212not in the 213.Pa /etc/ssl 214directory. 215The default paths may be overridden in the sendmail.cf file. 216See 217.Xr starttls 8 218for information on configuring 219.Xr sendmail 8 220to use 221.Ar SSL/TLS . 222.Sh SEE ALSO 223.Xr openssl 1 , 224.Xr ssh 1 , 225.Xr ssl 3 , 226.Xr arandom 4 , 227.Xr httpd 8 , 228.Xr isakmpd 8 , 229.Xr rc 8 , 230.Xr sendmail 8 , 231.Xr sshd 8 , 232.Xr starttls 8 233.Sh HISTORY 234Prior to Sept 21, 2000, 235there were problems shipping fully functional implementations of these 236protocols, as such shipment would include shipping 237.Ar into 238the United States. 239.Ar RSA Data Security Inc (RSADSI) 240held the patent on the 241.Ar RSA 242algorithm in the United States, and because of this, free 243implementations of 244.Ar RSA 245were difficult to distribute and propagate. 246(The 247.Ar RSA 248patent was probably more effective at preventing the adoption of 249widespread international integrated crypto than the much maligned 250ITAR restrictions were). 251Prior to 252.Ox 2.8 , 253these libraries shipped without the 254.Ar RSA 255algorithm -- all such functions 256were stubbed to fail. 257Since 258.Ar RSA 259is a key component of 260.Ar SSL version 2 , 261this 262meant that 263.Ar SSL version 2 264would not work at all. 265.Ar SSL version 3 266and 267.Ar TLS version 1 268allow for the exchange of keys via mechanisms that do not 269involve 270.Ar RSA , 271and would work with the shipped version of the libraries, 272assuming both ends could agree to a cipher suite and key exchange that 273did not involve RSA. 274Likewise, the SSH1 protocol in 275.Xr ssh 1 276uses RSA, so it was similarly encumbered. 277.Pp 278For instance, another typical alternative is 279.Ar DSA , 280which is not encumbered by commercial patents (and lawyers). 281.Pp 282The 283.Ar https 284protocol used by web browsers (in modern incarnations) 285allows for the use of 286.Ar SSL version 3 287and 288.Ar TLS version 1 , 289which in theory allows for encrypted web transactions without using 290.Ar RSA . 291Unfortunately, all the popular web browsers 292buy their cryptographic code from 293.Ar RSADSI . 294Predictably, 295.Ar RSADSI 296would prefer that web browsers used their patented algorithm, and thus 297their libraries do not implement any 298.Ar non-RSA 299cipher and keying combination. 300The result of this was that while the 301.Ar https 302protocol allowed for many cipher suites that did not require the use 303of patented algorithms, it was very difficult to use these with the 304popular commercially available software. 305Prior to version 2.8, 306.Ox 307allowed users to download 308.Ar RSA 309enabled versions of the shared libssl and libcrypto libraries 310which allowed users to enable full function without recompiling 311the applications. 312This method is now no longer needed, as the fully functional 313libraries ship with the system. 314However, this entire debacle is worth remembering when choosing 315software and vendors. 316.Pp 317This document first appeared in 318.Ox 2.5 . 319.Sh BUGS 320The world needs more 321.Ar DSA 322capable 323.Ar SSL 324and 325.Ar SSH 326services. 327