1.\" $OpenBSD: ssl.8,v 1.69 2021/02/12 14:19:11 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: February 12 2021 $ 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. 67Start by creating a private key of the desired length: 68.Bd -literal -offset indent 69# openssl genrsa -out /etc/ssl/private/server.key 4096 70.Ed 71.Pp 72Or, if you wish the key to be encrypted with a passphrase that you will 73have to type in when starting servers 74.Bd -literal -offset indent 75# openssl genrsa -aes256 -out /etc/ssl/private/server.key 4096 76.Ed 77.Pp 78If you are only generating a private key to use with 79.Xr acme-client 1 80(for example, with a non-default key length) 81you may stop here. 82.Pp 83Otherwise, the next step is to generate a Certificate Signing Request (CSR) 84which is used to get a Certificate Authority (CA) to sign your certificate. 85To do this use the command: 86.Bd -literal -offset indent 87# openssl req -new -key /etc/ssl/private/server.key \e 88 -out /etc/ssl/private/server.csr 89.Ed 90.Pp 91This 92.Pa server.csr 93file can then be given to a Certificate Authority who will sign the key. 94.Pp 95You can also sign the key yourself, using the command: 96.Bd -literal -offset indent 97# openssl x509 -sha256 -req -days 365 \e 98 -in /etc/ssl/private/server.csr \e 99 -signkey /etc/ssl/private/server.key \e 100 -out /etc/ssl/server.crt 101.Ed 102.Pp 103Note that standard web browsers do not use the common name of a subject, 104but instead require that subject alt names are provided. 105This requires the use of 106.Ar -extfile Pa server.ext 107when self-signing. 108.Bd -literal -offset indent 109# this is an example server.ext file 110subjectAltName=DNS:example.com,DNS:www.example.com 111.Ed 112.Pp 113With 114.Pa /etc/ssl/server.crt 115and 116.Pa /etc/ssl/private/server.key 117in place, you should be able to start 118.Xr httpd 8 119with SSL configured, enabling HTTPS transactions with your machine on port 443. 120.Pp 121You will most likely want to generate a self-signed certificate in the 122manner above along with your certificate signing request to test your 123server's functionality even if you are going to have the certificate 124signed by another Certificate Authority. 125Once your Certificate Authority returns the signed certificate to you, 126you can switch to using the new certificate by replacing the self-signed 127.Pa /etc/ssl/server.crt 128with the certificate signed by your Certificate Authority, and then 129restarting 130.Xr httpd 8 . 131.Sh GENERATING ECDSA SERVER CERTIFICATES 132First, generate a private ECDSA key. 133The following command will use a NIST/SECG curve over a 384-bit 134prime field: 135.Bd -literal -offset indent 136# openssl ecparam -name secp384r1 -genkey \e 137 -noout -out /etc/ssl/private/eccert.key 138.Ed 139.Pp 140Note that some Certificate Authorities will only issue certificates for 141keys generated using prime256v1 parameters. 142.Pp 143If you are only generating a private key to use with 144.Xr acme-client 1 , 145you may stop here. 146Otherwise, the next step is to generate a Certificate Signing Request (CSR) 147which is used to get a Certificate Authority (CA) to sign your certificate. 148To do this use the command: 149.Bd -literal -offset indent 150# openssl req -key /etc/ssl/private/eccert.key -new \e 151 -out /etc/ssl/private/eccert.csr 152.Ed 153.Pp 154This 155.Pa eccert.csr 156file can then be given to a CA who will sign the key. 157.Pp 158You can also sign the key yourself, using the command: 159.Bd -literal -offset indent 160# openssl x509 -sha256 -req -days 365 \e 161 -in /etc/ssl/private/eccert.csr \e 162 -signkey /etc/ssl/private/eccert.key \e 163 -out /etc/ssl/eccert.crt 164.Ed 165.Sh SEE ALSO 166.Xr acme-client 1 , 167.Xr openssl 1 , 168.Xr ssh 1 , 169.Xr ssl 3 , 170.Xr httpd 8 , 171.Xr isakmpd 8 , 172.Xr rc 8 , 173.Xr smtpd 8 , 174.Xr sshd 8 , 175.Xr starttls 8 176.Sh HISTORY 177Prior to Sept 21, 2000, 178there were problems shipping fully functional implementations of these 179protocols, as such shipment would include shipping 180.Em into 181the United States. 182RSA Data Security Inc (RSADSI) held the patent on the RSA algorithm in the 183United States, and because of this, free implementations of RSA were 184difficult to distribute and propagate. 185(The RSA patent was probably more effective at preventing the adoption of 186widespread international integrated crypto than the much maligned ITAR 187restrictions were.) 188Prior to 189.Ox 2.8 , 190these libraries shipped without the RSA algorithm -- all such functions 191were stubbed to fail. 192Since RSA is a key component of SSL version 2, this meant that SSL version 1932 would not work at all. 194SSL version 3 and TLS version 1 allow for the exchange of keys via 195mechanisms that do not involve RSA, and would work with the shipped version 196of the libraries, assuming both ends could agree to a cipher suite and key 197exchange that did not involve RSA. 198Likewise, the SSH1 protocol in 199.Xr ssh 1 200uses RSA, so it was similarly encumbered. 201.Pp 202For instance, another typical alternative is DSA, which is not encumbered 203by commercial patents (and lawyers). 204.Pp 205The HTTPS protocol used by web browsers (in modern incarnations) allows for 206the use of SSL version 3 and TLS version 1, which in theory allows for 207encrypted web transactions without using RSA. 208Unfortunately, all the popular web browsers buy their cryptographic code 209from RSADSI. 210Predictably, RSADSI would prefer that web browsers used their patented 211algorithm, and thus their libraries do not implement any non-RSA cipher and 212keying combination. 213The result of this was that while the HTTPS protocol allowed for many 214cipher suites that did not require the use of patented algorithms, it was 215very difficult to use these with the popular commercially available 216software. 217Prior to version 2.8, 218.Ox 219allowed users to download RSA enabled versions of the shared libssl and 220libcrypto libraries which allowed users to enable full functionality without 221recompiling the applications. 222This method is now no longer needed, as the fully functional 223libraries ship with the system. 224However, this entire debacle is worth remembering when choosing 225software and vendors. 226.Pp 227Due to multiple flaws in the protocols, SSL version 2 was removed in 228.Ox 5.2 229and SSL version 3 was disabled in 230.Ox 5.7 . 231Users and programs should use TLS version 1.2 instead. 232.Pp 233This document first appeared in 234.Ox 2.5 . 235