FAQ last updated 14 November 1996.
SSLeay is a free implementation of Netscape's Secure Socket Layer - the software encryption protocol behind the Netsite Secure Server and the Netscape Navigator Browser.
SSLeay is pronounced S-S-L-e-a-y (i.e. each letter is pronounced individually).
SSLeay implements SSLv2 (version 2). Support for SSLv3 is planned but there is no fixed timeframe in which this will be done. Contact us on ssleay@mincom.com if you wish to discuss this.
This implementation was coded from scratch using only the publicly available documentation of the various protocols by Eric Young eay@mincom.com.
The initial prompting to tackle an SSL implementation, the alpha testing, SSL developer (i.e. Eric) hassling, Windows port and documentation was done by Tim Hudson tjh@mincom.com.
This implementation has been used by Tim Hudson tjh@mincom.com to add SSL support to the following:
The following applications are also now available based on the earlier work with input from others:
Support for the following are also available:
SSLeay implements the following encryption algorithms:
This documentation is Copyright Tim Hudson tjh@mincom.com See the COPYRIGHT file for the usage and redistribution restrictions.
Note: a nicely formatted postscript version of this document is included in the file SSLeay.doc-version.tar.gz (in the same directory as the SSLeay source).
That is one of the hard questions on which there is as yet no clear answer. You need to read quite a bit of information (see the RAMBLINGS file in the SSLeay source distribution) to draw your own conclusions - and then go and talk to a lawyer. Again this document is my opinion and as such should be treated in that light - reality could be quite different to how I happen to see things :-).
In short:
Nothing. The package itself is free. There are a couple of minor conditions which are outlined clearly in the COPYRIGHT file in the source distribution. In short - attribution is mandatory, and no publicly available version of this code can have a different license.
Yes. Free of charge. Read the license carefully (see the COPYRIGHT file in the SSLeay source distribution). If there are issues that you are not clear on in terms of the COPYRIGHT contact Eric Young directly via eay@mincom.com.
At present the documentation from a programmer's point of view is fairly light and you really need to work through the code that is included in the library itself and have a look at how the patches are put together. It is fairly straight forward to add SSL support to an existing application.
Most of the issues that need to be considered if you are going to start using SSL either as an end user or as a developer are covered in the documentation - certainly there needs to be more work done on this documentation; however reading the documentation should answer most questions (and raise quite a few more too).
Eric has finally been hassled into starting documentation on the library itself ... see the doc directory in the SSLeay distribution. This documentation may be turned into a more verbose manual over the next few months.
The best starting point is to look at example code ... either in the sample client and server program included with SSLeay or in any of the patched applications - the structure of each of the applications internally is quite similar.
If you really get stuck then have a look through the ssl-users mailing list archives ... or ask us directly via email to ssleay@mincom.com.
The SSL Protocol Specification is detailed at http://home.netscape.com/newsref/std/SSL.html. This covers SSLv2.
SSLRef (The Netscape Reference Implementation of SSL) is located at http://home.netscape.com/newsref/std/sslref.html
SSL Version 3 Protocol Specification is located at http://home.netscape.com/eng/ssl3/
There is also a mailing list for discussion of SSL managed by Netscape at ssl-talk@netscape.com. You can join this list by sending mail to ssl-talk-request@netscape.com with subscribe as the subject line or the message body.
The SSL-Talk List FAQ is available at http://www.consensus.com/security/ssl-talk-faq.html and it contains a large amount of useful information.
A document describing our use of certificates is available at: http://home.netscape.com/newsref/std/ssl_2.0_certificate.html It contains a description of the "application/x-x509-ca-cert" MIME type.
General Netscape security information can be found at http://home.netscape.com/eng/security/
Additionally Jeff Weinstein jsw@netscape.com has also put together a description of Key Generation, Certificate Extensions, and Certificate Downloading in Netscape Navigator 3.0 at http://home.netscape.com/eng/security/certs.html. This is worth reading!
A rather extensive list of cryptographic material is maintained at http://www.cs.hut.fi/crypto/ and a handy list of publicly available software is available directly at http://www.cs.hut.fi/crypto/software.html.
Also there is a good overview of certificate services in general available from RSA at ftp://ftp.rsa.com/pub/csc/docs/wp.eps. It is a 40 page July 1993 document that is good background reading.
Holger Reif Holger.Reif@PrakInf.TU-Ilmenau.DE has a very readable writeup on SSLeay-0.5.x at http://www.heise.de/ix/artikel/E/9606128/. It is also available in German.
Adam Shostack adam@homeport.org has an interesting comparison of most generally available cryptographic libraries at http://www.homeport.org/~adam/crypto.
As part of working on SSLeay I've thown together a number of small documents that contain notes of things that I think are important when writing SSL-enabled applications. Naturally the documentation is not as current as I'd like but it does contain a lot of useful information.
I also wrote porting notes for the following applications when I converted them to use SSLeay so that others could see how much work it is to SSL-enable an application and also the things that should be done when writing an application to make supporting SSLeay easy.
Dave Madden dhm@paradigm.webvision.com has put together notes from various sources on what you need to do to set things up as your own CA.
Thanks to Stephan Kolletzki kolletzki@darmstadt.gmd.de and David P Kemp dpkemp@missi.ncsc.mil for the following list of online resources in the area of APIs related to Certifying Authority issues.
Version 1, Dec 1995 is currently visible. Version 2.0 is the current version but does not appear to be online yet.
http://www.intel.com/ial/security/specs.htm
http://www.microsoft.com/intdev/security/capi/capiref.zip
http://www.esat.kuleuven.ac.be/cosic/sesame
The SESAME V4 Public Key Management Application Developers' Guide describes the PKM API (pkm_begin, pkm_get_pub_key, etc).
http://www.darmstadt.gmd.de/secude
European multipurpose security toolkit + applications for Unix and PC including APIs for crypto/X.509/GSSv2/PEM/PKCS/SMIME and utilities/GUI for digital ID maintainance
This (believe it or not) used to be the most commonly asked question.
The whole dependence on RSA (actually now Verisign) for certificates began because Netscape browsers at release 1.x did not allow the user to configure which Certifying Authorities are trusted and only trusted four hardcoded CAs.
The Netscape Navigator starting with release 2.x (beta) added support for user configurable CAs. If the user connects to service that is using a certificate that is not signed by one of the hardcoded CAs then the user is asked if they want to add it to the list of trusted CAs. This basically means that the security trust policy is now in the hands of the user. This policy has continued with release 3.x and Netscape have also expanded their list of standard CAs to include some non-USA based CAs (including Thawte Consulting http://www.thawte.com). There is a full list of the CAs that have contacted me in List of Certifying Authorities.
Verisign have changed their policy on issuing certificates such that certificates will only be issued for use with registered applications that have been though an external Cryptographic analysis. (and SSLeay itself doesn't automatically fit in any of their current categories). Stronghold and Sioux are now both registered SSLeay-based servers so if you purchase either of those products Verisign will issue certificates. Alternatively you can simply use another CA.
Those that currently have certificates signed by Verisign will not have them renewed unless the software being used is on the registered application list. This is a rather interesting and unusual situation.
If you already have a certificate from RSA can you (legally) use it with an SSLeay-ized httpd? According to information I've received from Verisign doing this would be in violation of the licence agreement that was part of getting a certificate from Verisign. Contact Verisign directly if you are unsure of your situation.
You really should read the details of the process that Alex Tang altitude@cic.net went through if you are "blessed" with being inside the USA. This is detailed at http://petrified.cic.net/~altitude/ssl/ssl.saga.html and makes quite "interesting reading".
Note: Microsoft have now complicated the picture as their current Internet Explorer does not support automatic user configurable CAs and is in that respect back to the state of the Navigator 2.x times. MSIE does support the user being able to add in their own CAs, however when an unknown CA is encountered the user is not presented with the option of adding them into the CA list (which is how Navigator 3.x behaves).
This is likely to change in the near future given the rapid development that Microsoft has performed to get from MSIE 2.x to MSIE 3.x and I will update the details here when this happens.
The patches to Mosaic were done so that there is no checking of the certificate of the server such that Mosaic will connect and work with any of the existing secure servers without a problem. This however is probably not the policy you should run if you are planning on issuing credit card transactions - the client should have some form of security verification procedure in place where it checks the server against a trusted list before handing over any important information.
Exactly how the whole certificate management and authorisation process is going to work on a global basis is really unknown at this stage.
Adding in your own server verification process into the patches that are available is fairly easy to do; however given the investment that Netscape and Microsoft have put into their products and are continuing to do so I don't personally see NCSA Mosaic as being a long-term viable browser alternative (hence I've not bothered tracking the continuing updates as I don't see any point myself as I can no longer use a browser without decent table support).
Rather simply put, we need people who are prepared to contribute to the effort under the same conditions that we work (which is simply attribution is mandatory but everything generated is totally free otherwise) so that we have a wider supported set of applications. If you do add SSL support to an application please drop us a line (and the patches if at all possible).
However if you wish to send donations of almost any form, neither of us will say no and it may influence what we work on next and how quickly things are done. If in doubt about this contact us directly via ssleay@mincom.com
If you have access to a Unix varient that we do not and you are well connected (bandwidth-wise) and don't mind a little extra load then we can speed up the spread of the SSL applications (the library itself is very portable - it's the applications (at the moment) that are significantly less so.
Also join the ssl-users@mincom.com mailing list (send email to ssl-users-request@mincom.com for instructions for using the majordomo varient that manages this list - which in short are send mail to factotum@mincom.com with a message body of subscribe ssl-users).
Tom Kee tom.kee@magnets.com maintains an archive of the mailing list at http://www.magnets.com/lists/
Holger Reif Holger.Reif@PrakInf.TU-Ilmenau.DE also maintains an archive at http://remus.prakinf.tu-ilmenau.de/ssl-users/
Well, as this in an unpaid effort there is no guarantee of support (you get what you pay for :-); however there is a mailing list which has those people subscribed to it who are interested in SSLeay and it's furthur development.
Join the ssl-users@mincom.com mailing list (send email to ssl-users-request@mincom.com for instructions for using the majordomo varient that manages this list - which in short are send mail to factotum@mincom.com with a message body of subscribe ssl-users).
Eric Young eay@mincom.com
Tim Hudson tjh@mincom.com
Or to get hold of both of us (which is probably the "right" thing to do for most questions) use ssleay@mincom.com
Eric concentrates on the library side of thing and Tim (me) has done all the applications and documentation; however it is better to contact both of us unless it's a really specific question as we do know what each other is working on and work different hours (and have different opinions on some things too :-) and take holidays at different times. I've also worked on most of the Windows infrastructure code.
Tom Kee tom.kee@magnets.com maintains an archive of the mailing list at http://www.magnets.com/lists/
Holger Reif Holger.Reif@PrakInf.TU-Ilmenau.DE also maintains an archive at http://remus.prakinf.tu-ilmenau.de/ssl-users/
The master location for SSLeay source and the SSLapps is the following:
Note: the SSLeay Programmer Reference is in the process of being updated to SSLeay-0.6 so what is there doesn't exactly match the current version.
SSLeay is also mirrored at the following locations:
Christoph Martin christoph.martin@uni-mainz.de mirrors the SSLeay distribution (updated every 24 hours) in the following location:
The German CERT server in Hamburg
For those close to Finland
Panu Rissanen bande@nic.funet.fi mirrors SSLeay updated biweekly at:
Sites in Sweeden
Tein Yuan tyuan@beta.wsl.sinica.edu.tw mirrors SSLeay related stuff at:
Sites in South Africa
John Hay jhay@zibbi.mikom.csir.co.za and Johan Eksteen Johan.Eksteen@dent.mikom.csir.co.za mirrors SSLeay updated daily at:
Sites in Korea
Lee, Ho-sun ahmlhs@cair.kaist.ac.kr mirrors SSLeay related stuff at:
Sites in Japan
Takahiro Kiuchi kiuchi@rick.epistat.m.u-tokyo.ac.jp mirrors SSLeay related stuff at:
Sites in the UK
Steve Kennedy steve@gbnet.net mirrors SSLeay updated daily at:
Sites in Hong Kong
Enzo Michelangeli enzo@ima.net mirrors SSLeay updated daily at:
Sites in Taiwan
CS Lee (Lee Chee Siong) ftpowner@ftp.nchu.edu.tw mirrors SSLeay updated daily at:
Sites in Poland
Martin E. Bednarz specula@lodz.pdi.net mirrors SSLeay updated daily at:
Note: If you are outside of the USA and not covered by legal restrictions on the export and import of encryption technology and you are prepared to mirror the SSLeay distribution then drop me a line at tjh@mincom.com with details similar to the current mirrors and you will be added to this list.
4.4BSD-Lite telnet (NEtelnet) patches done by Christoph Martin christoph.martin@uni-mainz.de are located at:
Note: Christoph and myself are still in the process of merging our code to get back to having a single version of the source.
The first fully functional version of Apache with SSL support was implemented by Ben Laurie ben@algroup.co.uk. This server is probably the best choice at the moment if you are looking for a freely available SSL capable WWW server and don't mind building, configuring and maintaining it yourself.
SSL support for CERN httpd was implemented by Gertjan van Oosten gertjan@West.NL. See http://www.west.nl/archive/cern_httpd/HTTPS.patch for the patches.
Thomas E Zerucha tz@execpc.com is maintaining a patch to Lynx to support SSLeay. See http://www.mich.com/~thomas/ftp/lynxpatches for the current version.
Lynx is a text based WWW browser that supports Unix, VMS and apparently DOS. For more information see http://lynx.cc.ukans.edu/
There have been problems reported with the current release of SSLeay with the patches noted above. If you get this working then please send me some email at tjh@mincom.com so I can update this document.
Is there a Windows version of SSLeay and the applications to go with it?
The answer is yes. SSLeay-0.6.1 and above support WIN16 and WIN32. The base release has command line makefile support for building with Microsoft Visual C.
Note: I've also build WIN16 setups for Borland C++ 4.x but the build procedure is not yet integrated into the standard distribution. Contact me if you wish to get the current Borland C support tjh@mincom.com.
SSLeay-0.6.4 includes multi-threaded support for WIN32.
We have tested Windows 3.11, Windows 95 and Windows NT.
To start things rolling with a server you will need to generate a certificate. There is a quick way to generate a "dummy" self-signed certificate for testing purposes or if you are not using the certificate for authentication.
PATH=$PATH:/usr/local/ssl/bin # SSLeay 0.5.0b+ (21-Dec-95) supports a quick mechanism for generating # "dummy" certificates cd /usr/local/ssl/certs req -new -x509 -nodes -out telnetd.pem -keyout telnetd.pem ln -s telnetd.pem `x509 -noout -hash < telnetd.pem`.0
Then *test* that verify likes the setup
verify /usr/local/ssl/certs/telnetd.pem
It is fairly easy with SSLeay-0.5.x to do this. Grab der_chop from ftp://ftp.psy.uq.oz.au/pub/Crypto/SSLapps/der_chop and read the instructions inside it.
der_chop < ServerCert.der > cert.pem
Convert and encrypt it again to protect the key
rsa -inform NET -in ServerKey.der -des > key.pem
There is a ca program in SSLeay-0.5.x that includes the initial support for basically operating as your own certifying authority.
Note: There is a lot more to being a CA then having the software to issue certificates. If you plan on starting your own CA for public issuing of certificates then you should start with reading all the information about being a CA that is available from Verisign at http://www.verisign.com.
I've wrapped a script around the ca program it to make it a little easier to work with and it is included in the current SSLeay releases as apps/CA.sh.
CA.sh -newca ... will setup the right stuff for using ca CA.sh -newreq ... will generate a certificate request CA.sh -sign ... will sign the generated request and output a cert
Documentation for ca itself is very light but here are some of the basics:
The ca program uses the ssleay.conf file for most of its configuration. You will want to read through this file and customise it to match your own requirements.
Use ca -help for the standard brief usage instructions. The follow documents more information and is not yet complete but should have enough information to encourage you to experiment.
ca supports the concept of policies to define the order of fields certificate request and what fields are mandatory at what attributes get filled in.
The options for each policy are stored in sections in the configuration file (the default configuration file is called ssleay.conf)
Sections in the configuration file basically match the "normal" Windows INI file concept of named lists of variables with values.
[section name] variable1=value variable2=value
In the config file, the section to use for parameters. This lets multiple setups to be contained in the one file. By default, the default_ca variable is looked up in the [ ca ] section. So in the shipped ssleay.conf, the CA definition used is CA_default. It could be any other name.
This will generate a new certificate revocation list.
When certifiying certificates, this is the number of days for which the certified certificate is valid - i.e. the number of days from now at which the certificate will expire.
These are described later. There are 2 policies definied in the default ssleay.conf configuration file.
We always want to keep the CA's RSA key encrypted!
The -out options concatenate all the resultant certified certificates to one file, -outdir puts them in a directory, named by serial number.
Most parameters have their default values defined in the configuration file ssleay.conf (and naturally the standard defaults are reasonable :-).
The standard defaults for most of the options are in ssleay.conf in the "section" CA_default.
| name | description |
| dir | where all the CA database stuff is kept. |
| certs | where all the previously issued certificates are kept. |
| database file | a simple text database containing a record of the status of issued certificates |
| policy | the default policy name |
The policy section specifies the requirements for each of the "objects" that go into the certificates in the terms of:
The defaults for policy_match are
countryName = match stateOrProvinceName = match organizationName = match organizationalUnitName = optional commonName = supplied emailAddress = optional
The order in which the "objects" are listed in the policy section is the order in which they will occur in the generated certificate.
status: a value of 'R' - revoked, 'E' -expired or 'V' valid. issued date: When the certificate was certified. revoked date: When it was revoked, blank if not revoked. serial number: The certificate serial number. certificate: Where the certificate is located. CN: The name of the certificate.
Note: The demo file has quite a few made up values it it. The last 2 were added by the ca program and are accurate.
The ca program does not update the 'certificate' file correctly right now. The serial field should be unique as should the CN/status combination be correct. The ca program checks these at startup. What still needs to be written is a program to 'regenerate' the database file from the issued certificate list (and a CRL list).
If you think about how the Persona requests operate, it is similar to the policy_match policy and the policy_anything is similar to what Verisign are doing.
Naturally the easist thing to do is to use one of the commerical CAs listed in List of Certifying Authorities. Each CA listed has their own policies (and pricing) for providing this service. Some of the CAs will also sell you a package including the necessary details for acting as your own CA.
If you have any problems with SSLeay then please take the following steps:
Note: if using gcc then remove -fomit-frame-pointer before you try to debug things.
If you wish to report a bug then please include the following information in any bug report: (perhaps I should turn this into a bug submission FORM?)
SSLeay Details
- Version
Operating System Details
- OS Name
- OS Version
- Hardware platform
Compiler Details
- Name
- Version
Application Details
- Name
- Version
Problem Description
- include steps that will reproduce the problem (if known)
Stack Traceback (if the application dumps core)
For example:
SSLeay-0.5.1a SunOS 5.3, SPARC, SunC 3.0 SSLtelnet-0.7 Core dumps when using telnet with SSL support in bn_mul() with the following stack trackback ...
Report the bug to either ssleay@mincom.com (Eric and Tim) or ssl-bugs@mincom.com (mailing list of active developers)
See ftp://ftp.psy.uq.oz.au/pub/Crypto/SSLapps/PORT4-5 notes for brief details on the most visible changes.
If you happen to wish to send non-plaintext email then the following is the PGP key for tjh@mincom.com. (And yes I do know that the key size is small).
-----BEGIN PGP PUBLIC KEY BLOCK----- Version: 2.6 mQBNAjEqnRQAAAECAK1c6Mg2fS98Mhj8IXlXj0+qCwmjklRMty3Uq7yHhE1iNCED wZH51I3gG+HiN7AE4L1+qfjT16v+yEU66UDAzrUABRO0G1RpbSBIdWRzb24gPHRq aEBtaW5jb20uY29tPg== =2NyS -----END PGP PUBLIC KEY BLOCK-----
| -z ssl | use only SSL mode; don't even try to negotiate something different |
| -z secure | (ftp, ftpd, telnet, telnetd) don't fall back into a nonsecure mode if SSL-handshake fails. |
| -z verify=level |
|
| -z cert=certfile | (default <appname>.pem) look for an alternative file containing the certificate |
| -z key=keyfile | (default <appname>.pem) look for an alternative file containing the private RSA key |
| -z certsok | (server only) checks for a client cert and then checks the Oneline version and if it matches an entry in /etc/ssl.users then that is used as the authentication rather than the "normal" username and password. |
| -z cipher | which cipher suite is prefered; (could be given as the environment variable SSL_CIPHER) |
| SSL_CERT_DIR | directory containing the cert files |
| SSL_CERT_FILE | file containing a number of certificates |
| SSL_CIPHER | which cipher suite is prefered |
The following is a list of the commercial software that I know about that uses SSLeay. They are in the order that I've found out about them and in no way constitutes my relative opinion of the various packages.
If you wish to have your product added to this list then drop me email at tjh@mincom.com with the brief details that you would like added.
StrongHold (originally known as Apache-SSL-US) is available with full-strength encryption world-wide for commercial and non-commercial use. Developed by Community ConneXion for the USA http://stronghold.c2.net and UK Web for international use http://stronghold.ukweb.com/.
Note: the USA version is built against RSAREF.
Sioux is a secure web server based on Apache and SSLeay. Binaries available from ftp://ftp.thawte.com/pub/products/sioux/ Documentation and other information is available at http://www.thawte.com/products/sioux/. Sioux is available with full-strength encryption support world-wide.
I still don't know of any commerical browsers based on SSLeay .. perhaps Netscape and Microsoft have got his market to themselves.
Medcom has an SSLeay based secure socket relay available for evaluation by download and is free for non-commercial use.