.\"	$OpenBSD: ssl.8,v 1.33 2001/08/03 15:21:17 mpech Exp $
.\"
.Dd March 15, 1999
.Dt SSL 8
.Os
.Sh NAME
.Nm ssl
.Nd details for libssl and libcrypto
.Sh DESCRIPTION
This document describes some of the issues relating to the use of
the OpenSSL libssl and libcrypto libraries.
This document is intended as an overview of what the libraries do,
and what uses them.
.Pp
The SSL libraries (libssl and libcrypto) implement the
.Ar SSL version 2 ,
.Ar SSL version 3 ,
and
.Ar TLS version 1
protocols.
.Ar SSL version 2
and
.Ar 3
are most
commonly used by the
.Ar https
protocol for encrypted web transactions, as can be done with
.Xr httpd 8 .
The libcrypto library is also used by various programs such as
.Xr ssh 1 ,
.Xr sshd 8 ,
and
.Xr isakmpd 8 .
.Sh RANDOM DATA SOURCE
OpenBSD uses the
.Xr arandom 4
device as the default source for random data when needed by the routines in
libcrypto and libssl.
If the
.Xr arandom 4
device does not exist or is not readable, many of the routines will fail.
This is most commonly seen by users as the
.Ar RSA
routines failing in applications such as
.Xr ssh 1 ,
and
.Xr httpd 8 .
.Pp
It is important to remember when using a random data source for certificate
and key generation that the random data source should not be visible by
people who could duplicate the process and come up with the same result.
You should ensure that nobody who you don't trust is in a position to read
the same random data used by you to generate keys and certificates.
The
.Xr arandom 4
device ensures that no two users on the same machine will see the same
data.
See
.Xr openssl 1
for more information on how to use different sources of random data.
.Sh SERVER CERTIFICATES
The most common uses of
.Ar SSL/TLS
will require you to generate a server certificate, which is provided by your
host as evidence of its identity when clients make new connections.
The certificates reside in the
.Pa /etc/ssl
directory, with the keys in the
.Pa /etc/ssl/private
directory.
.Pp
Private keys can be encrypted using
.Ar 3DES
and a passphrase to protect their integrity should the encrypted file
be disclosed, However it is
important to note that encrypted server keys mean that the passphrase
needs to be typed in every time the server is started.
If a passphrase is not used, you will need to be absolutely sure your
key file is kept secure.
.Sh GENERATING DSA SERVER CERTIFICATES
Generating a
.Ar DSA
certificate involves several steps.
First, you generate a
.Ar DSA
parameter set with a command like the following:
.Bd -literal -offset indent
# openssl dsaparam 1024 -out dsa1024.pem
.Ed
.Pp
Would generate
.Ar DSA
parameters for 1024 bit
.Ar DSA
keys, and save them to the
file
.Pa dsa1024.pem .
.Pp
Once you have the
.Ar DSA
parameters generated, you can generate a certificate
and unencrypted private key using the command:
.Bd -literal -offset indent
# openssl req -x509 -nodes -newkey dsa:dsa1024.pem \\
  -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem
.Ed
.Pp
To generate an encrypted private key, you would use:
.Bd -literal -offset indent
# openssl req -x509 -newkey dsa:dsa1024.pem \\
  -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem
.Ed
.Sh GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS
To support
.Ar https
transactions in
.Xr httpd 8
you will need to generate an
.Ar RSA
certificate.
.Bd -literal -offset indent
# openssl genrsa -out /etc/ssl/private/server.key 1024
.Ed
.Pp
Or, if you wish the key to be encrypted with a passphrase that you will
have to type in when starting servers
.Bd -literal -offset indent
# openssl genrsa -des3 -out /etc/ssl/private/server.key 1024
.Ed
.Pp
The next step is to generate a
.Ar Certificate Signing Request
which is used
to get a
.Ar Certifying Authority (CA)
to sign your certificate.
To do this use the command:
.Bd -literal -offset indent
# openssl req -new -key /etc/ssl/private/server.key \\
  -out /etc/ssl/private/server.csr
.Ed
.Pp
This
.Pa server.csr
file can then be given to
.Ar Certifying Authority
who will sign the key.
One such CA is
.Ar Thawte Certification
which you can reach at
.Ar http://www.thawte.com/.
Thawte can currently sign RSA keys for you.
A procedure is being worked out to allow for DSA keys.
.Pp
You can also sign the key yourself, using the command:
.Bd -literal -offset indent
# openssl x509 -req -days 365 -in /etc/ssl/private/server.csr \\
  -signkey /etc/ssl/private/server.key -out /etc/ssl/server.crt
.Ed
.Pp
With
.Pa /etc/ssl/server.crt
and
.Pa /etc/ssl/private/server.key
in place, you should be able to start
.Xr httpd 8
with the
.Ar -DSSL
flag, enabling
.Ar https
transactions with your machine on port 443. 
.Pp
You will most likely want to generate a self-signed certificate in the
manner above along with your certificate signing request to test your
server's functionality even if you are going to have the certificate
signed by another Certifying Authority.  Once your Certifying
Authority returns the signed certificate to you, you can switch to
using the new certificate by replacing the self-signed
.Pa /etc/ssl/server.crt
with the certificate signed by your Certifying Authority, and then
restarting 
.Xr httpd 8
.Sh BUGS
The world needs more
.Ar DSA
capable
.Ar SSL
and
.Ar SSH
services.
.Sh SEE ALSO
.Xr httpd 8 ,
.Xr ssh 1 ,
.Xr sshd 8 ,
.Xr isakmpd 8 ,
.Xr pkg_add 1 ,
.Xr openssl 1 ,
.Xr arandom 4 ,
.Xr ssl 3 ,
.Xr rc 8
.Sh HISTORY
Prior to Sept 21, 2000
there were problems shipping fully functional implementations of these
protocols everywhere in the world, as such shipment would include shipping
.Ar into
the United States, thus causing problems.
.Ar RSA Data Security Inc (RSADSI)
held the patent on the
.Ar RSA
algorithm in the United States.
Because of this, free implementations of
.Ar RSA
were difficult to distribute and propagate.
(The
.Ar RSA
patent was probably more effective at preventing the late adoption of
widespread international integrated crypto than the much maligned
ITAR restrictions were).
Prior to OpenBSD 2.8, these libraries shipped without the
.Ar RSA
algorithm -- all such functions
were stubbed to fail.
Since
.Ar RSA
is a key component of
.Ar SSL version 2 ,
this
meant that
.Ar SSL version 2
would not work at all.
.Ar SSL version 3
and
.Ar TLS version 1
allow for the exchange of keys via mechanisms that do not
involve
.Ar RSA ,
and would work with the shipped version of the libraries,
assuming both ends could agree to a cipher suite and key exchange that
did not involve RSA.
Likewise, the SSH1 protocol in
.Xr ssh 1
uses RSA, so it was similarly encumbered.
.Pp
For instance, another typical alternative
is
.Ar DSA ,
which is not encumbered by commercial patents (and lawyers).
.Pp
The
.Ar https
protocol used by web browsers (in modern incarnations),
allows for the use of
.Ar SSL version 3
and
.Ar TLS version 1 ,
which in theory allows for encrypted web transactions without using
.Ar RSA .
Unfortunately all the popular web browsers
buy their cryptographic code from
.Ar RSADSI .
Predictably,
.Ar RSADSI
would prefer if web browsers used their patented algorithm, and thus their
libraries do not implement any
.Ar non-RSA
cipher and keying combination.
The result of this was that while the
.Ar https
protocol allowed for many cipher suites that did not require the use
of patented algorithms, It was very difficult to use these with the
popular commercially available software.
Prior to version 2.8, OpenBSD allowed users to download
.Ar RSA
enabled versions of the shared libssl and libcrypto libraries
which allowed users to enable full function without recompiling
the applications.
This method is now no longer needed, as the fully functional
libraries ship with the system.
However, this entire debacle is worth remembering when choosing
software and vendors.
.Pp
This document first appeared in
.Ox 2.5 .