SSL(8)                  OpenBSD System Manager's Manual                 SSL(8)

NAME
     ssl - details for libssl and libcrypto

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, what uses them, and the slightly un-
     orthodox way of upgrading the library.

     The SSL libraries (libssl and libcrypto) implement the SSL version 2, SSL
     version 3, and TLS version 1 protocols.  SSL version 2 and 3 are most
     commonly used by the https protocol for encrypted web transactions.  Due
     to patent issues in the United States, there are problems with shipping a
     fully functional implementation of these protocols anywhere in the world,
     as such shipment would include shipping into the United States, thus
     causing problems.

PATENTS AND THE RSA ALGORITHM
     RSA Data Security Inc (RSADSI) holds a patent on the RSA algorithm in the
     United States. Because of this, free implementations of RSA are difficult
     to distribute and propagate.  (The RSA patent is probably more effective
     at preventing the widespread international adoption of integrated crypto
     than the much maligned ITAR restrictions are). The versions of libssl and
     libcrypto provided in the stock distribution do not contain the RSA algo-
     rithm -- all such functions are stubbed to fail. Since RSA is a key com-
     ponent of SSL version 2, this means that SSL version 2 will not work at
     all.  SSL version 3 and TLS version 1 allow for the exchange of keys via
     mechanisms that do not involve RSA, and will work with the shipped ver-
     sion of the libraries, assuming both ends can agree to a cipher suite and
     key exchange that does not involve RSA.

     For instance, another typical alternative is DSA -- which is patent-free.

     The https protocol used by web browsers (in modern incarnations), allows
     for the use of SSL version 3 and TLS version 1, which in theory allows
     for encrypted web transactions without using RSA. Unfortunately all the
     popular web browsers buy their cryptographic code from RSADSI. Pre-
     dictably, RSADSI would prefer if web browsers used their patented algo-
     rithm, and thus their libraries do not implement any non-RSA cipher and
     keying combination.

HOW TO ADD RSA-CAPABLE LIBRARIES
     Fortunately, not all of the world lives in the United States.  Addition-
     ally RSA inc. permits non-licensed use of the algorithm by certain par-
     ties (ie. non-commercial use).  If you are permitted to use the RSA algo-
     rithm, you can enable the full function of the ssl libraries by updating
     the shared libraries on your system, using a command like:

        # pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/2.6/packages/i386/ssl26.tgz

     or

        # pkg_add ftp://ftp.usa.openbsd.org/pub/OpenBSD/2.6/packages/i386/sslUSA26.tgz

     (Obviously, replace 2.6 with the current release, and i386 with your ar-
     chitecture name (see arch(1)). see  afterboot(8) for more details on
     adding RSA capable libraries.

     Once your ssl libraries are updated, the ssl libraries will be fully
     functional.

SERVER CERTIFICATES
     The most common uses of 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
     /etc/ssl directory, with the keys in the /etc/ssl/private directory.

     Private keys can be encrypted using 3DES and a passphrase to protect
     their integrity should the encrypted file be disclosed, However it is im-
     portant 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.

GENERATING DSA SERVER CERTIFICATES
     Generating a DSA certificate involves several steps. First, you generate
     a DSA parameter set with a command like the following:

           # openssl dsaparam 1024 -out dsa1024.pem

     Would generate DSA parameters for 1024 bit DSA keys, and save them to the
     file dsa1024.pem.

     Once you have the DSA paramters generated, you can generate a certificate
     and unencrypted private key using the command:

           # openssl req -x509 -nodes -newkey dsa:dsa1024.pem \
             -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem

     To generate an encrypted private key, you would use:

           # openssl req -x509 -newkey dsa:dsa1024.pem \
             -out /etc/ssl/dsacert.pem -keyout /etc/ssl/private/dsakey.pem

GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS
     To generate RSA certificates, you will first need to upgrade your shared
     libraries to support RSA as described above. Once that is done, you can
     generate RSA certificates that will be usable by httpd(8) for https
     transactions.

           # openssl genrsa -out /etc/ssl/private/server.key 1024

     Or, if you wish the key to be encrypted with a passphrase that you will
     have to type in when starting servers

           # openssl genrsa -des3 -out /etc/ssl/private/server.key 1024

     The next step is to generate a Certificate Signing Request which is used
     to get a Certifying Authority (CA) to sign your certificate. To do this
     use the command:

           # openssl req -new -key /etc/ssl/private/server.key \
             -out /etc/ssl/private/server.csr

     This server.csr file can then be given to Certifying Authority who will
     sign the key. One such CA is Thawte Certification which you can reach at
     http://www.thawte.com/. Thawte can currently sign RSA keys for you. A
     procedure is being worked out to allow for DSA keys.

     You can also sign the key yourself, using the command:

           # openssl x509 -req -days 365 -in /etc/ssl/private/server.csr \
             -signkey /etc/ssl/private/server.key -out /etc/ssl/server.crt

     With /etc/ssl/server.crt and /etc/ssl/private/server.key in place, you
     should be able to start httpd(8) with the -DSSL flag, enabling https
     transactions with your machine on port 443.

BUGS
     openssl and libssl have nearly nonexistent documentation.  Most documen-
     tation consists of examples and README files in the sources.  Mail
     beck@openbsd.org to assist or encourage him to finish the job.

     The world needs more DSA capable SSL and SSH services.

     According to "Applied Cryptography: Schneier" the RSA patent will expire
     September 20th, 2000.


     Patents can be renewed.

SEE ALSO
     httpd(8),  ssh(1),  sshd(1),  rc(8)

HISTORY
     This document first appeared in OpenBSD 2.5.

OpenBSD 2.6                     March 15, 1999                               3
