1.\" $OpenBSD: ssl.8,v 1.56 2014/03/13 10:12:11 florian 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 13 2014 $ 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 SSL version 3 39and TLS version 1 protocols. 40SSL and TLS are most commonly used by the HTTPS protocol for encrypted 41web transactions, as can be done with 42.Xr nginx 8 . 43The libcrypto library is also used by various programs such as 44.Xr ssh 1 , 45.Xr sshd 8 , 46and 47.Xr isakmpd 8 . 48.Sh RANDOM DATA SOURCE 49.Ox 50uses the 51.Xr arandom 4 52device as the default source for random data when needed by the routines in 53libcrypto and libssl. 54If the 55.Xr arandom 4 56device does not exist or is not readable, many of the routines will fail. 57This is most commonly seen by users as the RSA routines failing in 58applications such as 59.Xr ssh 1 60and 61.Xr nginx 8 . 62.Pp 63It is important to remember when using a random data source for certificate 64and key generation that the random data source should not be visible by 65people who could duplicate the process and come up with the same result. 66You should ensure that nobody who you don't trust is in a position to read 67the same random data used by you to generate keys and certificates. 68The 69.Xr arandom 4 70device ensures that no two users on the same machine will see the same 71data. 72See 73.Xr openssl 1 74for more information on how to use different sources of random data. 75.Sh SERVER CERTIFICATES 76The most common uses of SSL/TLS will require you to generate a server 77certificate, which is provided by your host as evidence of its identity 78when clients make new connections. 79The certificates reside in the 80.Pa /etc/ssl 81directory, with the keys in the 82.Pa /etc/ssl/private 83directory. 84.Pp 85Private keys can be encrypted using AES and a passphrase to protect their 86integrity should the encrypted file be disclosed. 87However, it is important to note that encrypted server keys mean that the 88passphrase needs to be typed in every time the server is started. 89If a passphrase is not used, you will need to be absolutely sure your 90key file is kept secure. 91.Sh GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS 92To support HTTPS transactions in 93.Xr nginx 8 94you will need to generate an RSA certificate. 95.Bd -literal -offset indent 96# openssl genrsa -out /etc/ssl/private/server.key 2048 97.Ed 98.Pp 99Or, if you wish the key to be encrypted with a passphrase that you will 100have to type in when starting servers 101.Bd -literal -offset indent 102# openssl genrsa -aes256 -out /etc/ssl/private/server.key 2048 103.Ed 104.Pp 105The next step is to generate a Certificate Signing Request (CSR) which is 106used to get a Certificate Authority (CA) to sign your certificate. 107To do this use the command: 108.Bd -literal -offset indent 109# openssl req -new -key /etc/ssl/private/server.key \e 110 -out /etc/ssl/private/server.csr 111.Ed 112.Pp 113This 114.Pa server.csr 115file can then be given to a Certificate Authority who will sign the key. 116.Pp 117You can also sign the key yourself, using the command: 118.Bd -literal -offset indent 119# openssl x509 -sha256 -req -days 365 \e 120 -in /etc/ssl/private/server.csr \e 121 -signkey /etc/ssl/private/server.key \e 122 -out /etc/ssl/server.crt 123.Ed 124.Pp 125With 126.Pa /etc/ssl/server.crt 127and 128.Pa /etc/ssl/private/server.key 129in place, you should be able to start 130.Xr nginx 8 131with SSL configured, enabling HTTPS transactions with your machine on port 443. 132.Pp 133You will most likely want to generate a self-signed certificate in the 134manner above along with your certificate signing request to test your 135server's functionality even if you are going to have the certificate 136signed by another Certificate Authority. 137Once your Certificate Authority returns the signed certificate to you, 138you can switch to using the new certificate by replacing the self-signed 139.Pa /etc/ssl/server.crt 140with the certificate signed by your Certificate Authority, and then 141restarting 142.Xr nginx 8 . 143.Sh GENERATING DSA SERVER CERTIFICATES 144Generating a DSA certificate involves several steps. 145First, generate parameters for DSA keys. 146The following command will generate 1024-bit keys: 147.Bd -literal -offset indent 148# openssl dsaparam 1024 -out dsa1024.pem 149.Ed 150.Pp 151Once you have the DSA parameters generated, you can generate a 152CSR and unencrypted private key using the command: 153.Bd -literal -offset indent 154# openssl req -nodes -newkey dsa:dsa1024.pem \e 155 -out /etc/ssl/dsacert.csr -keyout /etc/ssl/private/dsakey.pem 156.Ed 157.Pp 158To generate an encrypted private key, you would use: 159.Bd -literal -offset indent 160# openssl req -newkey dsa:dsa1024.pem \e 161 -out /etc/ssl/dsacert.csr -keyout /etc/ssl/private/dsakey.pem 162.Ed 163.Pp 164This 165.Pa server.csr 166file can then be given to a CA who will sign the key. 167.Pp 168You can also sign the key yourself, using the command: 169.Bd -literal -offset indent 170# openssl x509 -sha256 -req -days 365 \e 171 -in /etc/ssl/private/dsacert.csr \e 172 -signkey /etc/ssl/private/dsacert.key \e 173 -out /etc/ssl/dsacert.crt 174.Ed 175.Sh GENERATING ECDSA SERVER CERTIFICATES 176First, generate parameters for ECDSA keys. 177The following command will use a NIST/SECG curve over a 384-bit 178prime field: 179.Bd -literal -offset indent 180# openssl ecparam -out ec-secp384r1.pem -name secp384r1 181.Ed 182.Pp 183Once you have the ECDSA parameters generated, you can generate a 184CSR and unencrypted private key using the command: 185.Bd -literal -offset indent 186# openssl req -nodes -newkey ec:ec-secp384r1.pem \e 187 -keyout /etc/ssl/private/eccert.key -new \e 188 -out /etc/ssl/private/eccert.csr 189.Ed 190.Pp 191To generate an encrypted private key, you would use: 192.Bd -literal -offset indent 193# openssl req -newkey ec:ec-secp384r1.pem \e 194 -keyout /etc/ssl/private/eccert.key -new \e 195 -out /etc/ssl/private/eccert.csr 196.Ed 197.Pp 198This 199.Pa eccert.csr 200file can then be given to a CA who will sign the key. 201.Pp 202You can also sign the key yourself, using the command: 203.Bd -literal -offset indent 204# openssl x509 -sha256 -req -days 365 \e 205 -in /etc/ssl/private/eccert.csr \e 206 -signkey /etc/ssl/private/eccert.key \e 207 -out /etc/ssl/eccert.crt 208.Ed 209.Sh USING SSL/TLS WITH SENDMAIL 210By default, 211.Xr sendmail 8 212expects both the keys and certificates to reside in 213.Pa /etc/mail/certs , 214not in the 215.Pa /etc/ssl 216directory. 217The default paths may be overridden in the sendmail.cf file. 218See 219.Xr starttls 8 220for information on configuring 221.Xr sendmail 8 222to use SSL/TLS. 223.Sh SEE ALSO 224.Xr openssl 1 , 225.Xr ssh 1 , 226.Xr ssl 3 , 227.Xr arandom 4 , 228.Xr isakmpd 8 , 229.Xr nginx 8 , 230.Xr rc 8 , 231.Xr sendmail 8 , 232.Xr sshd 8 , 233.Xr starttls 8 234.Sh HISTORY 235Prior to Sept 21, 2000, 236there were problems shipping fully functional implementations of these 237protocols, as such shipment would include shipping 238.Em into 239the United States. 240RSA Data Security Inc (RSADSI) held the patent on the RSA algorithm in the 241United States, and because of this, free implementations of RSA were 242difficult to distribute and propagate. 243(The RSA patent was probably more effective at preventing the adoption of 244widespread international integrated crypto than the much maligned ITAR 245restrictions were.) 246Prior to 247.Ox 2.8 , 248these libraries shipped without the RSA algorithm -- all such functions 249were stubbed to fail. 250Since RSA is a key component of SSL version 2, this meant that SSL version 2512 would not work at all. 252SSL version 3 and TLS version 1 allow for the exchange of keys via 253mechanisms that do not involve RSA, and would work with the shipped version 254of the libraries, assuming both ends could agree to a cipher suite and key 255exchange that did not involve RSA. 256Likewise, the SSH1 protocol in 257.Xr ssh 1 258uses RSA, so it was similarly encumbered. 259.Pp 260For instance, another typical alternative is DSA, which is not encumbered 261by commercial patents (and lawyers). 262.Pp 263The HTTPS protocol used by web browsers (in modern incarnations) allows for 264the use of SSL version 3 and TLS version 1, which in theory allows for 265encrypted web transactions without using RSA. 266Unfortunately, all the popular web browsers buy their cryptographic code 267from RSADSI. 268Predictably, RSADSI would prefer that web browsers used their patented 269algorithm, and thus their libraries do not implement any non-RSA cipher and 270keying combination. 271The result of this was that while the HTTPS protocol allowed for many 272cipher suites that did not require the use of patented algorithms, it was 273very difficult to use these with the popular commercially available 274software. 275Prior to version 2.8, 276.Ox 277allowed users to download RSA enabled versions of the shared libssl and 278libcrypto libraries which allowed users to enable full function without 279recompiling the applications. 280This method is now no longer needed, as the fully functional 281libraries ship with the system. 282However, this entire debacle is worth remembering when choosing 283software and vendors. 284.Pp 285Due to multiple flaws in the protocol, SSL version 2 was disabled in 286.Ox 5.2 . 287Users and programs should use SSL version 3 or TLS version 1 instead. 288.Pp 289This document first appeared in 290.Ox 2.5 . 291