diff options
Diffstat (limited to 'lib/ssl/doc')
27 files changed, 4578 insertions, 0 deletions
diff --git a/lib/ssl/doc/html/.gitignore b/lib/ssl/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/ssl/doc/html/.gitignore diff --git a/lib/ssl/doc/man3/.gitignore b/lib/ssl/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/ssl/doc/man3/.gitignore diff --git a/lib/ssl/doc/man6/.gitignore b/lib/ssl/doc/man6/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/ssl/doc/man6/.gitignore diff --git a/lib/ssl/doc/pdf/.gitignore b/lib/ssl/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/ssl/doc/pdf/.gitignore diff --git a/lib/ssl/doc/src/Makefile b/lib/ssl/doc/src/Makefile new file mode 100644 index 0000000000..54d274ef83 --- /dev/null +++ b/lib/ssl/doc/src/Makefile @@ -0,0 +1,130 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1999-2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% +# + +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(SSL_VSN) +APPLICATION=ssl + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = refman.xml +XML_REF3_FILES = ssl.xml new_ssl.xml +XML_REF6_FILES = ssl_app.xml + +XML_PART_FILES = release_notes.xml usersguide.xml +XML_CHAPTER_FILES = \ + ssl_protocol.xml \ + using_ssl.xml \ + pkix_certs.xml \ + create_certs.xml \ + ssl_distribution.xml \ + licenses.xml \ + notes.xml + +BOOK_FILES = book.xml + +GIF_FILES = warning.gif + +PS_FILES = + +XML_FLAGS += -defs cite cite.defs -booksty otpA4 + +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info +EXTRA_FILES = \ + $(DEFAULT_GIF_FILES) \ + $(DEFAULT_HTML_FILES) \ + $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_REF6_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) +MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +man: $(MAN3_FILES) $(MAN6_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +debug opt: + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man6 + $(INSTALL_DATA) $(MAN6_FILES) $(RELEASE_PATH)/man/man6 + +release_spec: diff --git a/lib/ssl/doc/src/book.xml b/lib/ssl/doc/src/book.xml new file mode 100644 index 0000000000..9122addb74 --- /dev/null +++ b/lib/ssl/doc/src/book.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <header titlestyle="normal"> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Secure Socket Layer </title> + <prepared>Peter Högfeldt</prepared> + <docno></docno> + <date>1999-01-25</date> + <rev>A</rev> + <file>book.sgml</file> + </header> + <insidecover> + <include file="insidecover"></include> + </insidecover> + <pagetext>SSL Application</pagetext> + <preamble> + <contents level="2"></contents> + </preamble> + <parts lift="yes"> + <xi:include href="usersguide.xml"/> + </parts> + <applications> + <xi:include href="refman.xml"/> + </applications> + <releasenotes> + <xi:include href="notes.xml"/> + </releasenotes> + <listofterms></listofterms> + <index></index> +</book> + + diff --git a/lib/ssl/doc/src/cite.defs b/lib/ssl/doc/src/cite.defs new file mode 100644 index 0000000000..45c9054e32 --- /dev/null +++ b/lib/ssl/doc/src/cite.defs @@ -0,0 +1,112 @@ +[ +{"4711","CCITT","CCITT, Red Book Vol.-FASCILE VIII.7, Recomm. X400-X.430, Geneva, 1985","jocke"}, +{"X.680","ITU-T X.680","ITU-T Recommendation X.680 (1994) | ISO/IEC 8824-1: 1995, Abstract Syntax Notation One (ASN.1): Specification of Basic Notation"}, +{"X.682","ITU-T X.682","ITU-T Recommendation X.682 (1994) | ISO/IEC 8824-3: 1995, Abstract Syntax Notation One (ASN.1): Constraint Specification"}, +{"X.690","ITU-T X.690","ITU-T Recommendation X.690 (1994) | ISO/IEC 8825-1: 1995, ASN.1 Encoding Rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)"}, +{"X.691","ITU-T X.691","ITU-T Recommendation X.691 (04/95) | ISO/IEC 8825-2: 1995, ASN.1 Encoding Rules: Specification of Packed Encoding Rules (PER)"}, +{"X.681","ITU-T X.681","ITU-T Recommendation X.681 (1994) | ISO/IEC 8824-2: 1995, Abstract Syntax Notation One (ASN.1): Information Object Specification"}, +{"X.683","ITU-T X.683","ITU-T Recommendation X.683 (1994) | ISO/IEC 8824-4: 1995, Abstract Syntax Notation One (ASN.1): Parameterization of ASN.1 Specifications"}, +{"X.509","ITU-T X.509","ITU-T Recommendation X.509 (1997) | " + "ISO/IEC 9594-8:1997 : " + "http://www.itu.int/ITU-T/asn1/database/itu-t/x/x509/1997/index.html", + peter}, +{ + "DUBUISSON", + "ASN.1 Communication between Heterogeneous Systems", + "Oliver Dubuisson: ASN.1 Communication between Heterogeneous Systems, " + "June 2000 ISBN 0-126333361-0", "nibe" + }, + { + "erlbook2", + "Concurrent Programming in ERLANG", + "J. Armstrong, R. Virding, C. Wikstrom, M. Williams: " + "Concurrent Programming in ERLANG, Prentice Hall, 1996, ISBN 0-13-508301-X", + "kent" + }, + {"practsgml", + "Practical SGML", + "Eric van Herwijnen: Practical SGML, Kluwer Academic Publishers, 1990.", + "peter" + }, + {"ssl", + "SSL", + "The SSL Protocol Version 3.0, Internet draft November 18, 1996." + "peter" + }, + {"rescorla", + "SSL and TLS", + "Eric Rescorla: SSL and TLS - Designing and Building Secure Systems, " + "Addison-Wesley, 2001, ISBN 0-201-61598-3.", + "peter" + }, + {"rfc3279", + "RFC 3279", + "Algorithms and Identifiers for the Internet X.509 Public Key " + "Infrastructure Certificate and Certificate Revocation List (CRL) Profile.", + "peter" + }, + {"rfc3280", + "RFC 3280", + "Internet X.509 Public Key Infrastructure Certificate and " + "Certificate Revocation List (CRL) Profile.", + "peter" + }, + {"rfc3281", + "RFC 3281", + "An Internet Attribute Certificate Profile for Authorization.", + "peter" + }, + {"pkcs1", + "PKCS #1", + "[RFC 2437] RSA Cryptography Specifications, version 2.0 .", + "peter" + }, + {"pkcs3", + "PKCS #3", + "Diffie-Hellman Key-Agreement Standard, version 1.4, November 1993.", + "peter" + }, + {"pkcs5", + "PKCS #5", + "[RFC 2898] Password-Based Cryptography Specification, version 2.0 .", + "peter" + }, + {"pkcs6", + "PKCS #6", + "Extended-Certificate Syntax Standard, version 1.5, November 1993.", + "peter" + }, + {"pkcs7", + "PKCS #7", + "Cryptographic Message Syntax Standard, version 1.5, November 1993.", + "peter" + }, + {"pkcs8", + "PKCS #8", + "Private-Key Information Syntax Standard, version 1.2, November 1993.", + "peter" + }, + {"pkcs9", + "PKCS #9", + "[RFC 2985] Selected Object Classes and Attribute Types, " + "version 2.0 .", + "peter" + }, + {"pkcs10", + "PKCS #10", + "[RFC 2986] Certification Request Syntax Specification, version 1.7 .", + "peter" + }, + {"pkcs12", + "PKCS #12", + "Personal Information Exchange Syntax Standard, version 1.0 DRAFT, " + "30 April 1997.", + "peter" + }, + {"schneier", + "Applied Cryptography", + "Bruce Schneier: Applied Cryptography: Protocols, Algorithms, and Source Code in C, " + "Second Edition, John Wiley & Sons, 1995, ISBN 0471117099", + "peter" + } +]. diff --git a/lib/ssl/doc/src/create_certs.xml b/lib/ssl/doc/src/create_certs.xml new file mode 100644 index 0000000000..15958ee457 --- /dev/null +++ b/lib/ssl/doc/src/create_certs.xml @@ -0,0 +1,148 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Creating Certificates</title> + <prepared>UAB/F/P Peter Högfeldt</prepared> + <docno></docno> + <date>2003-06-16</date> + <rev>A</rev> + <file>create_certs.xml</file> + </header> + <p>Here we consider the creation of example certificates. + </p> + + <section> + <title>The openssl Command</title> + <p>The <c>openssl</c> command is a utility that comes with the + OpenSSL distribution. It provides a variety of subcommands. Each + subcommand is invoked as</p> + <code type="none"><![CDATA[ + openssl subcmd <options and arguments> ]]></code> + <p>where <c>subcmd</c> denotes the subcommand in question. + </p> + <p>We shall use the following subcommands to create certificates for + the purpose of testing Erlang/OTP SSL: + </p> + <list type="bulleted"> + <item><em>req</em> to create certificate requests and a + self-signed certificates, + </item> + <item><em>ca</em> to create certificates from certificate requests.</item> + </list> + <p>We create the following certificates: + </p> + <list type="bulleted"> + <item>the <em>erlangCA</em> root certificate (a self-signed + certificate), </item> + <item>the <em>otpCA</em> certificate signed by the <em>erlangCA</em>, </item> + <item>a client certificate signed by the <em>otpCA</em>, and</item> + <item>a server certificate signed by the <em>otpCA</em>.</item> + </list> + + <section> + <title>The openssl configuration file</title> + <p>An <c>openssl</c> configuration file consist of a number of + sections, where each section starts with one line containing + <c>[ section_name ]</c>, where <c>section_name</c> is the name + of the section. The first section of the file is either + unnamed, or is named <c>[ default ]</c>. For further details + see the OpenSSL config(5) manual page. + </p> + <p>The required sections for the subcommands we are going to + use are as follows: + </p> + <table> + <row> + <cell align="left" valign="middle">subcommand</cell> + <cell align="left" valign="middle">required/default section</cell> + <cell align="left" valign="middle">override command line option</cell> + <cell align="left" valign="middle">configuration file option</cell> + </row> + <row> + <cell align="left" valign="middle">req</cell> + <cell align="left" valign="middle">[req]</cell> + <cell align="left" valign="middle">-</cell> + <cell align="left" valign="middle"><c>-config FILE</c></cell> + </row> + <row> + <cell align="left" valign="middle">ca</cell> + <cell align="left" valign="middle">[ca]</cell> + <cell align="left" valign="middle"><c>-name section</c></cell> + <cell align="left" valign="middle"><c>-config FILE</c></cell> + </row> + <tcaption>openssl subcommands to use</tcaption> + </table> + </section> + + <section> + <title>Creating the Erlang root CA</title> + <p>The Erlang root CA is created with the command</p> + <code type="none"> +\011openssl req -new -x509 -config /some/path/req.cnf \\ +\011 -keyout /some/path/key.pem -out /some/path/cert.pem </code> + <p>where the option <c>-new</c> indicates that we want to create + a new certificate request and the option <c>-x509</c> implies + that a self-signed certificate is created. + </p> + </section> + + <section> + <title>Creating the OTP CA</title> + <p>The OTP CA is created by first creating a certificate request + with the command</p> + <code type="none"> +\011openssl req -new -config /some/path/req.cnf \\ +\011 -keyout /some/path/key.pem -out /some/path/req.pem </code> + <p>and the ask the Erlang CA to sign it:</p> + <code type="none"> +\011openssl ca -batch -notext -config /some/path/req.cnf \\ +\011 -extensions ca_cert -in /some/path/req.pem -out /some/path/cert.pem </code> + <p>where the option <c>-extensions</c> refers to a section in the + configuration file saying that it should create a CA certificate, + and not a plain user certificate. + </p> + <p>The <c>client</c> and <c>server</c> certificates are created + similarly, except that the option <c>-extensions</c> then has the + value <c>user_cert</c>. + </p> + </section> + </section> + + <section> + <title>An Example</title> + <p>The following module <c>create_certs</c> is used by the Erlang/OTP + SSL application for generating certificates to be used in tests. The + source code is also found in <c>ssl-X.Y.Z/examples/certs/src</c>. + </p> + <p>The purpose of the <c>create_certs:all/1</c> function is to make + it possible to provide from the <c>erl</c> command line, the + full path name of the <c>openssl</c> command. + </p> + <p>Note that the module creates temporary OpenSSL configuration files + for the <c>req</c> and <c>ca</c> subcommands. + </p> + <codeinclude file="../../examples/certs/src/make_certs.erl" tag="" type="erl"></codeinclude> + </section> +</chapter> + + diff --git a/lib/ssl/doc/src/fascicules.xml b/lib/ssl/doc/src/fascicules.xml new file mode 100644 index 0000000000..7ee764fda3 --- /dev/null +++ b/lib/ssl/doc/src/fascicules.xml @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> + +<fascicules> + <fascicule file="usersguide" href="usersguide_frame.html" entry="no"> + User's Guide + </fascicule> + <fascicule file="refman" href="refman_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="release_notes" href="release_notes_frame.html" entry="no"> + Release Notes + </fascicule> + <fascicule file="" href="../../../../doc/print.html" entry="no"> + Off-Print + </fascicule> +</fascicules> + + diff --git a/lib/ssl/doc/src/insidecover.xml b/lib/ssl/doc/src/insidecover.xml new file mode 100644 index 0000000000..4f3f5e5951 --- /dev/null +++ b/lib/ssl/doc/src/insidecover.xml @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE bookinsidecover SYSTEM "bookinsidecover.dtd"> + +<bookinsidecover> +The Erlang/OTP SSL application includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). Copyright (c) 1998-2002 The OpenSSL Project. All rights reserved. <br></br> +This product includes cryptographic software written by Eric Young ([email protected]). This product includes software written by Tim Hudson ([email protected]). Copyright (C) 1995-1998 Eric Young ([email protected]). All rights reserved. <br></br> +For further OpenSSL and SSLeay license information se the chapter <bold>Licenses</bold> +. <vfill></vfill> + <br></br> + <tt>http://www.erlang.org</tt> + <br></br> +</bookinsidecover> + + diff --git a/lib/ssl/doc/src/licenses.xml b/lib/ssl/doc/src/licenses.xml new file mode 100644 index 0000000000..0969f9ad6e --- /dev/null +++ b/lib/ssl/doc/src/licenses.xml @@ -0,0 +1,156 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Licenses</title> + <prepared>Peter Högfeldt</prepared> + <docno></docno> + <date>2003-05-26</date> + <rev>A</rev> + <file>licenses.xml</file> + </header> + <p> <marker id="licenses"></marker> +This chapter contains in extenso versions + of the OpenSSL and SSLeay licenses. + </p> + + <section> + <title>OpenSSL License</title> + <code type="none"> +/* ==================================================================== + * Copyright (c) 1998-2002 The OpenSSL Project. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. All advertising materials mentioning features or use of this + * software must display the following acknowledgment: + * "This product includes software developed by the OpenSSL Project + * for use in the OpenSSL Toolkit. (http://www.openssl.org/)" + * + * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to + * endorse or promote products derived from this software without + * prior written permission. For written permission, please contact + * [email protected]. + * + * 5. Products derived from this software may not be called "OpenSSL" + * nor may "OpenSSL" appear in their names without prior written + * permission of the OpenSSL Project. + * + * 6. Redistributions of any form whatsoever must retain the following + * acknowledgment: + * "This product includes software developed by the OpenSSL Project + * for use in the OpenSSL Toolkit (http://www.openssl.org/)" + * + * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY + * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + * ==================================================================== + * + * This product includes cryptographic software written by Eric Young + * ([email protected]). This product includes software written by Tim + * Hudson ([email protected]). + * + */ </code> + </section> + + <section> + <title>SSLeay License</title> + <code type="none"> +/* Copyright (C) 1995-1998 Eric Young ([email protected]) + * All rights reserved. + * + * This package is an SSL implementation written + * by Eric Young ([email protected]). + * The implementation was written so as to conform with Netscapes SSL. + * + * This library is free for commercial and non-commercial use as long as + * the following conditions are aheared to. The following conditions + * apply to all code found in this distribution, be it the RC4, RSA, + * lhash, DES, etc., code; not just the SSL code. The SSL documentation + * included with this distribution is covered by the same copyright terms + * except that the holder is Tim Hudson ([email protected]). + * + * Copyright remains Eric Young's, and as such any Copyright notices in + * the code are not to be removed. + * If this package is used in a product, Eric Young should be given attribution + * as the author of the parts of the library used. + * This can be in the form of a textual message at program startup or + * in documentation (online or textual) provided with the package. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. All advertising materials mentioning features or use of this software + * must display the following acknowledgement: + * "This product includes cryptographic software written by + * Eric Young ([email protected])" + * The word 'cryptographic' can be left out if the rouines from the library + * being used are not cryptographic related :-). + * 4. If you include any Windows specific code (or a derivative thereof) from + * the apps directory (application code) you must include an acknowledgement: + * "This product includes software written by Tim Hudson ([email protected])" + * + * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * + * The licence and distribution terms for any publically available version or + * derivative of this code cannot be changed. i.e. this code cannot simply be + * copied and put under another distribution licence + * [including the GNU Public Licence.] + */ </code> + </section> +</chapter> + + diff --git a/lib/ssl/doc/src/make.dep b/lib/ssl/doc/src/make.dep new file mode 100644 index 0000000000..2ff81bee1f --- /dev/null +++ b/lib/ssl/doc/src/make.dep @@ -0,0 +1,30 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex create_certs.tex licenses.tex new_ssl.tex \ + pkix_certs.tex refman.tex ssl.tex ssl_app.tex \ + ssl_distribution.tex ssl_protocol.tex usersguide.tex \ + using_ssl.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: refman.xml + +create_certs.tex: ../../examples/certs/src/make_certs.erl + +using_ssl.tex: ../../examples/src/client_server.erl + +pkix_certs.tex: ../../../../system/doc/definitions/cite.defs + +ssl_protocol.tex: ../../../../system/doc/definitions/cite.defs + diff --git a/lib/ssl/doc/src/new_ssl.xml b/lib/ssl/doc/src/new_ssl.xml new file mode 100644 index 0000000000..f50f714fe6 --- /dev/null +++ b/lib/ssl/doc/src/new_ssl.xml @@ -0,0 +1,678 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved aniline's at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>ssl</title> + <prepared>Ingela Anderton Andin</prepared> + <responsible>Ingela Anderton Andin</responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>2003-03-25</date> + <rev></rev> + <file>new_ssl.xml</file> + </header> + <module>new_ssl</module> + <modulesummary>Interface Functions for Secure Socket Layer</modulesummary> + <description> + <p>This module contains interface functions to the Secure Socket + Layer. + </p> + </description> + + <section> + <title>NEW SSL</title> + + <p>This manual page describes functions that are defined + in the ssl module and represents the new ssl implementation + that coexists with the old one, as the new implementation + is not yet complete enough to replace the old one.</p> + + <p>The new implementation can be + accessed by providing the option {ssl_imp, new} to the + ssl:connect and ssl:listen functions.</p> + + <p>The new implementation is Erlang based and all logic + is in Erlang and only payload encryption calculations are + done in C via the crypto application. The main reason for + making a new implementation is that the old solution was + very crippled as the control of the ssl-socket was deep + down in openssl making it hard if not impossible to + support all inet options, ipv6 and upgrade of a tcp + connection to a ssl connection. The alfa version has a + few limitations that will be removed before the ssl-4.0 + release. Main differences and limitations in the alfa are + listed below.</p> + + <list type="bulleted"> + <item>New ssl requires the crypto + application.</item> + <item>The option reuseaddr is + supported and the default value is false as in gen_tcp. + Old ssl is patched to accept that the option is set to + true to provide a smoother migration between the + versions. In old ssl the option is hard coded to + true.</item> + <item>ssl:version/0 is replaced by + ssl:versions/0</item> + <item>ssl:ciphers/0 is replaced by + ssl:cipher_suites/0</item> + <item>ssl:pid/1 is a + meaningless function in new ssl and will be deprecated in + ssl-4.0 until it is removed it will return a valid but + meaningless pid.</item> + <item>New API functions are + ssl:shutdown/2, ssl:cipher_suites/[0,1] and + ssl:versions/0</item> + <item>Diffie-Hellman keyexchange is + not supported yet.</item> + <item>CRL and policy certificate + extensions are not supported yet. </item> + <item>Supported SSL/TLS-versions are SSL-3.0 and TLS-1.0 </item> + <item>For security reasons sslv2 is not supported.</item> + </list> + + </section> + + <section> + <title>COMMON DATA TYPES</title> + <p>The following data types are used in the functions below: + </p> + + <p><c>boolean() = true | false</c></p> + + <p><c>property() = atom()</c></p> + + <p><c>option() = socketoption() | ssloption() | transportoption()</c></p> + + <p><c>socketoption() = [{property(), term()}] - defaults to + [{mode,list},{packet, 0},{header, 0},{active, true}]. + </c></p> + + <p>For valid options + see <seealso marker="kernel:inet">inet(3) </seealso> and + <seealso marker="kernel:gen_tcp">gen_tcp(3) </seealso>. + </p> + + <p> <c>ssloption() = {verify, verify_type()} | + {fail_if_no_peer_cert, boolean()} + {depth, integer()} | + {certfile, path()} | {keyfile, path()} | {password, string()} | + {cacertfile, path()} | {ciphers, ciphers()} | {ssl_imp, ssl_imp()} + | {reuse_sessions, boolean()} | {reuse_session, fun()} + </c></p> + + <p><c>transportoption() = {CallbackModule, DataTag, ClosedTag} + - defaults to {gen_tcp, tcp, tcp_closed}. Ssl may be + run over any reliable transport protocol that has + an equivalent API to gen_tcp's.</c></p> + + <p><c> CallbackModule = + atom()</c> + </p> <p><c> DataTag = + atom() - tag used in socket data message.</c></p> + <p><c> ClosedTag = atom() - tag used in + socket close message.</c></p> + + <p><c>verify_type() = verify_none | verify_peer</c></p> + + <p><c>path() = string() - representing a file path.</c></p> + + <p><c>host() = hostname() | ipaddress()</c></p> + + <p><c>hostname() = string()</c></p> + + <p><c> + ip_address() = {N1,N2,N3,N4} % IPv4 + | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6 </c></p> + + <p><c>sslsocket() - opaque to the user. </c></p> + + <p><c>protocol() = sslv3 | tlsv1 </c></p> + + <p><c>ciphers() = [ciphersuite()] | sting() (according to old API)</c></p> + + <p><c>ciphersuite() = + {key_exchange(), cipher(), hash(), exportable()}</c></p> + + <p><c>key_exchange() = rsa | dh_dss | dh_rsa | dh_anon | dhe_dss + | dhe_rsa | krb5 | KeyExchange_export + </c></p> + + <p><c>cipher() = rc4_128 | idea_cbc | des_cbc | '3des_ede_cbc' + des40_cbc | dh_dss | aes_128_cbc | aes_256_cbc | + rc2_cbc_40 | rc4_40 </c></p> + + <p> <c>hash() = md5 | sha + </c></p> + + <p> <c>exportable() = export | no_export | ignore + </c></p> + + <p><c>ssl_imp() = new | old - default is old.</c></p> + + </section> + +<section> + <title>SSL OPTION DESCRIPTIONS</title> + + <taglist> + <tag>{verify, verify_type()}</tag> + <item> If <c>verify_none</c> is specified x509-certificate + path validation errors at the client side + will not automatically cause the connection to fail, as + it will if the verify type is <c>verify_peer</c>. See also + the option verify_fun. + Servers only do the path validation if <c>verify_peer</c> is set to + true, as it then will + send a certificate request to + the client (this message is not sent if the verify option is + <c>verify_none</c>) and you may then also want to specify + the option <c>fail_if_no_peer_cert</c>. + </item> + + <tag>{fail_if_no_peer_cert, boolean()}</tag> + <item>Used together with {verify, verify_peer} by a ssl server. + If set to true, + the server will fail if the client does not have a certificate + to send, e.i sends a empty certificate, if set to false it will + only fail if the client sends a invalid certificate (an empty + certificate is considered valid). + </item> + + <tag>{verify_fun, fun(ErrorList) -> boolean()}</tag> + <item>Used by the ssl client to determine if + x509-certificate path validations errors are acceptable or + if the connection should fail. Defaults to: + +<code> +fun(ErrorList) -> + case lists:foldl(fun({bad_cert,unknown_ca}, Acc) -> + Acc; + (Other, Acc) -> + [Other | Acc] + end, [], ErrorList) of + [] -> + true; + [_|_] -> + false + end +end +</code> + I.e. by default if the only error found was that the CA-certificate + holder was unknown this will be accepted. + + Possible errors in the error list are: + {bad_cert, cert_expired}, {bad_cert, invalid_issuer}, + {bad_cert, invalid_signature}, {bad_cert, name_not_permitted}, + {bad_cert, unknown_ca}, + {bad_cert, cert_expired}, {bad_cert, invalid_issuer}, + {bad_cert, invalid_signature}, {bad_cert, name_not_permitted}, + {bad_cert, cert_revoked} (not implemented yet), + {bad_cert, unknown_critical_extension} or {bad_cert, term()} (Will + be relevant later when an option is added for the user to be able to verify application specific extensions.) + </item> + + <tag>{depth, integer()}</tag> + <item>Specifies the maximum + verification depth, i.e. how far in a chain of certificates the + verification process can proceed before the verification is + considered to fail. Peer certificate = 0, CA certificate = 1, + higher level CA certificate = 2, etc. The value 2 thus means + that a chain can at most contain peer cert, CA cert, next CA + cert, and an additional CA cert. The default value is 1. + </item> + + <tag>{certfile, path()}</tag> + <item>Path to a file containing the + user's certificate. Optional for clients but note + that some servers requires that the client can certify + itself. </item> + <tag>{keyfile, path()}</tag> + <item>Path to file containing user's + private PEM encoded key. As PEM-files may contain several + entries this option defaults to the same file as given by + certfile option.</item> + <tag>{password, string()}</tag> + <item>String containing the user's password. + Only used if the private keyfile is password protected. + </item> + <tag>{cacertfile, path()}</tag> + <item>Path to file containing PEM encoded + CA certificates (trusted certificates used for verifying a peer + certificate). May be omitted if you do not want to verify + the peer.</item> + + <tag>{ciphers, ciphers()}</tag> + <item>The function <c>ciphers_suites/0</c> can + be used to find all available ciphers. + </item> + + <tag>{ssl_imp, ssl_imp()}</tag> + <item>Specify which ssl implementation you want to use. + </item> + + <tag>{reuse_sessions, boolean()}</tag> + <item>Specifies if ssl sessions should be reused + when possible. + </item> + + <tag>{reuse_session, fun(SuggestedSessionId, + PeerCert, Compression, CipherSuite) -> boolean()}</tag> + <item>Enables the ssl server to have a local policy + for deciding if a session should be reused or not, + only meaning full if <c>reuse_sessions</c> is set to true. + SuggestedSessionId is a binary(), PeerCert is a DER encoded + certificate, Compression is an enumeration integer + and CipherSuite of type ciphersuite(). + </item> + </taglist> + </section> + + <section> + <title>General</title> + + <p>When a ssl socket is in active mode (the default), data from the + socket is delivered to the owner of the socket in the form of + messages: + </p> + <list type="bulleted"> + <item>{ssl, Socket, Data} + </item> + <item>{ssl_closed, Socket} + </item> + <item> + {ssl_error, Socket, Reason} + </item> + </list> + + <p>A <c>Timeout</c> argument specifies a timeout in milliseconds. The + default value for a <c>Timeout</c> argument is <c>infinity</c>. + </p> + </section> + + <funcs> + <func> + <name>cipher_suites() -></name> + <name>cipher_suites(Type) -> ciphers()</name> + <fsummary> Returns a list of supported cipher suites</fsummary> + <type> + <v>Type = erlang | openssl</v> + + </type> + <desc><p>Returns a list of supported cipher suites. + cipher_suites() is equivalent to cipher_suites(erlang). + Type openssl is provided for backwards compatibility with + old ssl that used openssl. + </p> + </desc> + </func> + + <func> + <name>connect(Socket, SslOptions) -> </name> + <name>connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} + | {error, Reason}</name> + <fsummary> Upgrades a gen_tcp, or + equivalent, connected socket to a ssl socket. </fsummary> + <type> + <v>Socket = socket()</v> + <v>SslOptions = [ssloption()]</v> + <v>Timeout = integer() | infinity</v> + <v>SslSocket = sslsocket()</v> + <v>Reason = term()</v> + </type> + <desc> <p>Upgrades a gen_tcp, or equivalent, + connected socket to a ssl socket e.i performs the + client-side ssl handshake.</p> + </desc> + </func> + + <func> + <name>connect(Host, Port, Options) -></name> + <name>connect(Host, Port, Options, Timeout) -> + {ok, SslSocket} | {error, Reason}</name> + <fsummary>Opens an ssl connection to Host, Port. </fsummary> + <type> + <v>Host = host()</v> + <v>Port = integer()</v> + <v>Options = [option()]</v> + <v>Timeout = integer() | infinity</v> + <v>SslSocket = sslsocket()</v> + <v>Reason = term()</v> + </type> + <desc> <p>Opens an ssl connection to Host, Port.</p> </desc> + </func> + + <func> + <name>close(SslSocket) -> ok | {error, Reason}</name> + <fsummary>Close a ssl connection</fsummary> + <type> + <v>SslSocket = sslsocket()</v> + <v>Reason = term()</v> + </type> + <desc><p>Close a ssl connection.</p> + </desc> + </func> + + <func> + <name>controlling_process(SslSocket, NewOwner) -> + ok | {error, Reason}</name> + + <fsummary>Assigns a new controlling process to the + ssl-socket.</fsummary> + + <type> + <v>SslSocket = sslsocket()</v> + <v>NewOwner = pid()</v> + <v>Reason = term()</v> + </type> + <desc><p>Assigns a new controlling process to the ssl-socket. A + controlling process is the owner of a ssl-socket, and receives + all messages from the socket.</p> + </desc> + </func> + + <func> + <name>connection_info(SslSocket) -> + {ok, {ProtocolVersion, CipherSuite}} | {error, Reason} </name> + <fsummary>Returns the negotiated protocol version and cipher suite. + </fsummary> + <type> + <v>CipherSuite = ciphersuite()</v> + <v>ProtocolVersion = protocol()</v> + </type> + <desc><p>Returns the negotiated protocol version and cipher suite.</p> + </desc> + </func> + + <func> + <name>getopts(Socket) -> </name> + <name>getopts(Socket, OptionNames) -> + {ok, [socketoption()]} | {error, Reason}</name> + <fsummary>Get the value of the specified options.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>OptionNames = [property()]</v> + </type> + <desc> + <p>Get the value of the specified socket options, if no + options are specified all options are returned. + </p> + </desc> + </func> + + <func> + <name>listen(Port, Options) -> + {ok, ListenSocket} | {error, Reason}</name> + <fsummary>Creates a ssl listen socket.</fsummary> + <type> + <v>Port = integer()</v> + <v>Options = options()</v> + <v>ListenSocket = sslsocket()</v> + </type> + <desc> + <p>Creates a ssl listen socket.</p> + </desc> + </func> + + <func> + <name>peercert(Socket) -> </name> + <name>peercert(Socket, Opts) -> {ok, Cert} | {error, Reason}</name> + <fsummary>Return the peer certificate.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Opts = [] | [otp] | [plain] </v> + <v>Cert = term()</v> + <v>Subject = term()</v> + </type> + <desc> + <p><c>peercert(Cert)</c> is equivalent to <c>peercert(Cert, [])</c>. + </p> + <p>The form of the returned certificate depends on the + options. + </p> + <p>If the options list is empty the certificate is returned as + a DER encoded binary. + </p> + <p>The option <c>otp</c> or <c>plain</c> implies that the + certificate will be returned as a parsed ASN.1 structure in the + form of an Erlang term. For detail see the public_key application. + Currently only plain is officially supported see the public_key users + guide. + </p> + </desc> + </func> + <func> + <name>peername(Socket) -> {ok, {Address, Port}} | + {error, Reason}</name> + <fsummary>Return peer address and port.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Address = ipaddress()</v> + <v>Port = integer()</v> + </type> + <desc> + <p>Returns the address and port number of the peer.</p> + </desc> + </func> + + <func> + <name>recv(Socket, Length) -> </name> + <name>recv(Socket, Length, Timeout) -> {ok, Data} | {error, + Reason}</name> + <fsummary>Receive data on a socket.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Length = integer()</v> + <v>Timeout = integer()</v> + <v>Data = [char()] | binary()</v> + </type> + <desc> + <p>This function receives a packet from a socket in passive + mode. A closed socket is indicated by a return value + <c>{error, closed}</c>.</p> + <p>The <c>Length</c> argument is only meaningful when + the socket is in <c>raw</c> mode and denotes the number of + bytes to read. If <c>Length</c> = 0, all available bytes are + returned. If <c>Length</c> > 0, exactly <c>Length</c> + bytes are returned, or an error; possibly discarding less + than <c>Length</c> bytes of data when the socket gets closed + from the other side.</p> + <p>The optional <c>Timeout</c> parameter specifies a timeout in + milliseconds. The default value is <c>infinity</c>.</p> + </desc> + </func> + + <func> + <name>send(Socket, Data) -> ok | {error, Reason}</name> + <fsummary>Write data to a socket.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Data = iolist() | binary()</v> + </type> + <desc> + <p>Writes <c>Data</c> to <c>Socket</c>. </p> + <p>A notable return value is <c>{error, closed}</c> indicating that + the socket is closed.</p> + </desc> + </func> + <func> + <name>setopts(Socket, Options) -> ok | {error, Reason}</name> + <fsummary>Set socket options.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Options = [socketoption]()</v> + </type> + <desc> + <p>Sets options according to <c>Options</c> for the socket + <c>Socket</c>. </p> + </desc> + </func> + + <func> + <name>shutdown(Socket, How) -> ok | {error, Reason}</name> + <fsummary>Immediately close a socket</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>How = read | write | read_write</v> + <v>Reason = reason()</v> + </type> + <desc> + <p>Immediately close a socket in one or two directions.</p> + <p><c>How == write</c> means closing the socket for writing, + reading from it is still possible.</p> + <p>To be able to handle that the peer has done a shutdown on + the write side, the <c>{exit_on_close, false}</c> option + is useful.</p> + </desc> + </func> + + <func> + <name>ssl_accept(ListenSocket) -> </name> + <name>ssl_accept(ListenSocket, Timeout) -> ok | {error, Reason}</name> + <fsummary>Perform server-side SSL handshake</fsummary> + <type> + <v>ListenSocket = sslsocket()</v> + <v>Timeout = integer()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>The <c>ssl_accept</c> function establish the SSL connection + on the server side. It should be called directly after + <c>transport_accept</c>, in the spawned server-loop.</p> + </desc> + </func> + + <func> + <name>ssl_accept(ListenSocket, SslOptions) -> </name> + <name>ssl_accept(ListenSocket, SslOptions, Timeout) -> {ok, Socket} | {error, Reason}</name> + <fsummary>Perform server-side SSL handshake</fsummary> + <type> + <v>ListenSocket = socket()</v> + <v>SslOptions = ssloptions()</v> + <v>Timeout = integer()</v> + <v>Reason = term()</v> + </type> + <desc> + <p> Upgrades a gen_tcp, or + equivalent, socket to a ssl socket e.i performs the + ssl server-side handshake.</p> + </desc> + </func> + + <func> + <name>sockname(Socket) -> {ok, {Address, Port}} | + {error, Reason}</name> + <fsummary>Return the local address and port.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Address = ipaddress()</v> + <v>Port = integer()</v> + </type> + <desc> + <p>Returns the local address and port number of the socket + <c>Socket</c>.</p> + </desc> + </func> + + <func> + <name>start() -> </name> + <name>start(Type) -> ok | {error, Reason}</name> + <fsummary>Starts the Ssl application. </fsummary> + <type> + <v>Type = permanent | transient | temporary</v> + </type> + <desc> + <p>Starts the Ssl application. Default type + is temporary. + <seealso marker="kernel:application">application(3)</seealso></p> + </desc> + </func> + <func> + <name>stop() -> ok </name> + <fsummary>Stops the Ssl application.</fsummary> + <desc> + <p>Stops the Ssl application. + <seealso marker="kernel:application">application(3)</seealso></p> + </desc> + </func> + + <func> + <name>transport_accept(Socket) -></name> + <name>transport_accept(Socket, Timeout) -> + {ok, NewSocket} | {error, Reason}</name> + <fsummary>Accept an incoming connection and + prepare for <c>ssl_accept</c></fsummary> + <type> + <v>Socket = NewSocket = sslsocket()</v> + <v>Timeout = integer()</v> + <v>Reason = reason()</v> + </type> + <desc> + <p>Accepts an incoming connection request on a listen socket. + <c>ListenSocket</c> must be a socket returned from + <c>listen/2</c>. The socket returned should be passed to + <c>ssl_accept</c> to complete ssl handshaking and + establishing the connection.</p> + <warning> + <p>The socket returned can only be used with <c>ssl_accept</c>, + no traffic can be sent or received before that call.</p> + </warning> + <p>The accepted socket inherits the options set for + <c>ListenSocket</c> in <c>listen/2</c>.</p> + <p>The default + value for <c>Timeout</c> is <c>infinity</c>. If + <c>Timeout</c> is specified, and no connection is accepted + within the given time, <c>{error, timeout}</c> is + returned.</p> + </desc> + </func> + + <func> + <name>versions() -> + [{SslAppVer, SupportedSslVer, AvailableSslVsn}]</name> + <fsummary>Returns version information relevant for the + ssl application.</fsummary> + <type> + <v>SslAppVer = string()</v> + <v>SupportedSslVer = [protocol()]</v> + <v>AvailableSslVsn = [protocol()]</v> + </type> + <desc> + <p> + Returns version information relevant for the + ssl application.</p> + </desc> + </func> + </funcs> + + <section> + <title>SEE ALSO</title> + <p><seealso marker="kernel:inet">inet(3) </seealso> and + <seealso marker="kernel:gen_tcp">gen_tcp(3) </seealso> + </p> + </section> + +</erlref> + diff --git a/lib/ssl/doc/src/note.gif b/lib/ssl/doc/src/note.gif Binary files differnew file mode 100644 index 0000000000..6fffe30419 --- /dev/null +++ b/lib/ssl/doc/src/note.gif diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml new file mode 100644 index 0000000000..14dfe616ba --- /dev/null +++ b/lib/ssl/doc/src/notes.xml @@ -0,0 +1,1132 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>SSL Release Notes</title> + <prepared>Peter Högfeldt</prepared> + <docno></docno> + <date>2003-08-03</date> + <rev>G</rev> + <file>notes.xml</file> + </header> + <p>This document describes the changes made to the SSL application. + </p> + +<section><title>SSL 3.10.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A ticker process could potentially be blocked + indefinitely trying to send a tick to a node not + responding. If this happened, the connection would not be + brought down as it should.</p> + <p> This requires erts-5.7.4 and kernel-2.13.4 or later + to be able to get the erlang distribution over ssl to work.</p> + <p> + Own Id: OTP-8218</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the frames are removed.</p> + <p> + Own Id: OTP-8250</p> + </item> + <item> + <p> + Code cleanup from Kostis.</p> + <p> + Own Id: OTP-8260</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 3.10.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The ssl:ssl_accept/3 issue was not properly fixed in the + previous patch, see OTP-8244.</p> + <p> + Own Id: OTP-8275 Aux Id: seq11451 </p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 3.10.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Allow clients to not send certificates if option + <c>fail_if_no_peer_cert</c> was not set.</p> + <p> + Own Id: OTP-8224</p> + </item> + <item> + <p>A ssl:ssl_accept/3 could crash a connection if the + timing was wrong.</p> <p>Removed info message if the + socket closed without a proper disconnect from the ssl + layer. </p> <p>ssl:send/2 is now blocking until the + message is sent.</p> + <p> + Own Id: OTP-8244 Aux Id: seq11420 </p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 3.10.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A client could avoid a certificate check if the client + code didn't send the requested certificate.</p> + <p> + Own Id: OTP-8137</p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 3.10.3</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Packet handling was not implemented correctly.</p> + <p>Inet option handling support have been improved.</p> + <p>The <c>verify_fun</c> is now invoked even if + verify_peer is used, that implies that by default + {bad_cert,unknown_ca} is an accepted fault during the + client connection phase. The check can still be done by + suppling another verify_fun.</p> + <p> + Own Id: OTP-8011 Aux Id: seq11287 </p> + </item> + </list> + </section> + +</section> + + +<section><title>SSL 3.10.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A "new_ssl" socket was not closed if the controlling + process died without calling ssl:close/1.</p> + <p> + Own Id: OTP-7963 Aux Id: seq11276 </p> + </item> + </list> + </section> + +</section> + +<section><title>SSL 3.10.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug that caused the ssl handshake finished message + to be calculated wrongly under the circumstances that the + server did not send the trusted cert and that the + previous cert did not have the extension telling us the + trusted certs name. This manifested it self as + bad_record_mac alert from the server.</p> + <p> + Own Id: OTP-7878</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The cacertsfile option is now optional for ssl servers.</p> + <p> + Own Id: OTP-7656</p> + </item> + <item> + <p> + For the ssl client the options cacertfile, certfile and + keyfile are now optional as they are not always needed + depending on configuration of the client itself and the + configuration of the server. Also as PEM-files may + contain more than one entry the keyfile option will + default to the same file as given by the certfile option.</p> + <p> + Own Id: OTP-7870</p> + </item> + <item> + <p> + Added new ssl client option verify_fun.</p> + <p> + Own Id: OTP-7871</p> + </item> + </list> + </section> + +</section> + + <section><title>SSL 3.10</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Error log entries are now formatted correctly.</p> + <p> + Own Id: OTP-7258</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + All handling of X509-certificates and public keys have + been moved to the new application public_key.</p> + <p> + Own Id: OTP-6894</p> + </item> + <item> + <p> + New ssl now supports SSL-3.0 and TLS-1.0</p> + <p> + Own Id: OTP-7037</p> + </item> + <item> + <p> + New ssl now supports all inet-packet types.</p> + <p> + Own Id: OTP-7039</p> + </item> + <item> + <p> + The new ssl-server is now able to send a certificate + request to the client. However new options may be + introduced later to fully support all features regarding + certificate requests.</p> + <p> + Own Id: OTP-7150</p> + </item> + </list> + </section> + + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p> + Running erlang distribution over ssl don't work as + described in the documentation.</p> + <p> + Own Id: OTP-7536</p> + </item> + </list> + </section> + + </section> + + + <section><title>SSL 3.9</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + ssl_prim.erl was passing an FD rather than an #sslsocket + to ssl_broker:ssl_accept_prim. This could cause problems + in the deprecated accept function, this will not cause + any more problems however this function is deprecated!</p> + <p> + Own Id: OTP-6926</p> + </item> + <item> + <p> + Erlang distribution over ssl was broken after R11B-0, + this has now been fixed.</p> + <p> + Own Id: OTP-7004</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + All inet options are available in the new ssl + implementation that is released as a alfa in ssl-3.9 and + will replace the old implementation in ssl-4.0. This will + not be fixed in the old implementation.</p> + <p> + Own Id: OTP-4677</p> + </item> + <item> + <p> + The new ssl implementation released as a alfa in this + version supports upgrading of a tcp connection to a ssl + connection so that http client and servers may implement + RFC 2817.</p> + <p> + Own Id: OTP-5510</p> + </item> + <item> + <p>A new implementation of ssl is released as a alfa + version in ssl-3.9 it will later replace the old + implementation in ssl-4.0. The new implementation can be + accessed by providing the option {ssl_imp, new} to the + ssl:connect and ssl:listen functions.</p> + <p>The new implementation is Erlang based and all logic + is in Erlang and only payload encryption calculations are + done in C via the crypto application. The main reason for + making a new implementation is that the old solution was + very crippled as the control of the ssl-socket was deep + down in openssl making it hard if not impossible to + support all inet options, ipv6 and upgrade of a tcp + connection to a ssl connection. The alfa version has a + few limitations that will be removed before the ssl-4.0 + release. Main differences and limitations in the alfa are + listed below.</p> + + <list type="bulleted"> <item>New ssl requires the crypto + application.</item> <item>The option reuseaddr is + supported and the default value is false as in gen_tcp. + Old ssl is patched to accept that the option is set to + true to provide a smoother migration between the + versions. In old ssl the option is hard coded to + true.</item> <item>ssl:version/0 is replaced by + ssl:versions/0</item> <item>ssl:ciphers/0 is replaced by + ssl:cipher_suites/0</item> <item>ssl:pid/1 is a + meaningless function in new ssl and will be deprecated in + ssl-4.0 until it is removed it will return a valid but + meaningless pid.</item> <item>New API functions are + ssl:shutdown/2, ssl:cipher_suites/[0,1] and + ssl:versions/0</item> <item>Diffie-Hellman keyexchange is + not supported.</item> <item>Not all inet packet types are + supported.</item> <item>CRL and policy certificate + extensions are not supported.</item> <item>In this alfa + only sslv3 is enabled, although tlsv1 and tlsv1.1 + versions are implemented and will be supported in future + versions.</item> <item>For security reasons sslv2 is not + supported.</item> </list> + <p> + Own Id: OTP-6619</p> + </item> + <item> + <p> + New ssl implementation, released as alfa in ssl-3.9, + supports ipv6. It will not be supported in the old + implementation.</p> + <p> + Own Id: OTP-6637 Aux Id: OTP-6636 </p> + </item> + </list> + </section> + + </section> + + <section> + <title>SSL 3.1.1.1</title> + + <section> + <title>Minor Makefile changes</title> + <list type="bulleted"> + <item> + <p>Removed use of <c>erl_flags</c> from Makefile.</p> + <p>Own Id: OTP-6689</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 3.1.1</title> + + <section> + <title>Crash on error in ssl_accept</title> + <list type="bulleted"> + <item> + <p>A bug in ssl_accept could cause all ssl + connections to hang when a connection + attempt was closed by the client while + the server was in <c>ssl_accept</c>.</p> + <p>Own Id: OTP-6612 Aux Id: seq10599</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 3.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>SSL now uses a two-phase accept, with a separate accept + calls for the socket and the ssl protocol. This avoids + timeouts when a client doesn't initiate ssl handshake.</p> + <p>With the old implementation of accept, the server + was locked by a client, if the client didn't do + proper ssl handshake.</p> + <p>Own Id: OTP-6418 Aux Id: seq10105</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 3.0.12</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>An integer array pointing to a struct pollfd array, is + now reset before file descriptors are collected to be + included in a call to poll(). This is to prevent file + descriptors to be mixed up.</p> + <p>Own Id: OTP-6084</p> + </item> + <item> + <p>The generation of the module ssl_pkix_oid contained + multiple identifiers, which made the mapping between + atoms and identifiers not one-to-one.</p> + <p>Own Id: OTP-6085</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 3.0.11</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The state of a connection in active mode could be in a + restrictive state, so that an internal tcp_closed message + was incorrectly considered illegal, resulting in a + premature termination of the connection process.</p> + <p>Own Id: OTP-5972 Aux Id: seq10188 </p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 3.0.10</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Erlang distribution over SSL was broken. Corrected. + (Thanks to Fredrik Thulin.)</p> + <p>Own Id: OTP-5863</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 3.0.9</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The port program for the ssl application could waste huge + amounts of CPU time if a write could not be completed + directly and was put in the write queue. (Only on platforms + where poll() is used, such as Solaris and Linux.)</p> + <p>Own Id: OTP-5784</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 3.0.8</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A process reading only a portion of a sufficiently large + amount of data from an accepted socket, and then quering + the ssl library (e.g. ssl:getpeername()), would cause a + global deadlock in the esock port program.</p> + <p>Own Id: OTP-5702</p> + </item> + <item> + <p>A spelling error in the module <c>ssl_pkix</c> caused the + call to <c>ssl:peercert/2</c> to fail when the option + <c>subject</c> was used.</p> + <p>Own Id: OTP-5708</p> + </item> + <item> + <p>Because fopen() on Solaris 8 can't handle file + descriptor numbers above 255, reading of certificate + files would fail if all file descriptors below 256 were + in use (typically, if many connections were open). This + problem has been worked around.</p> + <p>The ssl application's port program used to use + select(), which meant that it could not handle more than + FD_SETSIZE file descriptors (usually 1024). To eliminate + that limitation, poll() is now used on all platforms that + support it.</p> + <p>Solaris/Sparc, 64-bit emulator: The SO_REUSEADDR + option was not set for listen sockets, which essentially + made the ssl application unusable. Corrected.</p> + <p>The default listen queue size for ssl port program was + changed to 128 (from 5).</p> + <p>Own Id: OTP-5755 Aux Id: seq10068 </p> + </item> + </list> + </section> + </section> + + <section> + <title>Ssl 3.0.7</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The R/W buffer length i esock.c was too small. It has + been increased from 4k to 32k.</p> + <p>Own Id: OTP-5620</p> + </item> + </list> + </section> + </section> + + <section> + <title>Ssl 3.0.6</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>A configuration option for choosing protocol versions has + been added (<c>sslv2</c>, <c>sslv3</c>, and + <c>tlsv1</c>).</p> + <p>Own Id: OTP-5429 Aux Id: seq9755 </p> + </item> + </list> + </section> + </section> + + <section> + <title>Ssl 3.0.5</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Linked in drivers in the crypto, and asn1 applications + are now compiled with the -D_THREAD_SAFE and -D_REENTRANT + switches on unix when the emulator has thread support + enabled.</p> + <p>Linked in drivers on MacOSX are not compiled with the + undocumented -lbundle1.o switch anymore. Thanks to Sean + Hinde who sent us a patch.</p> + <p>Linked in driver in crypto, and port programs in ssl, now + compiles on OSF1.</p> + <p>Minor makefile improvements in runtime_tools.</p> + <p>Own Id: OTP-5346</p> + </item> + </list> + </section> + </section> + + <section> + <title>Ssl 3.0.4</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p><c>ssl:recv/3</c> with finite timeout value, closed the + connection at timeout.</p> + <p>Own Id: OTP-4882</p> + </item> + </list> + </section> + </section> + + <section> + <title>Ssl 3.0.3</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>When a file descriptor was marked for closing, and and + end-of-file condition had already been detected, the file + descriptor was never closed.</p> + <p>Own Id: OTP-5093 Aux Id: seq8806 </p> + </item> + <item> + <p>When the number of open file descriptors reached + FD_SETSIZE, the SSL port program entered a busy loop.</p> + <p>Own Id: OTP-5094 Aux Id: seq8806 </p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The SSL application now supports SSL sessions for + servers, which typically speeds up HTTP requests from + browsers.</p> + <p>Own Id: OTP-5095</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 3.0.2</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The UTF8String type is now defined in asn1-1.4.4.2 and + later. Therefore the definitions of UTF8String has been + removed from the ASN.1 modules PKIX1Explicit88.asn1 and + PKIXAttributeCertificate.asn1. The SSL application can now + only be built using asn-1.4.4.2 or later.</p> + <p>OwnId: OTP-4971.</p> + </item> + </list> + </section> + + <section> + <title>Known Bugs and Problems</title> + <p>See SSL-3.0. + </p> + </section> + </section> + + <section> + <title>SSL 3.0.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>An unexpected object identifier would crash <c>ssl:peercert</c>. </p> + <p>OwnId: OTP-4771.</p> + </item> + </list> + </section> + + <section> + <title>Known Bugs and Problems</title> + <p>See SSL-3.0. + </p> + </section> + </section> + + <section> + <title>SSL 3.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The <c>cache_timout</c> option was silently ignored. It had + to do with SSL sessions, where multiple connections can occur. + Since the Erlang SSL application does not support sessions the + option is still ignored, and consequently the documentation + about it has been removed.</p> + <p>OwnId: OTP-3146</p> + </item> + <item> + <p>The Erlang SSL application is now based on OpenSSL version + 0.9.7a. OpenSSL 0.9.6 should also work.</p> + <p>OwnId: OTP-4002</p> + </item> + <item> + <p>When connecting it is now possible to bind to a local address + and local port. </p> + <p>OwnId: OTP-4675</p> + </item> + <item> + <p>The <c>ssl_esock</c> port program is now part of the + distribution and thus does not have to be created + explicitly. It is dynamically linked to OpenSSL + libraries in a "standard" location (typically + <c>/usr/local/lib</c> on UNIX; in the path on Win32).</p> + <p>OwnId: + OTP-4676</p> + </item> + <item> + <p>The new functions <c>ssl:peercert/1/2</c> provide information + from the certificate of a peer of a connection.</p> + <p>OwnId: OTP-4680 + <br></br> +Aux Id: seq7688</p> + </item> + <item> + <p>The function <c>ssl:port/1</c> has been removed from the + documentation, but not from the <c>ssl</c> interface module. + The recommendation is to use <c>ssl:peername/1</c> + instead, which provides both address and port of the peer.</p> + <p>OwnId: OTP-4681 </p> + </item> + <item> + <p>New User's Guide documentation has been added.</p> + <p>OwnId: OTP-4682 </p> + </item> + <item> + <p>The old <c>ssl_socket</c> interface has been removed and also + the documentation of it. </p> + <p>OwnId: OTP-4683 </p> + </item> + <item> + <p>The use of ephemeral RSA keys is now supported. It is + a global configuration option (see the ssl(6) manual page).</p> + <p>OwnId: OTP-4691.</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The option <c>cacertfile</c> is now in effect, and can + therefore no longer be set with the OS environment + variable SSL_CERT_FILE (which did set the same value for + all connections). </p> + <p>OwnId: OTP-3146</p> + </item> + <item> + <p>There was a synchronization error at closing of an SSL + connection. </p> + <p>OwnId: OTP-4435 + <br></br> +Aux Id: seq7534</p> + </item> + <item> + <p>C macros in <c>debuglog.c</c> were not ANSI C compliant.</p> + <p>OwnId: OTP-4674</p> + </item> + <item> + <p>The <c>binary</c> option was not properly handled.</p> + <p>OwnId: OTP-4678</p> + </item> + <item> + <p>The <c>ssl:format_error/1</c> did not consider <c>inet</c> + error codes, nor did it have a catch all for unknown error + codes.</p> + <p>OwnId: OTP-4679</p> + </item> + </list> + </section> + + <section> + <title>Known Bugs and Problems</title> + <list type="bulleted"> + <item> + <p>Change of controlling process in not OTP compliant. </p> + <p>OwnId; OTP-4712</p> + </item> + <item> + <p>There is still no way to restrict the cipher sizes. </p> + <p>OwnId: OTP-4712</p> + </item> + <item> + <p>The <c>keep_alive</c> and <c>reuse_addr</c> options will be + added in a future release. </p> + <p>OwnId: OTP-4677</p> + </item> + <item> + <p>There is currently no way to restrict the SSL/TLS + protocol versions to use. In a future release this will be + supported as a configuration option, and as an option for + each connection as well. </p> + <p>OwnId: OTP-4711.</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 2.3.6</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>There was a synchronization error at closing, which could + result in that an SSL socket was removed prematurely, resulting + in that a user process referring to it received an unexpected + exit.</p> + <p>OwnId: OTP-4435 + <br></br> +Aux Id: seq7600</p> + </item> + </list> + </section> + + <section> + <title>Known Bugs and Problems</title> + <p>See SSL 2.2 . </p> + </section> + </section> + + <section> + <title>SSL 2.3.5</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Setting of the option `nodelay' caused the SSL port program + to dump core.</p> + <p>OwnId: OTP-4380 + <br></br> +Aux Id: -</p> + </item> + <item> + <p>Setting of the option '{active, once}' in <c>setopts</c> was + wrong, causing a correct socket message to be regarded as + erroneous. </p> + <p>OwnId: OTP-4380 + <br></br> +Aux Id: -</p> + </item> + <item> + <p>A self-signed peer certificate was always rejected with the + error `eselfsignedcert', irrespective of the `depth' value. </p> + <p>OwnId: OTP-4374 + <br></br> +Aux Id: seq7417</p> + </item> + </list> + </section> + + <section> + <title>Known Bugs and Problems</title> + <p>See SSL 2.2 . </p> + </section> + </section> + + <section> + <title>SSL 2.3.4</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>All TCP options allowed in gen_tcp, are now also allowed in + SSL, except the option <c>{reuseaddr, Boolean}</c>. A new + function <c>getopts</c> has been added to the SSL interface + module <c>ssl</c>. </p> + <p>OwnId: OTP-4305, OTP-4159</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 2.3.3</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The roles of the SSLeay and OpenSSL packages has been + clarified in the ssl(6) application manual page. Also + the URLs from which to download SSLeay has been updated.</p> + <p>OwnId: OTP-4002 + <br></br> +Aux Id: seq5269</p> + </item> + <item> + <p>A call to <c>ssl:listen(Port, Options)</c> with + <c>Options = []</c> resulted in the cryptic <c>{error, ebadf}</c> return value. The return value has been changed + to <c>{error, enooptions}</c>, and the behaviour has been + documented in the <c>listen/2</c> function.</p> + <p>OwnId: OTP-4016 + <br></br> +Aux Id: seq7006</p> + </item> + <item> + <p>Use of the option <c>{nodelay, boolean()}</c> crashed + the <c>ssl_server</c>.</p> + <p>OwnId: OTP-4070 + <br></br> +Aux Id:</p> + </item> + <item> + <p>A bug caused the Erlang distribution over ssl to fail. + This bug has now been fixed.</p> + <p>OwnId: OTP-4072 + <br></br> +Aux Id:</p> + </item> + <item> + <p>On Windows when the SSL port program encountered an + error code not anticipated it crashed. </p> + <p>OwnId: OTP-4132 + <br></br> +Aux Id:</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 2.3.2</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The <c>ssl:accept/1-2</c> function sometimes returned + <c>{error, {What, Where}}</c> instead of <c>{error, What}</c>, where <c>What</c> is an atom. </p> + <p>OwnId: OTP-3775 + <br></br> +Aux Id: seq4991</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 2.3.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Sometimes the SSL portprogram would loop in an accept + loop, without terminating even when the SSL application + was stopped.. </p> + <p>OwnId: OTP-3691</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 2.3</title> + <p>Functions have been added to SSL to experimentally support + Erlang distribution. + </p> + </section> + + <section> + <title>SSL 2.2.1</title> + <p>The 2.2.1 version of SSL provides code replacement in runtime + by upgrading from, or downgrading to, versions 2.1 and 2.2. + </p> + </section> + + <section> + <title>SSL 2.2</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The restriction that only the creator of an SSL socket can + read from and write to the socket has been lifted.</p> + <p>OwnId: OTP-3301</p> + </item> + <item> + <p>The option <c>{packet, cdr}</c> for SSL sockets has been added, + which means that SSL sockets also supports CDR encoded packets.</p> + <p>OwnId: OTP-3302</p> + </item> + </list> + </section> + + <section> + <title>Known Bugs and Problems</title> + <list type="bulleted"> + <item> + <p>Setting of a CA certificate file with the <c>cacertfile</c> + option (in calls to <c>ssl:accept/1/2</c> or + <c>ssl:connect/3/4</c>) does not work due to weaknesses + in the SSLeay package. </p> + <p>A work-around is to set the OS environment variable + <c>SSL_CERT_FILE</c> before SSL is started. However, then + the CA certificate file will be global for all connections.</p> + <p>OwnId: OTP-3146</p> + </item> + <item> + <p>When changing controlling process of an SSL socket, a + temporary process is started, which is not gen_server + compliant.</p> + <p>OwnId: OTP-3146</p> + </item> + <item> + <p>Although there is a <c>cache</c> timeout option, it is + silently ignored.</p> + <p>OwnId: OTP-3146</p> + </item> + <item> + <p>There is currently no way to restrict the cipher sizes.</p> + <p>OwnId: OTP-3146</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 2.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The set of possible error reasons has been extended to + contain diagnostics on erroneous certificates and failures + to verify certificates.</p> + <p>OwnId: OTP-3145</p> + </item> + <item> + <p>The maximum number of simultaneous SSL connections on + Windows has been increased from 31 to 127.</p> + <p>OwnId: OTP-3145</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A dead-lock occurring when write queues are not empty has + been removed. </p> + <p>OwnId: OTP-3145</p> + </item> + <item> + <p>Error reasons have been unified and changed.</p> + <p>(** POTENTIAL INCOMPATIBILITY **)</p> + <p>OwnId: OTP-3145</p> + </item> + <item> + <p>On Windows a check of the existence of the environment + variable <c>ERLSRV_SERVICE_NAME</c> has been added. If + that variable is defined, the port program of the SSL + application will not terminated when a user logs off.</p> + <p>OwnId: OTP-3145</p> + </item> + <item> + <p>An error in the setting of the <c>nodelay</c> option + has been corrected.</p> + <p>OwnId: OTP-3145</p> + </item> + <item> + <p>The confounded notions of verify mode and verify depth has + been corrected. The option <c>verifydepth</c> has been + removed, and the two separate options <c>verify</c> and + <c>depth</c> has been added.</p> + <p>(** POTENTIAL INCOMPATIBILITY **)</p> + <p>OwnId: OTP-3145</p> + </item> + </list> + </section> + + <section> + <title>Known Bugs and Problems</title> + <list type="bulleted"> + <item> + <p>Setting of a CA certificate file with the <c>cacertfile</c> + option (in calls to <c>ssl:accept/1/2</c> or + <c>ssl:connect/3/4</c>) does not work due to weaknesses + in the SSLeay package. </p> + <p>A work-around is to set the OS environment variable + <c>SSL_CERT_FILE</c> before SSL is started. However, then + the CA certificate file will be global for all connections.</p> + <p>OwnId: OTP-3146</p> + </item> + <item> + <p>When changing controlling process of an SSL socket, a + temporary process is started, which is not gen_server + compliant.</p> + <p>OwnId: OTP-3146</p> + </item> + <item> + <p>Although there is a <c>cache</c> timeout option, it is + silently ignored.</p> + <p>OwnId: OTP-3146</p> + </item> + <item> + <p>There is currently no way to restrict the cipher sizes.</p> + <p>OwnId: OTP-3146</p> + </item> + </list> + </section> + </section> + + <section> + <title>SSL 2.0</title> + <p>A complete new version of SSL with separate I/O channels + for all connections with non-blocking I/O multiplexing.</p> + </section> +</chapter> + + diff --git a/lib/ssl/doc/src/pkix_certs.xml b/lib/ssl/doc/src/pkix_certs.xml new file mode 100644 index 0000000000..47818c1b7d --- /dev/null +++ b/lib/ssl/doc/src/pkix_certs.xml @@ -0,0 +1,253 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>PKIX Certificates</title> + <prepared>UAB/F/P Peter Högfeldt</prepared> + <docno></docno> + <date>2003-06-09</date> + <rev>A</rev> + <file>pkix_certs.xml</file> + </header> + + <section> + <title>Introduction to Certificates</title> + <p>Certificates were originally defined by ITU (CCITT) and the latest + definitions are described in <cite id="X.509"></cite>, but those definitions + are (as always) not working. + </p> + <p>Working certificate definitions for the Internet Community are found + in the the PKIX RFCs <cite id="rfc3279"></cite>and <cite id="rfc3280"></cite>. + The parsing of certificates in the Erlang/OTP SSL application is + based on those RFCS. + </p> + <p>Certificates are defined in terms of ASN.1 (<cite id="X.680"></cite>). + For an introduction to ASN.1 see <url href="http://asn1.elibel.tm.fr/">ASN.1 Information Site</url>. + </p> + </section> + + <section> + <title>PKIX Certificates</title> + <p>Here we base the PKIX certificate definitions in RFCs <cite id="rfc3279"></cite>and <cite id="rfc3280"></cite>. We however present the + definitions according to <c>SSL-PKIX.asn1</c> module, + which is an amelioration of the <c>PKIX1Explicit88.asn1</c>, + <c>PKIX1Implicit88.asn1</c>, and <c>PKIX1Algorithms88.asn1</c> + modules. You find all these modules in the <c>pkix</c> subdirectory + of SSL. + </p> + <p>The Erlang terms that are returned by the functions + <c>ssl:peercert/1/2</c>, <c>ssl_pkix:decode_cert/1/2</c>, and + <c>ssl_pkix:decode_cert_file/1/2</c> when the option <c>ssl</c> + is used in those functions, correspond the ASN.1 structures + described in the sequel. + </p> + + <section> + <title>Certificate and TBSCertificate</title> + <code type="none"> +Certificate ::= SEQUENCE { + tbsCertificate TBSCertificate, + signatureAlgorithm SignatureAlgorithm, + signature BIT STRING } + +TBSCertificate ::= SEQUENCE { + version [0] Version DEFAULT v1, + serialNumber CertificateSerialNumber, + signature SignatureAlgorithm, + issuer Name, + validity Validity, + subject Name, + subjectPublicKeyInfo SubjectPublicKeyInfo, + issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL, + -- If present, version MUST be v2 or v3 + subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL, + -- If present, version MUST be v2 or v3 + extensions [3] Extensions OPTIONAL + -- If present, version MUST be v3 -- } + +Version ::= INTEGER { v1(0), v2(1), v3(2) } + +CertificateSerialNumber ::= INTEGER + +Validity ::= SEQUENCE { + notBefore Time, + notAfter Time } + +Time ::= CHOICE { + utcTime UTCTime, + generalTime GeneralizedTime } + </code> + <p>The meaning of the fields <c>version</c>, <c>serialNumber</c>, + and <c>validity</c> are quite obvious given the type definitions + above, so we do not go further into their details. + </p> + <p>The <c>signatureAlgorithm</c> field of <c>Certificate</c> and + the <c>signature</c> field of <c>TBSCertificate</c> contain + the name and parameters of the algorithm used for signing the + certificate. The values of these two fields must be equal. + </p> + <p>The <c>signature</c> field of <c>Certificate</c> contains the + value of the signature that the issuer computed by using the + prescribed algorithm. + </p> + <p>The <c><![CDATA[issuer<c> and <c>subject]]></c> fields can contain many + different types av data, and is therefore considered in a + separate section. The same holds for the <c>extensions</c> + field. + The <c>issuerUniqueID</c> and the <c>subjectUniqueID</c> fields + are not considered further.</p> + </section> + + <section> + <title>TBSCertificate issuer and subject</title> + <p></p> + <code type="none"><![CDATA[ +Name ::= CHOICE { -- only one possibility for now -- + rdnSequence RDNSequence } + +RDNSequence ::= SEQUENCE OF RelativeDistinguishedName + +DistinguishedName ::= RDNSequence + +RelativeDistinguishedName ::= + SET SIZE (1 .. MAX) OF AttributeTypeAndValue + +AttributeTypeAndValue ::= SEQUENCE { + type ATTRIBUTE-TYPE-AND-VALUE-CLASS.&id +\011\011({SupportedAttributeTypeAndValues}), + value ATTRIBUTE-TYPE-AND-VALUE-CLASS.&Type +\011\011({SupportedAttributeTypeAndValues}{@type}) } + +SupportedAttributeTypeAndValues ATTRIBUTE-TYPE-AND-VALUE-CLASS ::= +\011{ name | surname | givenName | initials | generationQualifier | +\011 commonName | localityName | stateOrProvinceName | organizationName | +\011 organizationalUnitName | title | dnQualifier | countryName | +\011 serialNumber | pseudonym | domainComponent | emailAddress } ]]></code> + </section> + + <section> + <title>TBSCertificate extensions</title> + <p>The <c>extensions</c> field of a <c>TBScertificate</c> is a + sequence of type <c>Extension</c>, defined as follows,</p> + <code type="none"> +Extension ::= SEQUENCE { + extnID OBJECT IDENTIFIER, + critical BOOLEAN DEFAULT FALSE, + extnValue ANY } </code> + <p>Each extension has a unique object identifier. An extension + with a <c>critical</c> value set to <c>TRUE</c><em>must</em> + be recognised by the reader of a certificate, or else the + certificate must be rejected. + </p> + <p>Extensions are divided into two groups: standard extensions + and internet certificate extensions. All extensions listed in + the table that follows are standard extensions, except for + <c>authorityInfoAccess</c> and <c>subjectInfoAccess</c>, which + are internet extensions. + </p> + <p>Depending on the object identifier the <c>extnValue</c> is + parsed into an appropriate welldefined structure. + </p> + <p>The following table shows the purpose of each extension, but + does not specify the structure. To see the structure consult + the <c>PKIX1Implicit88.asn1</c> module. + </p> + <table> + <row> + <cell align="left" valign="middle">authorityKeyIdentifier</cell> + <cell align="left" valign="middle">Used by to identify a certificate signed that has multiple signing keys. </cell> + </row> + <row> + <cell align="left" valign="middle">subjectKeyIdentifier</cell> + <cell align="left" valign="middle">Used to identify certificates that contain a public key. Must appear i CA certificates.</cell> + </row> + <row> + <cell align="left" valign="middle">keyUsage </cell> + <cell align="left" valign="middle">Defines the purpose of the certificate. Can be one or several of<c>digitalSignature</c>, <c>nonRepudiation</c>,<c>keyEncipherment</c>, <c>dataEncipherment</c>,<c>keyAgreement</c>, <c>keyCertSign</c>, <c>cRLSign</c>,<c>encipherOnly</c>, <c>decipherOnly</c>.</cell> + </row> + <row> + <cell align="left" valign="middle">privateKeyUsagePeriod </cell> + <cell align="left" valign="middle">Allows certificate issuer to provide a private key usage period to be short than the certificate usage period.</cell> + </row> + <row> + <cell align="left" valign="middle">certificatePolicies</cell> + <cell align="left" valign="middle">Contains one or more policy information terms indicating the policies under which the certificate has been issued.</cell> + </row> + <row> + <cell align="left" valign="middle">policyMappings</cell> + <cell align="left" valign="middle">Used i CA certificates. </cell> + </row> + <row> + <cell align="left" valign="middle">subjectAltName</cell> + <cell align="left" valign="middle">Allows additional identities to be bound the the subject. </cell> + </row> + <row> + <cell align="left" valign="middle">issuerAltName</cell> + <cell align="left" valign="middle">Allows additional identities to be bound the the issuer.</cell> + </row> + <row> + <cell align="left" valign="middle">subjectDirectoryAttributes</cell> + <cell align="left" valign="middle">Conveys identity attributes of the subject.</cell> + </row> + <row> + <cell align="left" valign="middle">basicConstraints</cell> + <cell align="left" valign="middle">Tells if the certificate holder is a CA or not.</cell> + </row> + <row> + <cell align="left" valign="middle">nameConstraints</cell> + <cell align="left" valign="middle">Used in CA certificates.</cell> + </row> + <row> + <cell align="left" valign="middle">policyConstraints</cell> + <cell align="left" valign="middle">Used in CA certificates.</cell> + </row> + <row> + <cell align="left" valign="middle">extKeyUsage</cell> + <cell align="left" valign="middle">Indicates for which purposed the public key may be used. </cell> + </row> + <row> + <cell align="left" valign="middle">cRLDistributionPoints</cell> + <cell align="left" valign="middle">Indicates how CRL (Certificate Revokation List) information is obtained.</cell> + </row> + <row> + <cell align="left" valign="middle">inhibitAnyPolicy</cell> + <cell align="left" valign="middle">Used i CA certificates.</cell> + </row> + <row> + <cell align="left" valign="middle">freshestCRL</cell> + <cell align="left" valign="middle">For CRLs.</cell> + </row> + <row> + <cell align="left" valign="middle">authorityInfoAccess</cell> + <cell align="left" valign="middle">How to access CA information of the issuer of the certificate.</cell> + </row> + <row> + <cell align="left" valign="middle">subjectInfoAccess</cell> + <cell align="left" valign="middle">How to access CA information of the subject of the certificate.</cell> + </row> + <tcaption>PKIX Extensions</tcaption> + </table> + </section> + </section> +</chapter> + + diff --git a/lib/ssl/doc/src/refman.xml b/lib/ssl/doc/src/refman.xml new file mode 100644 index 0000000000..3ad5a01b46 --- /dev/null +++ b/lib/ssl/doc/src/refman.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>SSL Reference Manual</title> + <prepared>Peter Högfeldt</prepared> + <docno></docno> + <date>2003-03-25</date> + <rev>B</rev> + <file>refman.sgml</file> + </header> + <description> + <p>The <em>SSL</em> application provides secure communication over + sockets. + </p> + <p>This product includes software developed by the OpenSSL Project for + use in the OpenSSL Toolkit (http://www.openssl.org/). + </p> + <p>This product includes cryptographic software written by Eric Young + ([email protected]). + </p> + <p>This product includes software written by Tim Hudson + ([email protected]). + </p> + <p>For full OpenSSL and SSLeay license texts, see <seealso marker="licenses#licenses">Licenses</seealso>.</p> + </description> + <xi:include href="ssl_app.xml"/> + <xi:include href="ssl.xml"/> + <xi:include href="new_ssl.xml"/> +</application> + + diff --git a/lib/ssl/doc/src/release_notes.xml b/lib/ssl/doc/src/release_notes.xml new file mode 100644 index 0000000000..e7c766bb91 --- /dev/null +++ b/lib/ssl/doc/src/release_notes.xml @@ -0,0 +1,49 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>SSL Release Notes</title> + <prepared>Peter Högfeldt</prepared> + <docno></docno> + <date>2003-05-26</date> + <rev>A</rev> + <file>release_notes.sgml</file> + </header> + <description> + <p>The SSL application provides secure communication over sockets. + </p> + <p>This product includes software developed by the OpenSSL Project for + use in the OpenSSL Toolkit (http://www.openssl.org/). + </p> + <p>This product includes cryptographic software written by Eric Young + ([email protected]). + </p> + <p>This product includes software written by Tim Hudson + ([email protected]). + </p> + <p>For full OpenSSL and SSLeay license texts, see <seealso marker="licenses#licenses">Licenses</seealso>. + </p> + </description> + <xi:include href="notes.xml"/> +</part> + + diff --git a/lib/ssl/doc/src/remember.xml b/lib/ssl/doc/src/remember.xml new file mode 100644 index 0000000000..799627a33c --- /dev/null +++ b/lib/ssl/doc/src/remember.xml @@ -0,0 +1,83 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>PKIX Certificates</title> + <prepared>UAB/F/P Peter Högfeldt</prepared> + <docno></docno> + <date>2003-06-09</date> + <rev>A</rev> + <file>pkix_certs.sgml</file> + </header> + + <section> + <title>Introduction to Certificates</title> + <p><em>Outline:</em></p> + <list type="bulleted"> + <item>SSL/TLS protocol - server must have certificate - -what + the the server sends to the client - client may verify the + server - server may ask client for certificate - what the + client sends to the server - server may then verify the client + - verification - certificate chains - root certificates - + public keys - key agreement - purpose of certificate - main + contents of certificate - contents have increased as time went + by - common file formats for certificates. + </item> + <item>private keys - password protection - key generation - file + formats. + </item> + <item>ssl_pkix and alternate decodings. + </item> + <item>Attribute Certificates (not used by SSL). + </item> + <item>Certificate requests - certificate authorities - signing of + certificates - certificate revocation lists. + </item> + <item>standards: ASN.1, X.509, X.520, PKIX, PKCS, PEM. + </item> + <item>incompatibilities between standards (X.509-1997 vs old) - the + ASN.1 problem of ANY, BIT STRING and OCTET STRING - the module + ssl_pkix. + </item> + <item>test suites: NIST + </item> + <item>Warnings: *creation* of trusted certificate (OpenSSL). + </item> + <item>Erlang SSL and certificates + </item> + <item>The need for seeding the random generator. See also John + S. Denker: High-Entropy Symbol Generator + (http://www.monmouth.com/~jsd). + </item> + <item>links to standards and documents. Books (Rescorla). + </item> + <item>ASN.1 crash course. + </item> + <item>Nagel algorithm. + </item> + </list> + <p>For an introduction to ASN.1 see <url href="http://asn1.elibel.tm.fr/">ASN.1 Information Site</url>. + </p> + </section> +</chapter> + + diff --git a/lib/ssl/doc/src/ssl.fig b/lib/ssl/doc/src/ssl.fig new file mode 100644 index 0000000000..a338720fd1 --- /dev/null +++ b/lib/ssl/doc/src/ssl.fig @@ -0,0 +1,10 @@ +#FIG 3.1 +Portrait +Center +Inches +1200 2 +2 2 0 1 6 6 0 0 20 0.000 0 0 -1 0 0 5 + 1350 525 4425 525 4425 2250 1350 2250 1350 525 +4 0 4 0 0 18 48 0.0000 4 555 495 2025 1575 S\001 +4 0 4 0 0 18 48 0.0000 4 555 495 2475 1725 S\001 +4 0 4 0 0 18 48 0.0000 4 555 435 3000 1620 L\001 diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml new file mode 100644 index 0000000000..9b780b14ce --- /dev/null +++ b/lib/ssl/doc/src/ssl.xml @@ -0,0 +1,728 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>ssl</title> + <prepared>Peter Högfeldt</prepared> + <responsible>Peter Högfeldt</responsible> + <docno></docno> + <approved>Peter Högfeldt</approved> + <checked></checked> + <date>2003-03-25</date> + <rev>D</rev> + <file>ssl.sgml</file> + </header> + <module>ssl</module> + <modulesummary>Interface Functions for Secure Socket Layer</modulesummary> + <description> + <p>This module contains interface functions to the Secure Socket Layer.</p> + </description> + + <section> + <title>General</title> + + <p>There is a new implementation of ssl available in + this module but until it is 100 % complete, so that it can replace + the old implementation in all aspects it will be + described here <seealso marker="new_ssl"> new ssl API </seealso></p> + + <p>The reader is advised to also read the <c>ssl(6)</c> manual page + describing the SSL application. + </p> + <warning> + <p>It is strongly advised to seed the random generator after + the ssl application has been started (see <c>seed/1</c> + below), and before any connections are established. Although + the port program interfacing to the ssl libraries does a + "random" seeding of its own in order to make everything work + properly, that seeding is by no means random for the world + since it has a constant value which is known to everyone + reading the source code of the port program.</p> + </warning> + </section> + + <section> + <title>Common data types</title> + <p>The following datatypes are used in the functions below: + </p> + <list type="bulleted"> + <item> + <p><c>options() = [option()]</c></p> + </item> + <item> + <p><c>option() = socketoption() | ssloption()</c></p> + </item> + <item> + <p><c>socketoption() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {nodelay, boolean()} | {active, activetype()} | {backlog, integer()} | {ip, ipaddress()} | {port, integer()}</c></p> + </item> + <item> + <p><c>ssloption() = {verify, code()} | {depth, depth()} | {certfile, path()} | {keyfile, path()} | {password, string()} | {cacertfile, path()} | {ciphers, string()}</c></p> + </item> + <item> + <p><c>packettype()</c> (see inet(3))</p> + </item> + <item> + <p><c>activetype()</c> (see inet(3))</p> + </item> + <item> + <p><c>reason() = atom() | {atom(), string()}</c></p> + </item> + <item> + <p><c>bytes() = [byte()]</c></p> + </item> + <item> + <p><c>string() = [byte()]</c></p> + </item> + <item> + <p><c>byte() = 0 | 1 | 2 | ... | 255</c></p> + </item> + <item> + <p><c>code() = 0 | 1 | 2</c></p> + </item> + <item> + <p><c>depth() = byte()</c></p> + </item> + <item> + <p><c>address() = hostname() | ipstring() | ipaddress()</c></p> + </item> + <item> + <p><c>ipaddress() = ipstring() | iptuple()</c></p> + </item> + <item> + <p><c>hostname() = string()</c></p> + </item> + <item> + <p><c>ipstring() = string()</c></p> + </item> + <item> + <p><c>iptuple() = {byte(), byte(), byte(), byte()}</c></p> + </item> + <item> + <p><c>sslsocket()</c></p> + </item> + <item> + <p><c>protocol() = sslv2 | sslv3 | tlsv1</c></p> + </item> + <item> + <p><c></c></p> + </item> + </list> + <p>The socket option <c>{backlog, integer()}</c> is for + <c>listen/2</c> only, and the option <c>{port, integer()}</c> + is for <c>connect/3/4</c> only. + </p> + <p>The following socket options are set by default: <c>{mode, list}</c>, <c>{packet, 0}</c>, <c>{header, 0}</c>, <c>{nodelay, false}</c>, <c>{active, true}</c>, <c>{backlog, 5}</c>, + <c>{ip, {0,0,0,0}}</c>, and <c>{port, 0}</c>. + </p> + <p>Note that the options <c>{mode, binary}</c> and <c>binary</c> + are equivalent. Similarly <c>{mode, list}</c> and the absence of + option <c>binary</c> are equivalent. + </p> + <p>The ssl options are for setting specific SSL parameters as follows: + </p> + <list type="bulleted"> + <item> + <p><c>{verify, code()}</c> Specifies type of verification: + 0 = do not verify peer; 1 = verify peer, 2 = verify peer, + fail if no peer certificate. The default value is 0. + </p> + </item> + <item> + <p><c>{depth, depth()}</c> Specifies the maximum + verification depth, i.e. how far in a chain of certificates + the verification process can proceed before the verification + is considered to fail. + </p> + <p>Peer certificate = 0, CA certificate = 1, higher level CA + certificate = 2, etc. The value 2 thus means that a chain + can at most contain peer cert, CA cert, next CA cert, and an + additional CA cert. + </p> + <p>The default value is 1. + </p> + </item> + <item> + <p><c>{certfile, path()}</c> Path to a file containing the + user's certificate. + chain of PEM encoded certificates.</p> + </item> + <item> + <p><c>{keyfile, path()}</c> Path to file containing user's + private PEM encoded key.</p> + </item> + <item> + <p><c>{password, string()}</c> String containing the user's + password. Only used if the private keyfile is password protected.</p> + </item> + <item> + <p><c>{cacertfile, path()}</c> Path to file containing PEM encoded + CA certificates (trusted certificates used for verifying a peer + certificate).</p> + </item> + <item> + <p><c>{ciphers, string()}</c> String of ciphers as a colon + separated list of ciphers. The function <c>ciphers/0</c> can + be used to find all available ciphers.</p> + </item> + </list> + <p>The type <c>sslsocket()</c> is opaque to the user. + </p> + <p>The owner of a socket is the one that created it by a call to + <c>transport_accept/[1,2]</c>, <c>connect/[3,4]</c>, + or <c>listen/2</c>. + </p> + <p>When a socket is in active mode (the default), data from the + socket is delivered to the owner of the socket in the form of + messages: + </p> + <list type="bulleted"> + <item> + <p><c>{ssl, Socket, Data}</c></p> + </item> + <item> + <p><c>{ssl_closed, Socket}</c></p> + </item> + <item> + <p><c>{ssl_error, Socket, Reason}</c></p> + </item> + </list> + <p>A <c>Timeout</c> argument specifies a timeout in milliseconds. The + default value for a <c>Timeout</c> argument is <c>infinity</c>. + </p> + <p>Functions listed below may return the value <c>{error, closed}</c>, which only indicates that the SSL socket is + considered closed for the operation in question. It is for + instance possible to have <c>{error, closed}</c> returned from + an call to <c>send/2</c>, and a subsequent call to <c>recv/3</c> + returning <c>{ok, Data}</c>. + </p> + <p>Hence a return value of <c>{error, closed}</c> must not be + interpreted as if the socket was completely closed. On the + contrary, in order to free all resources occupied by an SSL + socket, <c>close/1</c> must be called, or else the process owning + the socket has to terminate. + </p> + <p>For each SSL socket there is an Erlang process representing the + socket. When a socket is opened, that process links to the + calling client process. Implementations that want to detect + abnormal exits from the socket process by receiving <c>{'EXIT', Pid, Reason}</c> messages, should use the function <c>pid/1</c> + to retrieve the process identifier from the socket, in order to + be able to match exit messages properly.</p> + </section> + <funcs> + <func> + <name>ciphers() -> {ok, string()} | {error, enotstarted}</name> + <fsummary>Get supported ciphers.</fsummary> + <desc> + <p>Returns a string consisting of colon separated cipher + designations that are supported by the current SSL library + implementation. + </p> + <p>The SSL application has to be started to return the string + of ciphers.</p> + </desc> + </func> + <func> + <name>close(Socket) -> ok | {error, Reason}</name> + <fsummary>Close a socket returned by <c>transport_accept/[1,2]</c>, <c>connect/3/4</c>, or <c>listen/2</c>.</fsummary> + <type> + <v>Socket = sslsocket()</v> + </type> + <desc> + <p>Closes a socket returned by <c>transport_accept/[1,2]</c>, + <c>connect/[3,4]</c>, or <c>listen/2</c></p> + </desc> + </func> + <func> + <name>connect(Address, Port, Options) -> {ok, Socket} | {error, Reason}</name> + <name>connect(Address, Port, Options, Timeout) -> {ok, Socket} | {error, Reason}</name> + <fsummary>Connect to <c>Port</c>at <c>Address</c>.</fsummary> + <type> + <v>Address = address()</v> + <v>Port = integer()</v> + <v>Options = [connect_option()]</v> + <v>connect_option() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {nodelay, boolean()} | {active, activetype()} | {ip, ipaddress()} | {port, integer()} | {verify, code()} | {depth, depth()} | {certfile, path()} | {keyfile, path()} | {password, string()} | {cacertfile, path()} | {ciphers, string()}</v> + <v>Timeout = integer()</v> + <v>Socket = sslsocket()</v> + </type> + <desc> + <p>Connects to <c>Port</c> at <c>Address</c>. If the optional + <c>Timeout</c> argument is specified, and a connection could not + be established within the given time, <c>{error, timeout}</c> is + returned. The default value for <c>Timeout</c> is <c>infinity</c>. + </p> + <p>The <c>ip</c> and <c>port</c> options are for binding to a + particular <em>local</em> address and port, respectively.</p> + </desc> + </func> + <func> + <name>connection_info(Socket) -> {ok, {Protocol, Cipher}} | {error, Reason}</name> + <fsummary>Get current protocol version and cipher.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Protocol = protocol()</v> + <v>Cipher = string()</v> + </type> + <desc> + <p>Gets the chosen protocol version and cipher for an established + connection (accepted och connected). </p> + </desc> + </func> + <func> + <name>controlling_process(Socket, NewOwner) -> ok | {error, Reason}</name> + <fsummary>Assign a new controlling process to the socket.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>NewOwner = pid()</v> + </type> + <desc> + <p>Assigns a new controlling process to <c>Socket</c>. A controlling + process is the owner of a socket, and receives all messages from + the socket.</p> + </desc> + </func> + <func> + <name>format_error(ErrorCode) -> string()</name> + <fsummary>Return an error string.</fsummary> + <type> + <v>ErrorCode = term()</v> + </type> + <desc> + <p>Returns a diagnostic string describing an error.</p> + </desc> + </func> + <func> + <name>getopts(Socket, OptionsTags) -> {ok, Options} | {error, Reason}</name> + <fsummary>Get options set for socket</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>OptionTags = [optiontag()]()</v> + </type> + <desc> + <p>Returns the options the tags of which are <c>OptionTags</c> for + for the socket <c>Socket</c>. </p> + </desc> + </func> + <func> + <name>listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}</name> + <fsummary>Set up a socket to listen on a port on the local host.</fsummary> + <type> + <v>Port = integer()</v> + <v>Options = [listen_option()]</v> + <v>listen_option() = {mode, list} | {mode, binary} | binary | {packet, packettype()} | {header, integer()} | {active, activetype()} | {backlog, integer()} | {ip, ipaddress()} | {verify, code()} | {depth, depth()} | {certfile, path()} | {keyfile, path()} | {password, string()} | {cacertfile, path()} | {ciphers, string()}</v> + <v>ListenSocket = sslsocket()</v> + </type> + <desc> + <p>Sets up a socket to listen on port <c>Port</c> at the local host. + If <c>Port</c> is zero, <c>listen/2</c> picks an available port + number (use <c>port/1</c> to retrieve it). + </p> + <p>The listen queue size defaults to 5. If a different value is + wanted, the option <c>{backlog, Size}</c> should be added to the + list of options. + </p> + <p>An empty <c>Options</c> list is considered an error, and + <c>{error, enooptions}</c> is returned. + </p> + <p>The returned <c>ListenSocket</c> can only be used in calls to + <c>transport_accept/[1,2]</c>.</p> + </desc> + </func> + <func> + <name>peercert(Socket) -> </name> + <name>peercert(Socket, Opts) -> {ok, Cert} | {ok, Subject} | {error, Reason}</name> + <fsummary>Return the peer certificate.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Opts = [pkix | ssl | subject]()</v> + <v>Cert = term()()</v> + <v>Subject = term()()</v> + </type> + <desc> + <p><c>peercert(Cert)</c> is equivalent to <c>peercert(Cert, [])</c>. + </p> + <p>The form of the returned certificate depends on the + options. + </p> + <p>If the options list is empty the certificate is returned as + a DER encoded binary. + </p> + <p>The options <c>pkix</c> and <c>ssl</c> implies that the + certificate is returned as a parsed ASN.1 structure in the + form of an Erlang term. + </p> + <p>The <c>ssl</c> option gives a more elaborate return + structure, with more explicit information. In particular + object identifiers are replaced by atoms. + </p> + <p>The options <c>pkix</c>, and <c>ssl</c> are mutually + exclusive. + </p> + <p>The option <c>subject</c> implies that only the subject's + distinguished name part of the peer certificate is returned. + It can only be used together with the option <c>pkix</c> or + the option <c>ssl</c>.</p> + </desc> + </func> + <func> + <name>peername(Socket) -> {ok, {Address, Port}} | {error, Reason}</name> + <fsummary>Return peer address and port.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Address = ipaddress()</v> + <v>Port = integer()</v> + </type> + <desc> + <p>Returns the address and port number of the peer.</p> + </desc> + </func> + <func> + <name>pid(Socket) -> pid()</name> + <fsummary>Return the pid of the socket process.</fsummary> + <type> + <v>Socket = sslsocket()</v> + </type> + <desc> + <p>Returns the pid of the socket process. The returned pid should + only be used for receiving exit messages.</p> + </desc> + </func> + <func> + <name>recv(Socket, Length) -> {ok, Data} | {error, Reason}</name> + <name>recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}</name> + <fsummary>Receive data on socket.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Length = integer() >= 0</v> + <v>Timeout = integer()</v> + <v>Data = bytes() | binary()</v> + </type> + <desc> + <p>Receives data on socket <c>Socket</c> when the socket is in + passive mode, i.e. when the option <c>{active, false}</c> + has been specified. + </p> + <p>A notable return value is <c>{error, closed}</c> which + indicates that the socket is closed. + </p> + <p>A positive value of the <c>Length</c> argument is only + valid when the socket is in raw mode (option <c>{packet, 0}</c> is set, and the option <c>binary</c> is <em>not</em> + set); otherwise it should be set to 0, whence all available + bytes are returned. + </p> + <p>If the optional <c>Timeout</c> parameter is specified, and + no data was available within the given time, <c>{error, timeout}</c> is returned. The default value for + <c>Timeout</c> is <c>infinity</c>.</p> + </desc> + </func> + <func> + <name>seed(Data) -> ok | {error, Reason}</name> + <fsummary>Seed the ssl random generator.</fsummary> + <type> + <v>Data = iolist() | binary()</v> + </type> + <desc> + <p>Seeds the ssl random generator. + </p> + <p>It is strongly advised to seed the random generator after + the ssl application has been started, and before any + connections are established. Although the port program + interfacing to the OpenSSL libraries does a "random" seeding + of its own in order to make everything work properly, that + seeding is by no means random for the world since it has a + constant value which is known to everyone reading the source + code of the seeding. + </p> + <p>A notable return value is <c>{error, edata}}</c> indicating that + <c>Data</c> was not a binary nor an iolist.</p> + </desc> + </func> + <func> + <name>send(Socket, Data) -> ok | {error, Reason}</name> + <fsummary>Write data to a socket.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Data = iolist() | binary()</v> + </type> + <desc> + <p>Writes <c>Data</c> to <c>Socket</c>. </p> + <p>A notable return value is <c>{error, closed}</c> indicating that + the socket is closed.</p> + </desc> + </func> + <func> + <name>setopts(Socket, Options) -> ok | {error, Reason}</name> + <fsummary>Set socket options.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Options = [socketoption]()</v> + </type> + <desc> + <p>Sets options according to <c>Options</c> for the socket + <c>Socket</c>. </p> + </desc> + </func> + <func> + <name>ssl_accept(Socket) -> ok | {error, Reason}</name> + <name>ssl_accept(Socket, Timeout) -> ok | {error, Reason}</name> + <fsummary>Perform server-side SSL handshake and key exchange</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Timeout = integer()</v> + <v>Reason = atom()</v> + </type> + <desc> + <p>The <c>ssl_accept</c> function establish the SSL connection + on the server side. It should be called directly after + <c>transport_accept</c>, in the spawned server-loop.</p> + <p>Note that the ssl connection is not complete until <c>ssl_accept</c> + has returned <c>true</c>, and if an error is returned, the socket + is unavailable and for instance <c>close/1</c> will crash.</p> + </desc> + </func> + <func> + <name>sockname(Socket) -> {ok, {Address, Port}} | {error, Reason}</name> + <fsummary>Return the local address and port.</fsummary> + <type> + <v>Socket = sslsocket()</v> + <v>Address = ipaddress()</v> + <v>Port = integer()</v> + </type> + <desc> + <p>Returns the local address and port number of the socket + <c>Socket</c>.</p> + </desc> + </func> + <func> + <name>transport_accept(Socket) -> {ok, NewSocket} | {error, Reason}</name> + <name>transport_accept(Socket, Timeout) -> {ok, NewSocket} | {error, Reason}</name> + <fsummary>Accept an incoming connection and prepare for <c>ssl_accept</c></fsummary> + <type> + <v>Socket = NewSocket = sslsocket()</v> + <v>Timeout = integer()</v> + <v>Reason = atom()</v> + </type> + <desc> + <p>Accepts an incoming connection request on a listen socket. + <c>ListenSocket</c> must be a socket returned from <c>listen/2</c>. + The socket returned should be passed to <c>ssl_accept</c> to + complete ssl handshaking and establishing the connection.</p> + <warning> + <p>The socket returned can only be used with <c>ssl_accept</c>, + no traffic can be sent or received before that call.</p> + </warning> + <p>The accepted socket inherits the options set for <c>ListenSocket</c> + in <c>listen/2</c>.</p> + <p>The default value for <c>Timeout</c> is <c>infinity</c>. If + <c>Timeout</c> is specified, and no connection is accepted within + the given time, <c>{error, timeout}</c> is returned.</p> + </desc> + </func> + <func> + <name>version() -> {ok, {SSLVsn, CompVsn, LibVsn}}</name> + <fsummary>Return the version of SSL.</fsummary> + <type> + <v>SSLVsn = CompVsn = LibVsn = string()()</v> + </type> + <desc> + <p>Returns the SSL application version (<c>SSLVsn</c>), the library + version used when compiling the SSL application port program + (<c>CompVsn</c>), and the actual library version used when + dynamically linking in runtime (<c>LibVsn</c>). + </p> + <p>If the SSL application has not been started, <c>CompVsn</c> and + <c>LibVsn</c> are empty strings. + </p> + </desc> + </func> + </funcs> + + <section> + <title>ERRORS</title> + <p>The possible error reasons and the corresponding diagnostic strings + returned by <c>format_error/1</c> are either the same as those defined + in the <c>inet(3)</c> reference manual, or as follows: + </p> + <taglist> + <tag><c>closed</c></tag> + <item> + <p>Connection closed for the operation in question. + </p> + </item> + <tag><c>ebadsocket</c></tag> + <item> + <p>Connection not found (internal error). + </p> + </item> + <tag><c>ebadstate</c></tag> + <item> + <p>Connection not in connect state (internal error). + </p> + </item> + <tag><c>ebrokertype</c></tag> + <item> + <p>Wrong broker type (internal error). + </p> + </item> + <tag><c>ecacertfile</c></tag> + <item> + <p>Own CA certificate file is invalid. + </p> + </item> + <tag><c>ecertfile</c></tag> + <item> + <p>Own certificate file is invalid. + </p> + </item> + <tag><c>echaintoolong</c></tag> + <item> + <p>The chain of certificates provided by peer is too long. + </p> + </item> + <tag><c>ecipher</c></tag> + <item> + <p>Own list of specified ciphers is invalid. + </p> + </item> + <tag><c>ekeyfile</c></tag> + <item> + <p>Own private key file is invalid. + </p> + </item> + <tag><c>ekeymismatch</c></tag> + <item> + <p>Own private key does not match own certificate. + </p> + </item> + <tag><c>enoissuercert</c></tag> + <item> + <p>Cannot find certificate of issuer of certificate provided + by peer. + </p> + </item> + <tag><c>enoservercert</c></tag> + <item> + <p>Attempt to do accept without having set own certificate. + </p> + </item> + <tag><c>enotlistener</c></tag> + <item> + <p>Attempt to accept on a non-listening socket. + </p> + </item> + <tag><c>enoproxysocket</c></tag> + <item> + <p>No proxy socket found (internal error). + </p> + </item> + <tag><c>enooptions</c></tag> + <item> + <p>The list of options is empty. + </p> + </item> + <tag><c>enotstarted</c></tag> + <item> + <p>The SSL application has not been started. + </p> + </item> + <tag><c>eoptions</c></tag> + <item> + <p>Invalid list of options. + </p> + </item> + <tag><c>epeercert</c></tag> + <item> + <p>Certificate provided by peer is in error. + </p> + </item> + <tag><c>epeercertexpired</c></tag> + <item> + <p>Certificate provided by peer has expired. + </p> + </item> + <tag><c>epeercertinvalid</c></tag> + <item> + <p>Certificate provided by peer is invalid. + </p> + </item> + <tag><c>eselfsignedcert</c></tag> + <item> + <p>Certificate provided by peer is self signed. + </p> + </item> + <tag><c>esslaccept</c></tag> + <item> + <p>Server SSL handshake procedure between client and server failed. + </p> + </item> + <tag><c>esslconnect</c></tag> + <item> + <p>Client SSL handshake procedure between client and server failed. + </p> + </item> + <tag><c>esslerrssl</c></tag> + <item> + <p>SSL protocol failure. Typically because of a fatal alert + from peer. + </p> + </item> + <tag><c>ewantconnect</c></tag> + <item> + <p>Protocol wants to connect, which is not supported in + this version of the SSL application. + </p> + </item> + <tag><c>ex509lookup</c></tag> + <item> + <p>Protocol wants X.509 lookup, which is not supported in + this version of the SSL application. + </p> + </item> + <tag><c>{badcall, Call}</c></tag> + <item> + <p>Call not recognized for current mode (active or passive) and + state of socket. + </p> + </item> + <tag><c>{badcast, Cast}</c></tag> + <item> + <p>Call not recognized for current mode (active or passive) and + state of socket. + </p> + </item> + <tag><c>{badinfo, Info}</c></tag> + <item> + <p>Call not recognized for current mode (active or passive) and + state of socket. + </p> + </item> + </taglist> + </section> + + <section> + <title>SEE ALSO</title> + <p>gen_tcp(3), inet(3) + </p> + </section> + +</erlref> + + diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml new file mode 100644 index 0000000000..ae8bd87781 --- /dev/null +++ b/lib/ssl/doc/src/ssl_app.xml @@ -0,0 +1,182 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE appref SYSTEM "appref.dtd"> + +<appref> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>ssl</title> + <prepared>Peter Högfeldt</prepared> + <responsible>Peter Högfeldt</responsible> + <docno></docno> + <approved>Peter Högfeldt</approved> + <checked>Peter Högfeldt</checked> + <date>2005-03-10</date> + <rev>E</rev> + <file>ssl_app.sgml</file> + </header> + <app>ssl</app> + <appsummary>The SSL Application</appsummary> + <description> + <p>The Secure Socket Layer (SSL) application provides secure + socket communication over TCP/IP. + </p> + </description> + + <section> + <title>Warning</title> + <p>In previous versions of Erlang/OTP SSL it was advised, as a + work-around, to set the operating system environment variable + <c>SSL_CERT_FILE</c> to point at a file containing CA + certificates. That variable is no longer needed, and is not + recognised by Erlang/OTP SSL any more. + </p> + <p>However, the OpenSSL package does interpret that environment + variable. Hence a setting of that variable might have + unpredictable effects on the Erlang/OTP SSL application. It is + therefore adviced to not used that environment variable at all.</p> + </section> + + <section> + <title>Environment</title> + <p>The following application environment configuration parameters + are defined for the SSL application. Refer to application(3) for + more information about configuration parameters. + </p> + <p>Note that the environment parameters can be set on the command line, + for instance,</p> + <p><c>erl ... -ssl protocol_version '[sslv2,sslv3]' ...</c>. + </p> + <taglist> + <tag><c><![CDATA[ephemeral_rsa = true | false <optional>]]></c></tag> + <item> + <p>Enables all SSL servers (those that listen and accept) + to use ephemeral RSA key generation when a clients connect with + weak handshake cipher specifications, that need equally weak + ciphers from the server (i.e. obsolete restrictions on export + ciphers). Default is <c>false</c>. + </p> + </item> + <tag><c><![CDATA[debug = true | false <optional>]]></c></tag> + <item> + <p>Causes debug information to be written to standard + output. Default is <c>false</c>. + </p> + </item> + <tag><c><![CDATA[debugdir = path() | false <optional>]]></c></tag> + <item> + <p>Causes debug information output controlled by <c>debug</c> + and <c>msgdebug</c> to be printed to a file named + <c><![CDATA[ssl_esock.<pid>.log]]></c> in the directory specified by + <c>debugdir</c>, where <c><![CDATA[<pid>]]></c> is the operating system + specific textual representation of the process identifier + of the external port program of the SSL application. Default + is <c>false</c>, i.e. no log file is produced. + </p> + </item> + <tag><c><![CDATA[msgdebug = true | false <optional>]]></c></tag> + <item> + <p>Sets <c>debug = true</c> and causes also the contents + of low level messages to be printed to standard output. + Default is <c>false</c>. + </p> + </item> + <tag><c><![CDATA[port_program = string() | false <optional>]]></c></tag> + <item> + <p>Name of port program. The default is <c>ssl_esock</c>. + </p> + </item> + <tag><c><![CDATA[protocol_version = [sslv2|sslv3|tlsv1] <optional>]]></c>.</tag> + <item> + <p>Name of protocols to use. If this option is not set, + all protocols are assumed, i.e. the default value is + <c>[sslv2, sslv3, tlsv1]</c>. + </p> + </item> + <tag><c><![CDATA[proxylsport = integer() | false <optional>]]></c></tag> + <item> + <p>Define the port number of the listen port of the + SSL port program. Almost never is this option needed. + </p> + </item> + <tag><c><![CDATA[proxylsbacklog = integer() | false <optional>]]></c></tag> + <item> + <p>Set the listen queue size of the listen port of the + SSL port program. The default is 128. + </p> + </item> + </taglist> + </section> + + <section> + <title>OpenSSL libraries</title> + <p>The current implementation of the Erlang SSL application is + based on the <em>OpenSSL</em> package version 0.9.7 or higher. + There are source and binary releases on the web. + </p> + <p>Source releases of OpenSSL can be downloaded from the <url href="http://www.openssl.org">OpenSSL</url> project home page, + or mirror sites listed there. + </p> + <p>The same URL also contains links to some compiled binaries and + libraries of OpenSSL (see the <c>Related/Binaries</c> menu) of + which the <url href="http://www.shininglightpro.com/search.php?searchname=Win32+OpenSSL">Shining Light Productions Win32 and OpenSSL</url> pages are of + interest for the Win32 user. + </p> + <p>For some Unix flavours there are binary packages available + on the net. + </p> + <p>If you cannot find a suitable binary OpenSSL package, you + have to fetch an OpenSSL source release and compile it. + </p> + <p>You then have to compile and install the libraries + <c>libcrypto.so</c> and <c>libssl.so</c> (Unix), or the + libraries <c>libeay32.dll</c> and <c>ssleay32.dll</c> (Win32). + </p> + <p>For Unix The <c>ssl_esock</c> port program is delivered linked + to OpenSSL libraries in <c>/usr/local/lib</c>, but the default + dynamic linking will also accept libraries in <c>/lib</c> and + <c>/usr/lib</c>. + </p> + <p>If that is not applicable to the particular Unix operating + system used, the example <c>Makefile</c> in the SSL + <c>priv/obj</c> directory, should be used as a guide to + relinking the final version of the port program. + </p> + <p>For <c>Win32</c> it is only required that the libraries can be + found from the <c>PATH</c> environment variable, or that they + reside in the appropriate <c>SYSTEM32</c> directory; hence no + particular relinking is need. Hence no example <c>Makefile</c> + for Win32 is provided.</p> + </section> + + <section> + <title>Restrictions</title> + <p>Users must be aware of export restrictions and patent rights + concerning cryptographic software. + </p> + </section> + + <section> + <title>SEE ALSO</title> + <p>application(3)</p> + </section> + +</appref> + + diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml new file mode 100644 index 0000000000..c743cd67a3 --- /dev/null +++ b/lib/ssl/doc/src/ssl_distribution.xml @@ -0,0 +1,235 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2000</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Using SSL for Erlang Distribution</title> + <prepared>P Nyblom</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>2003-04-01</date> + <rev>B</rev> + <file>ssl_distribution.xml</file> + </header> + <p>This chapter describes how the Erlang distribution can use + SSL to get additional verification and security.</p> + + <section> + <title>Introduction</title> + <p>The Erlang distribution can in theory use almost any connection + based protocol as bearer. A module that implements the protocol + specific parts of connection setup is however needed. The + default distribution module is <c>inet_tcp_dist</c> which is + included in the Kernel application. When starting an + Erlang node distributed, <c>net_kernel</c> uses this module to + setup listen ports and connections. </p> + <p>In the SSL application there is an additional distribution + module, <c>inet_ssl_dist</c> which can be used as an + alternative. All distribution connections will be using SSL and + all participating Erlang nodes in a distributed system must use + this distribution module.</p> + <p>The security depends on how the connections are set up, one can + use key files or certificates to just get a crypted + connection. One can also make the SSL package verify the + certificates of other nodes to get additional security. + Cookies are however always used as they can be used to + differentiate between two different Erlang networks.</p> + <p>Setting up Erlang distribution over SSL involves some simple but + necessary steps:</p> + <list type="bulleted"> + <item>Building boot scripts including the SSL application</item> + <item>Specifying the distribution module for net_kernel</item> + <item>Specifying security options and other SSL options</item> + </list> + <p>The rest of this chapter describes the above mentioned steps in + more detail.</p> + </section> + + <section> + <title>Building boot scripts including the SSL application</title> + <p>Boot scripts are built using the <c>systools</c> utility in the + SASL application. Refer to the SASL documentations + for more information on systools. This is only an example of + what can be done.</p> + <p>The simplest boot script possible includes only the Kernel + and STDLIB applications. Such a script is located in the + Erlang distributions bin directory. The source for the script + can be found under the Erlang installation top directory under + <c><![CDATA[releases/<OTP version>start_clean.rel]]></c>. Copy that + script to another location (and preferably another name) + and add the SSL application with its current version number + after the STDLIB application.</p> + <p>An example .rel file with SSL added may look like this:</p> + <code type="none"> +{release, {"OTP APN 181 01","P7A"}, {erts, "5.0"}, + [{kernel,"2.5"}, + {stdlib,"1.8.1"}, + {ssl,"2.2.1"}]}. </code> + <p>Note that the version numbers surely will differ in your system. + Whenever one of the applications included in the script is + upgraded, the script has to be changed.</p> + <p>Assuming the above .rel file is stored in a file + <c>start_ssl.rel</c> in the current directory, a boot script + can be built like this:</p> + <code type="none"> +1> systools:make_script("start_ssl",[]). </code> + <p>There will now be a file <c>start_ssl.boot</c> in the current + directory. To test the boot script, start Erlang with the + <c>-boot</c> command line parameter specifying this boot script + (with its full path but without the <c>.boot</c> suffix), in + Unix it could look like this:</p> + <p></p> + <code type="none"><![CDATA[ +$ erl -boot /home/me/ssl/start_ssl +Erlang (BEAM) emulator version 5.0 + +Eshell V5.0 (abort with ^G) +1> whereis(ssl_server). +<0.32.0> ]]></code> + <p>The <c>whereis</c> function call verifies that the SSL + application is really started.</p> + <p>As an alternative to building a bootscript, one can explicitly + add the path to the ssl <c>ebin</c> directory on the command + line. This is done with the command line option <c>-pa</c>. This + works as the ssl application really need not be started for the + distribution to come up, a primitive version of the ssl server + is started by the distribution module itself, so as long as the + primitive code server can reach the code, the distribution will + start. The <c>-pa</c> method is only recommended for testing + purposes.</p> + </section> + + <section> + <title>Specifying distribution module for net_kernel</title> + <p>The distribution module for SSL is named <c>inet_ssl_dist</c> + and is specified on the command line whit the <c>-proto_dist</c> + option. The argument to <c>-proto_dist</c> should be the module + name without the <c>_dist</c> suffix, so this distribution + module is specified with <c>-proto_dist inet_ssl</c> on the + command line.</p> + <p></p> + <p>Extending the command line from above gives us the following:</p> + <code type="none"> +$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_ssl </code> + <p>For the distribution to actually be started, we need to give + the emulator a name as well:</p> + <code type="none"> +$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_ssl -sname ssl_test +Erlang (BEAM) emulator version 5.0 [source] + +Eshell V5.0 (abort with ^G) +(ssl_test@myhost)1> </code> + <p>Note however that a node started in this way will refuse to talk + to other nodes, as no certificates or key files are supplied + (see below).</p> + <p>When the SSL distribution starts, the OTP system is in its + early boot stage, why neither <c>application</c> nor <c>code</c> + are usable. As SSL needs to start a port program in this early + stage, it tries to determine the path to that program from the + primitive code loaders code path. If this fails, one need to + specify the directory where the port program resides. This can + be done either with an environment variable + <c>ERL_SSL_PORTPROGRAM_DIR</c> or with the command line option + <c>-ssl_portprogram_dir</c>. The value should be the directory + where the <c>ssl_esock</c> port program is located. Note that + this option is never needed in a normal Erlang installation.</p> + </section> + + <section> + <title>Specifying security options and other SSL options</title> + <p>For SSL to work, you either need certificate files or a + key file. Certificate files can be specified both when working as + client and as server (connecting or accepting). </p> + <p></p> + <p>On the <c>erl</c> command line one can specify options that the + ssl distribution will add when creation a socket. It is + mandatory to specify at least a key file or client and server + certificates. One can specify any <em>SSL option</em> on the + command line, but must not specify any socket options (like + packet size and such). The SSL options are listed in the + Reference Manual. The only difference between the + options in the reference manual and the ones that can be + specified to the distribution on the command line is that + <c>certfile</c> can (and usually needs to) be specified as + <c>client_certfile</c> and <c>server_certfile</c>. The + <c>client_certfile</c> is used when the distribution initiates a + connection to another node and the <c>server_cerfile</c> is used + when accepting a connection from a remote node. </p> + <p>The command line argument for specifying the SSL options is named + <c>-ssl_dist_opt</c> and should be followed by an even number of + SSL options/option values. The <c>-ssl_dist_opt</c> argument can + be repeated any number of times.</p> + <p>An example command line would now look something like this + (line breaks in the command are for readability, + they should not be there when typed):</p> + <code type="none"> +$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_ssl + -ssl_dist_opt client_certfile "/home/me/ssl/erlclient.pem" + -ssl_dist_opt server_certfile "/home/me/ssl/erlserver.pem" + -ssl_dist_opt verify 1 depth 1 + -sname ssl_test +Erlang (BEAM) emulator version 5.0 [source] + +Eshell V5.0 (abort with ^G) +(ssl_test@myhost)1> </code> + <p>A node started in this way will be fully functional, using SSL + as the distribution protocol.</p> + </section> + + <section> + <title>Setting up environment to always use SSL</title> + <p>A convenient way to specify arguments to Erlang is to use the + <c>ERL_FLAGS</c> environment variable. All the flags needed to + use SSL distribution can be specified in that variable and will + then be interpreted as command line arguments for all + subsequent invocations of Erlang.</p> + <p></p> + <p>In a Unix (Bourne) shell it could look like this (line breaks for + readability):</p> + <code type="none"> +$ ERL_FLAGS="-boot \\"/home/me/ssl/start_ssl\\" -proto_dist inet_ssl + -ssl_dist_opt client_certfile \\"/home/me/ssl/erlclient.pem\\" + -ssl_dist_opt server_certfile \\"/home/me/ssl/erlserver.pem\\" + -ssl_dist_opt verify 1 -ssl_dist_opt depth 1" +$ export ERL_FLAGS +$ erl -sname ssl_test +Erlang (BEAM) emulator version 5.0 [source] + +Eshell V5.0 (abort with ^G) +(ssl_test@myhost)1> init:get_arguments(). +[{root,["/usr/local/erlang"]}, + {progname,["erl "]}, + {sname,["ssl_test"]}, + {boot,["/home/me/ssl/start_ssl"]}, + {proto_dist,["inet_ssl"]}, + {ssl_dist_opt,["client_certfile","/home/me/ssl/erlclient.pem"]}, + {ssl_dist_opt,["server_certfile","/home/me/ssl/erlserver.pem"]}, + {ssl_dist_opt,["verify","1"]}, + {ssl_dist_opt,["depth","1"]}, + {home,["/home/me"]}] </code> + <p>The <c>init:get_arguments()</c> call verifies that the correct + arguments are supplied to the emulator. </p> + </section> +</chapter> + + diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml new file mode 100644 index 0000000000..3dc2332795 --- /dev/null +++ b/lib/ssl/doc/src/ssl_protocol.xml @@ -0,0 +1,349 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>The SSL Protocol</title> + <prepared>Peter Högfeldt</prepared> + <docno></docno> + <date>2003-04-28</date> + <rev>PA2</rev> + <file>ssl_protocol.xml</file> + </header> + <p>Here we provide a short introduction to the SSL protocol. We only + consider those part of the protocol that are important from a + programming point of view. + </p> + <p>For a very good general introduction to SSL and TLS see the book + <cite id="rescorla"></cite>. + </p> + <p><em>Outline:</em></p> + <list type="bulleted"> + <item>Two types of connections - connection: handshake, data transfer, and + shutdown - + SSL/TLS protocol - server must have certificate - what the the + server sends to the client - client may verify the server - + server may ask client for certificate - what the client sends to + the server - server may then verify the client - verification - + certificate chains - root certificates - public keys - key + agreement - purpose of certificate - references</item> + </list> + + <section> + <title>SSL Connections</title> + <p>The SSL protocol is implemented on top of the TCP/IP protocol. + From an endpoint view it also has the same type of connections + as that protocol, almost always created by calls to socket + interface functions <em>listen</em>, <em>accept</em> and + <em>connect</em>. The endpoints are <em>servers</em> and + <em>clients</em>. + </p> + <p>A <em>server</em><em>listen</em>s for connections on a + specific address and port. This is done once. The server then + <em>accept</em>s each connections on that same address and + port. This is typically done indefinitely many times. + </p> + <p>A <em>client</em> connects to a server on a specific address + and port. For each purpose this is done once. + </p> + <p>For a plain TCP/IP connection the establishment of a connection + (through an accept or a connect) is followed by data transfer between + the client and server, finally ended by a connection close. + </p> + <p>An SSL connection also consists of data transfer and connection + close, However, the data transfer contains encrypted data, and + in order to establish the encryption parameters, the data + transfer is preceded by an SSL <em>handshake</em>. In this + handshake the server plays a dominant role, and the main + instrument used in achieving a valid SSL connection is the + server's <em>certificate</em>. We consider certificates in the + next section, and the SSL handshake in a subsequent section.</p> + </section> + + <section> + <title>Certificates</title> + <p>A certificate is similar to a driver's license, or a + passport. The holder of the certificate is called the + <em>subject</em>. First of all the certificate identifies the + subject in terms of the name of the subject, its postal address, + country name, company name (if applicable), etc. + </p> + <p>Although a driver's license is always issued by a well-known and + distinct authority, a certificate may have an <em>issuer</em> + that is not so well-known. Therefore a certificate also always + contains information on the issuer of the certificate. That + information is of the same type as the information on the + subject. The issuer of a certificate also signs the certificate + with a <em>digital signature</em> (the signature is an inherent + part of the certificate), which allow others to verify that the + issuer really is the issuer of the certificate. + </p> + <p>Now that a certificate can be checked by verifying the + signature of the issuer, the question is how to trust the + issuer. The answer to this question is to require that there is + a certificate for the issuer as well. That issuer has in turn an + issuer, which must also have a certificate, and so on. This + <em>certificate chain</em> has to have en end, which then must + be a certificate that is trusted by other means. We shall cover + this problem of <em>authentication</em> in a subsequent + section. + </p> + </section> + + <section> + <title>Encryption Algorithms</title> + <p>An encryption algorithm is a mathematical algorithm for + encryption and decryption of messages (arrays of bytes, + say). The algorithm as such is always required to be publicly + known, otherwise its strength cannot be evaluated, and hence it + cannot be used reliably. The secrecy of an encrypted message is + not achieved by the secrecy of the algorithm used, but by the + secrecy of the <em>keys</em> used as input to the encryption and + decryption algorithms. For an account of cryptography in general + see <cite id="schneier"></cite>. + </p> + <p>There are two classes of encryption algorithms: <em>symmetric key</em> algorithms and <em>public key</em> algorithms. Both + types of algorithms are used in the SSL protocol. + </p> + <p>In the sequel we assume holders of keys keep them secret (except + public keys) and that they in that sense are trusted. How a + holder of a secret key is proved to be the one it claims to be + is a question of <em>authentication</em>, which, in the context + of the SSL protocol, is described in a section further below. + </p> + + <section> + <title>Symmetric Key Algorithms</title> + <p>A <em>symmetric key</em> algorithm has one key only. The key + is used for both encryption and decryption. Obviously the key + of a symmetric key algorithm must always be kept secret by the + users of the key. DES is an example of a symmetric key + algorithm. + </p> + <p>Symmetric key algorithms are fast compared to public key + algorithms. They are therefore typically used for encrypting + bulk data. + </p> + </section> + + <section> + <title>Public Key Algorithms</title> + <p>A <em>public key</em> algorithm has two keys. Any of the two + keys can be used for encryption. A message encrypted with one + of the keys, can only be decrypted with the other key. One of + the keys is public (known to the world), while the other key + is private (i.e. kept secret) by the owner of the two keys. + </p> + <p>RSA is an example of a public key algorithm. + </p> + <p>Public key algorithms are slow compared to symmetric key + algorithms, and they are therefore seldom used for bulk data + encryption. They are therefore only used in cases where the + fact that one key is public and the other is private, provides + features that cannot be provided by symmetric algorithms. + </p> + </section> + + <section> + <title>Digital Signature Algorithms</title> + <p>An interesting feature of a public key algorithm is that its + public and private keys can both be used for encryption. + Anyone can use the public key to encrypt a message, and send + that message to the owner of the private key, and be sure of + that only the holder of the private key can decrypt the + message. + </p> + <p>On the other hand, the owner of the private key can encrypt a + message with the private key, thus obtaining an encrypted + message that can decrypted by anyone having the public key. + </p> + <p>The last approach can be used as a digital signature + algorithm. The holder of the private key signs an array of + bytes by performing a specified well-known <em>message digest algorithm</em> to compute a hash of the array, encrypts the + hash value with its private key, an then presents the original + array, the name of the digest algorithm, and the encryption of + the hash value as a <em>signed array of bytes</em>. + </p> + <p>Now anyone having the public key, can decrypt the encrypted + hash value with that key, compute the hash with the specified + digest algorithm, and check that the hash values compare equal + in order to verify that the original array was indeed signed + by the holder of the private key. + </p> + <p>What we have accounted for so far is by no means all that can + be said about digital signatures (see <cite id="schneier"></cite>for + further details). + </p> + </section> + + <section> + <title>Message Digests Algorithms</title> + <p>A message digest algorithm is a hash function that accepts + an array bytes of arbitrary but finite length of input, and + outputs an array of bytes of fixed length. Such an algorithm + is also required to be very hard to invert. + </p> + <p>MD5 (16 bytes output) and SHA1 (20 bytes output) are examples + of message digest algorithms. + </p> + </section> + </section> + + <section> + <title>SSL Handshake</title> + <p>The main purpose of the handshake performed before an an SSL + connection is established is to negotiate the encryption + algorithm and key to be used for the bulk data transfer between + the client and the server. We are writing <em>the</em> key, + since the algorithm to choose for bulk encryption one of the + symmetric algorithms. + </p> + <p>There is thus only one key to agree upon, and obviously that + key has to be kept secret between the client and the server. To + obtain that the handshake has to be encrypted as well. + </p> + <p>The SSL protocol requires that the server always sends its + certificate to the client in the beginning of the handshake. The + client then retrieves the server's public key from the + certificate, which means that the client can use the server's + public key to encrypt messages to the server, and the server can + decrypt those messages with its private key. Similarly, the + server can encrypt messages to the client with its private key, + and the client can decrypt messages with the server's public + key. It is thus is with the server's public and private keys + that messages in the handshake are encrypted and decrypted, and + hence the key agreed upon for symmetric encryption of bulk data + can be kept secret (there are more things to consider to really + keep it secret, see <cite id="rescorla"></cite>). + </p> + <p>The above indicates that the server does not care who is + connecting, and that only the client has the possibility to + properly identify the server based on the server's certificate. + That is indeed true in the minimal use of the protocol, but it + is possible to instruct the server to request the certificate of + the client, in order to have a means to identify the client, but + it is by no means required to establish an SSL connection. + </p> + <p>If a server request the client certificate, it verifies, as a + part of the protocol, that the client really holds the private + key of the certificate by sending the client a string of bytes + to encrypt with its private key, which the server then decrypts + with the client's public key, the result of which is compared + with the original string of bytes (a similar procedure is always + performed by the client when it has received the server's + certificate). + </p> + <p>The way clients and servers <em>authenticate</em> each other, + i.e. proves that their respective peers are what they claim to + be, is the topic of the next section. + </p> + </section> + + <section> + <title>Authentication</title> + <p>As we have already seen the reception of a certificate from a + peer is not enough to prove that the peer is authentic. More + certificates are needed, and we have to consider how certificates + are issued and on what grounds. + </p> + <p>Certificates are issued by <em>certification authorities</em> + (<em>CA</em>s) only. They issue certificates both for other CAs + and ordinary users (which are not CAs). + </p> + <p>Certain CAs are <em>top CAs</em>, i.e. they do not have a + certificate issued by another CA. Instead they issue their own + certificate, where the subject and issuer part of the + certificate are identical (such a certificate is called a + self-signed certificate). A top CA has to be well-known, and has + to have a publicly available policy telling on what grounds it + issues certificates. + </p> + <p>There are a handful of top CAs in the world. You can examine the + certificates of several of them by clicking through the menus of + your web browser. + </p> + <p>A top CA typically issues certificates for other CAs, called + <em>intermediate CAs</em>, but possibly also to ordinary users. Thus + the certificates derivable from a top CA constitute a tree, where + the leaves of the tree are ordinary user certificates. + </p> + <p>A <em>certificate chain</em> is an ordered sequence of + certificates, <c>C1, C2, ..., Cn</c>, say, where <c>C1</c> is a + top CA certificate, and where <c>Cn</c> is an ordinary user + certificate, and where the holder of <c>C1</c> is the issuer of + <c>C2</c>, the holder of <c>C2</c> is the issuer of <c>C3</c>, + ..., and the holder of <c>Cn-1</c> is the issuer of <c>Cn</c>, + the ordinary user certificate. The holders of <c>C2, C3, ..., Cn-1</c> are then intermediate CAs. + </p> + <p>Now to verify that a certificate chain is unbroken we have to + take the public key from each certificate <c>Ck</c>, and apply + that key to decrypt the signature of certificate <c>Ck-1</c>, + thus obtaining the message digest computed by the holder of the + <c>Ck</c> certificate, compute the real message digest of the + <c>Ck-1</c> certificate and compare the results. If they compare + equal the link of the chain between <c>Ck</c> and <c>Ck-1</c> is + considered to unbroken. This is done for each link k = 1, 2, + ..., n-1. If all links are found to be unbroken, the user + certificate <c>Cn</c> is considered authenticated. + </p> + + <section> + <title>Trusted Certificates</title> + <p>Now that there is a way to authenticate a certificate by + checking that all links of a certificate chain are unbroken, + the question is how you can be sure to trust the certificates + in the chain, and in particular the top CA certificate of the + chain. + </p> + <p>To provide an answer to that question consider the + perspective of a client, which have just received the + certificate of the server. In order to authenticate the server + the client has to construct a certificate chain and to prove + that the chain is unbroken. The client has to have a set of CA + certificates (top CA or intermediate CA certificates) not + obtained from the server, but obtained by other means. Those + certificates are kept <c>locally</c> by the client, and are + trusted by the client. + </p> + <p>More specifically, the client does not really have to have + top CA certificates in its local storage. In order to + authenticate a server it is sufficient for the client to + posses the trusted certificate of the issuer of the server + certificate. + </p> + <p>Now that is not the whole story. A server can send an + (incomplete) certificate chain to its client, and then the + task of the client is to construct a certificate chain that + begins with a trusted certificate and ends with the server's + certificate. (A client can also send a chain to its server, + provided the server requested the client's certificate.) + </p> + <p>All this means that an unbroken certificate chain begins with + a trusted certificate (top CA or not), and ends with the peer + certificate. That is the end of the chain is obtained from the + peer, but the beginning of the chain is obtained from local + storage, which is considered trusted. + </p> + </section> + </section> +</chapter> + + diff --git a/lib/ssl/doc/src/usersguide.xml b/lib/ssl/doc/src/usersguide.xml new file mode 100644 index 0000000000..98071f5742 --- /dev/null +++ b/lib/ssl/doc/src/usersguide.xml @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2000</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>SSL User's Guide</title> + <prepared>OTP Team</prepared> + <docno></docno> + <date>2003-05-26</date> + <rev>B</rev> + <file>usersguide.sgml</file> + </header> + <description> + <p>The <em>SSL</em> application provides secure communication over + sockets. + </p> + <p>This product includes software developed by the OpenSSL Project for + use in the OpenSSL Toolkit (http://www.openssl.org/). + </p> + <p>This product includes cryptographic software written by Eric Young + ([email protected]). + </p> + <p>This product includes software written by Tim Hudson + ([email protected]). + </p> + <p>For full OpenSSL and SSLeay license texts, see <seealso marker="licenses#licenses">Licenses</seealso>. + </p> + </description> + <xi:include href="ssl_protocol.xml"/> + <xi:include href="using_ssl.xml"/> + <xi:include href="pkix_certs.xml"/> + <xi:include href="create_certs.xml"/> + <xi:include href="ssl_distribution.xml"/> + <xi:include href="licenses.xml"/> +</part> + + diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml new file mode 100644 index 0000000000..ba74dcfef4 --- /dev/null +++ b/lib/ssl/doc/src/using_ssl.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Using the SSL application</title> + <prepared>Peter Högfeldt</prepared> + <docno></docno> + <date>2003-04-23</date> + <rev>PA2</rev> + <file>using_ssl.xml</file> + </header> + <p>Here we provide an introduction to using the Erlang/OTP SSL + application, which is accessed through the <c>ssl</c> interface + module. + </p> + <p>We also present example code in the Erlang module + <c>client_server</c>, also provided in the directory + <c>ssl-X.Y.Z/examples</c>, with source code in <c>src</c> and the + compiled module in <c>ebin</c> of that directory. + </p> + + <section> + <title>The ssl Module</title> + <p>The <c>ssl</c> module provides the user interface to the Erlang/OTP + SSL application. The interface functions provided are very similar + to those provided by the <c>gen_tcp</c> and <c>inet</c> modules. + </p> + <p>Servers use the interface functions <c>listen</c> and + <c>accept</c>. The <c>listen</c> function specifies a TCP port + to to listen to, and each call to the <c>accept</c> function + establishes an incoming connection. + </p> + <p>Clients use the <c>connect</c> function which specifies the address + and port of a server to connect to, and a successful call establishes + such a connection. + </p> + <p>The <c>listen</c> and <c>connect</c> functions have almost all + the options that the corresponding functions in <c>gen_tcp/</c> have, + but there are also additional options specific to the SSL protocol. + </p> + <p>The most important SSL specific option is the <c>cacertfile</c> + option which specifies a local file containing trusted CA + certificates which are and used for peer authentication. This + option is used by clients and servers in case they want to + authenticate their peers. + </p> + <p>The <c>certfile</c> option specifies a local path to a file + containing the certificate of the holder of the connection + endpoint. In case of a server endpoint this option is mandatory + since the contents of the sever certificate is needed in the + the handshake preceding the establishment of a connection. + </p> + <p>Similarly, the <c>keyfile</c> option points to a local file + containing the private key of the holder of the endpoint. If the + <c>certfile</c> option is present, this option has to be + specified as well, unless the private key is provided in the + same file as specified by the <c>certfile</c> option (a + certificate and a private key can thus coexist in the same file). + </p> + <p>The <c>verify</c> option specifies how the peer should be verified: + </p> + <taglist> + <tag>0</tag> + <item>Do not verify the peer,</item> + <tag>1</tag> + <item>Verify peer,</item> + <tag>2</tag> + <item>Verify peer, fail the verification if the peer has no + certificate. </item> + </taglist> + <p>The <c>depth</c> option specifies the maximum length of the + verification certificate chain. Depth = 0 means the peer + certificate, depth = 1 the CA certificate, depth = 2 the next CA + certificate etc. If the verification process does not find a + trusted CA certificate within the maximum length, the verification + fails. + </p> + <p>The <c>ciphers</c> option specifies which ciphers to use (a + string of colon separated cipher names). To obtain a list of + available ciphers, evaluate the <c>ssl:ciphers/0</c> function + (the SSL application has to be running). + </p> + </section> + + <section> + <title>A Client-Server Example</title> + <p>Here is a simple client server example. + </p> + <codeinclude file="../../examples/src/client_server.erl" tag="" type="erl"></codeinclude> + </section> +</chapter> + + + diff --git a/lib/ssl/doc/src/warning.gif b/lib/ssl/doc/src/warning.gif Binary files differnew file mode 100644 index 0000000000..96af52360e --- /dev/null +++ b/lib/ssl/doc/src/warning.gif |
