1.\" $OpenBSD: ssl.8,v 1.46 2010/03/26 19:30:40 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: March 26 2010 $ 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 RSA SERVER CERTIFICATES FOR WEB SERVERS 105To support 106.Ar https 107transactions in 108.Xr httpd 8 109you will need to generate an 110.Ar RSA 111certificate. 112.Bd -literal -offset indent 113# openssl genrsa -out /etc/ssl/private/server.key 1024 114.Ed 115.Pp 116Or, if you wish the key to be encrypted with a passphrase that you will 117have to type in when starting servers 118.Bd -literal -offset indent 119# openssl genrsa -des3 -out /etc/ssl/private/server.key 1024 120.Ed 121.Pp 122The next step is to generate a 123.Ar Certificate Signing Request 124which is used 125to get a 126.Ar Certifying Authority (CA) 127to sign your certificate. 128To do this use the command: 129.Bd -literal -offset indent 130# openssl req -new -key /etc/ssl/private/server.key \e 131 -out /etc/ssl/private/server.csr 132.Ed 133.Pp 134This 135.Pa server.csr 136file can then be given to 137.Ar Certifying Authority 138who will sign the key. 139.Pp 140You can also sign the key yourself, using the command: 141.Bd -literal -offset indent 142# openssl x509 -req -days 365 -in /etc/ssl/private/server.csr \e 143 -signkey /etc/ssl/private/server.key -out /etc/ssl/server.crt 144.Ed 145.Pp 146With 147.Pa /etc/ssl/server.crt 148and 149.Pa /etc/ssl/private/server.key 150in place, you should be able to start 151.Xr httpd 8 152with the 153.Ar -DSSL 154flag, enabling 155.Ar https 156transactions with your machine on port 443. 157.Pp 158You will most likely want to generate a self-signed certificate in the 159manner above along with your certificate signing request to test your 160server's functionality even if you are going to have the certificate 161signed by another Certifying Authority. 162Once your Certifying Authority returns the signed certificate to you, 163you can switch to using the new certificate by replacing the self-signed 164.Pa /etc/ssl/server.crt 165with the certificate signed by your Certifying Authority, and then 166restarting 167.Xr httpd 8 168.Sh GENERATING DSA SERVER CERTIFICATES 169Generating a 170.Ar DSA 171certificate involves several steps. 172First, you generate a 173.Ar DSA 174parameter set with a command like the following: 175.Bd -literal -offset indent 176# openssl dsaparam 1024 -out dsa1024.pem 177.Ed 178.Pp 179Would generate 180.Ar DSA 181parameters for 1024 bit 182.Ar DSA 183keys, and save them to the 184file 185.Pa dsa1024.pem . 186.Pp 187Once you have the 188.Ar DSA 189parameters generated, you can generate a certificate 190and unencrypted private key using the command: 191.Bd -literal -offset indent 192# openssl req -x509 -nodes -newkey dsa:dsa1024.pem \e 193 -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem 194.Ed 195.Pp 196To generate an encrypted private key, you would use: 197.Bd -literal -offset indent 198# openssl req -x509 -newkey dsa:dsa1024.pem \e 199 -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem 200.Ed 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