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