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