diff options
| -rw-r--r-- | lib/libssl/Makefile | 3 | ||||
| -rw-r--r-- | lib/libssl/Makefile.bsd-wrapper | 7 | ||||
| -rw-r--r-- | lib/libssl/ssl.8 | 244 |
3 files changed, 247 insertions, 7 deletions
diff --git a/lib/libssl/Makefile b/lib/libssl/Makefile index 683e40e63bd..44a67a67641 100644 --- a/lib/libssl/Makefile +++ b/lib/libssl/Makefile @@ -1,5 +1,5 @@ .include <bsd.own.mk> - +MAN = ssl.8 ECHO= /bin/echo .if exists(${.OBJDIR}/src-patent) @@ -13,5 +13,6 @@ distribution: ${INSTALL} ${INSTALL_COPY} -g ${BINGRP} -m 444 \ ${.CURDIR}/ssleay.cnf ${DESTDIR}/etc/ssl/lib/ssleay.cnf; +.include <bsd.man.mk> .include <bsd.subdir.mk> diff --git a/lib/libssl/Makefile.bsd-wrapper b/lib/libssl/Makefile.bsd-wrapper index bb64e76798e..7b164016010 100644 --- a/lib/libssl/Makefile.bsd-wrapper +++ b/lib/libssl/Makefile.bsd-wrapper @@ -1,5 +1,5 @@ # Build wrapper for SSLeay. -# $OpenBSD: Makefile.bsd-wrapper,v 1.7 1999/03/12 17:31:01 espie Exp $ +# $OpenBSD: Makefile.bsd-wrapper,v 1.8 1999/03/16 19:48:08 beck Exp $ # Our lndir is hacked; specify a full path to avoid potential conflicts # with the one installed with X11. @@ -94,8 +94,3 @@ tags: .include <bsd.obj.mk> .include <bsd.subdir.mk> - - - - - diff --git a/lib/libssl/ssl.8 b/lib/libssl/ssl.8 new file mode 100644 index 00000000000..0a98dd7fb14 --- /dev/null +++ b/lib/libssl/ssl.8 @@ -0,0 +1,244 @@ +.Dd March 15, 1999 +.Dt SSL 8 +.Os OpenBSD +.Sh NAME +.Nm ssl +.Nd details for libssl and libcrypto +.Sh DESCRIPTION +This document describes some of the issues relating to the use of +Eric Young's libssl and libcrypto libraries in OpenBSD. This document +is intended as an overview of what the libraries do, what uses them, +and the slightly unorthodox way of upgrading the library. +.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. +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 +.Ar into +the United States, thus causing problems. +.Sh PATENTS AND THE RSA ALGORITHM +.Ar RSA Data Security Inc (RSADSI) +holds a patent on the +.Ar RSA +algorithm in the United States. Because of this, free +implementations of +.Ar RSA +are difficult to distribute and propogate. +(The +.Ar 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 +.Ar RSA +algorithm -- all such functions +are stubbed to fail. Since +.Ar RSA +is a key component of +.Ar SSL version 2 , +this +means that +.Ar SSL version 2 +will 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 will work with the shipped version of the libraries, +assuming both ends can agree to a cipher suite and key exchange that +does not involve RSA. +.Pp +For instance, another typical alternative +is +.Ar DSA +-- which is patent-free. +.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. +.Sh HOW TO ADD RSA LIBRARIES TO OPENBSD +Fortunately, not all of the world lives in the United +States. +Additionally +.Ar RSADSI +permits non-licensed use of the algorithm by certain parties +(ie. non-commercial use). +If you are permitted to use the +.Ar RSA +algorithm, you can enable the full function of the +.Nm +libraries by updating the shared libraries on your system, +using a command like: +.Bd -literal -offset xxx +# pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/2.5/packages/i386/libssl-1.1.tgz +.Ed +.Pp +(Obviously, replace +.Ar 2.5 +with the current release, and +.Ar i386 +with your architecture name (see +.Xr arch 1 ). +Once your ssl libraries are updated, the ssl libraries will be fully functional. +.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 +# ssleay 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 +paramters generated, you can generate a certificate +and unencrypted private key using the command: +.Bd -literal -offset indent +# ssleay req -x509 -nodes -newkey dsa:dsa1024.pem \\ + -out /etc/dsacert.pem -keyout /etc/ssl/private/dsakey.pem +.Ed +.Pp +To generate an encrypted private key, you would use: +.Bd -literal -offset indent +# ssleay req -x509 -nodes -newkey dsa:dsa1024.pem \\ + -out /etc/dsacert.pem -keyout /etc/ssl/private/dsakey.pem +.Ed +.Sh GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS +To generate +.Ar RSA +certificates, you will first need to upgrade your +shared libraries to support +.Ar RSA +as described above. Once that is done, +you can generate +.Ar RSA +certificates that will be usable by +.Xr httpd 8 +for +.Ar https +transactions. +.Bd -literal -offset indent +# ssleay 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 +# ssleay genrsa -des3 -out /etc/ssl/private/server.key 1024 +.Ed +.Pp +The next step is to generate a +.Ar Certifiate 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 +# ssleay 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. +You can also sign the key yourself, using the command: +.Bd -literal -offset indent +# ssleay 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. +.Sh BUGS +.Pp +.Nm ssleay +and +.Nm libssl +have nearly nonexistent documentation. +Most documentation consists of examples and README files in +the sources. Mail beck@openbsd.org to assist or +encourage him to finish the job. +.Pp +The world needs more +.Ar DSA +capable +.Ar SSL +services. +.Pp +Patents can be renewed. +.Sh SEE ALSO +.Xr httpd 8 , +.Xr rc 8 +.Sh HISTORY +This document first appeared in +.Ox 2.5 . |