1.\" $OpenBSD: ssl.8,v 1.64 2016/06/06 15:26:04 sthen 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 6 2016 $ 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 libssl and libcrypto libraries implement the TLS version 1 protocol. 39It is most commonly used by the HTTPS protocol for encrypted 40web transactions, as can be done with 41.Xr httpd 8 . 42The libcrypto library is also used by various programs such as 43.Xr ssh 1 , 44.Xr sshd 8 , 45and 46.Xr isakmpd 8 . 47.Sh SERVER CERTIFICATES 48The most common uses of TLS will require you to generate a server 49certificate, which is provided by your host as evidence of its identity 50when clients make new connections. 51The certificates reside in the 52.Pa /etc/ssl 53directory, with the keys in the 54.Pa /etc/ssl/private 55directory. 56.Pp 57Private keys can be encrypted using AES and a passphrase to protect their 58integrity should the encrypted file be disclosed. 59However, it is important to note that encrypted server keys mean that the 60passphrase needs to be typed in every time the server is started. 61If a passphrase is not used, you will need to be absolutely sure your 62key file is kept secure. 63.Sh GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS 64To support HTTPS transactions in 65.Xr httpd 8 66you will need to generate an RSA certificate. 67.Bd -literal -offset indent 68# openssl genrsa -out /etc/ssl/private/server.key 2048 69.Ed 70.Pp 71Or, if you wish the key to be encrypted with a passphrase that you will 72have to type in when starting servers 73.Bd -literal -offset indent 74# openssl genrsa -aes256 -out /etc/ssl/private/server.key 2048 75.Ed 76.Pp 77The next step is to generate a Certificate Signing Request (CSR) which is 78used to get a Certificate Authority (CA) to sign your certificate. 79To do this use the command: 80.Bd -literal -offset indent 81# openssl req -new -key /etc/ssl/private/server.key \e 82 -out /etc/ssl/private/server.csr 83.Ed 84.Pp 85This 86.Pa server.csr 87file can then be given to a Certificate Authority who will sign the key. 88.Pp 89You can also sign the key yourself, using the command: 90.Bd -literal -offset indent 91# openssl x509 -sha256 -req -days 365 \e 92 -in /etc/ssl/private/server.csr \e 93 -signkey /etc/ssl/private/server.key \e 94 -out /etc/ssl/server.crt 95.Ed 96.Pp 97With 98.Pa /etc/ssl/server.crt 99and 100.Pa /etc/ssl/private/server.key 101in place, you should be able to start 102.Xr httpd 8 103with SSL configured, enabling HTTPS transactions with your machine on port 443. 104.Pp 105You will most likely want to generate a self-signed certificate in the 106manner above along with your certificate signing request to test your 107server's functionality even if you are going to have the certificate 108signed by another Certificate Authority. 109Once your Certificate Authority returns the signed certificate to you, 110you can switch to using the new certificate by replacing the self-signed 111.Pa /etc/ssl/server.crt 112with the certificate signed by your Certificate Authority, and then 113restarting 114.Xr httpd 8 . 115.Sh GENERATING ECDSA SERVER CERTIFICATES 116First, generate parameters for ECDSA keys. 117The following command will use a NIST/SECG curve over a 384-bit 118prime field: 119.Bd -literal -offset indent 120# openssl ecparam -out ec-secp384r1.pem -name secp384r1 121.Ed 122.Pp 123Once you have the ECDSA parameters generated, you can generate a 124CSR and unencrypted private key using the command: 125.Bd -literal -offset indent 126# openssl req -nodes -newkey ec:ec-secp384r1.pem \e 127 -keyout /etc/ssl/private/eccert.key -new \e 128 -out /etc/ssl/private/eccert.csr 129.Ed 130.Pp 131To generate an encrypted private key, you would use: 132.Bd -literal -offset indent 133# openssl req -newkey ec:ec-secp384r1.pem \e 134 -keyout /etc/ssl/private/eccert.key -new \e 135 -out /etc/ssl/private/eccert.csr 136.Ed 137.Pp 138This 139.Pa eccert.csr 140file can then be given to a CA who will sign the key. 141.Pp 142You can also sign the key yourself, using the command: 143.Bd -literal -offset indent 144# openssl x509 -sha256 -req -days 365 \e 145 -in /etc/ssl/private/eccert.csr \e 146 -signkey /etc/ssl/private/eccert.key \e 147 -out /etc/ssl/eccert.crt 148.Ed 149.Sh SEE ALSO 150.Xr openssl 1 , 151.Xr ssh 1 , 152.Xr ssl 3 , 153.Xr httpd 8 , 154.Xr isakmpd 8 , 155.Xr rc 8 , 156.Xr smtpd 8 , 157.Xr sshd 8 , 158.Xr starttls 8 159.Sh HISTORY 160Prior to Sept 21, 2000, 161there were problems shipping fully functional implementations of these 162protocols, as such shipment would include shipping 163.Em into 164the United States. 165RSA Data Security Inc (RSADSI) held the patent on the RSA algorithm in the 166United States, and because of this, free implementations of RSA were 167difficult to distribute and propagate. 168(The RSA patent was probably more effective at preventing the adoption of 169widespread international integrated crypto than the much maligned ITAR 170restrictions were.) 171Prior to 172.Ox 2.8 , 173these libraries shipped without the RSA algorithm -- all such functions 174were stubbed to fail. 175Since RSA is a key component of SSL version 2, this meant that SSL version 1762 would not work at all. 177SSL version 3 and TLS version 1 allow for the exchange of keys via 178mechanisms that do not involve RSA, and would work with the shipped version 179of the libraries, assuming both ends could agree to a cipher suite and key 180exchange that did not involve RSA. 181Likewise, the SSH1 protocol in 182.Xr ssh 1 183uses RSA, so it was similarly encumbered. 184.Pp 185For instance, another typical alternative is DSA, which is not encumbered 186by commercial patents (and lawyers). 187.Pp 188The HTTPS protocol used by web browsers (in modern incarnations) allows for 189the use of SSL version 3 and TLS version 1, which in theory allows for 190encrypted web transactions without using RSA. 191Unfortunately, all the popular web browsers buy their cryptographic code 192from RSADSI. 193Predictably, RSADSI would prefer that web browsers used their patented 194algorithm, and thus their libraries do not implement any non-RSA cipher and 195keying combination. 196The result of this was that while the HTTPS protocol allowed for many 197cipher suites that did not require the use of patented algorithms, it was 198very difficult to use these with the popular commercially available 199software. 200Prior to version 2.8, 201.Ox 202allowed users to download RSA enabled versions of the shared libssl and 203libcrypto libraries which allowed users to enable full functionality without 204recompiling the applications. 205This method is now no longer needed, as the fully functional 206libraries ship with the system. 207However, this entire debacle is worth remembering when choosing 208software and vendors. 209.Pp 210Due to multiple flaws in the protocols, SSL version 2 was removed in 211.Ox 5.2 212and SSL version 3 was disabled in 213.Ox 5.7 . 214Users and programs should use TLS version 1.2 instead. 215.Pp 216This document first appeared in 217.Ox 2.5 . 218