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