aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssl/doc')
-rw-r--r--lib/ssl/doc/html/.gitignore0
-rw-r--r--lib/ssl/doc/man3/.gitignore0
-rw-r--r--lib/ssl/doc/man6/.gitignore0
-rw-r--r--lib/ssl/doc/pdf/.gitignore0
-rw-r--r--lib/ssl/doc/src/Makefile130
-rw-r--r--lib/ssl/doc/src/book.xml51
-rw-r--r--lib/ssl/doc/src/cite.defs112
-rw-r--r--lib/ssl/doc/src/create_certs.xml148
-rw-r--r--lib/ssl/doc/src/fascicules.xml19
-rw-r--r--lib/ssl/doc/src/insidecover.xml14
-rw-r--r--lib/ssl/doc/src/licenses.xml156
-rw-r--r--lib/ssl/doc/src/make.dep30
-rw-r--r--lib/ssl/doc/src/new_ssl.xml678
-rw-r--r--lib/ssl/doc/src/note.gifbin0 -> 1539 bytes
-rw-r--r--lib/ssl/doc/src/notes.xml1132
-rw-r--r--lib/ssl/doc/src/pkix_certs.xml253
-rw-r--r--lib/ssl/doc/src/refman.xml51
-rw-r--r--lib/ssl/doc/src/release_notes.xml49
-rw-r--r--lib/ssl/doc/src/remember.xml83
-rw-r--r--lib/ssl/doc/src/ssl.fig10
-rw-r--r--lib/ssl/doc/src/ssl.xml728
-rw-r--r--lib/ssl/doc/src/ssl_app.xml182
-rw-r--r--lib/ssl/doc/src/ssl_distribution.xml235
-rw-r--r--lib/ssl/doc/src/ssl_protocol.xml349
-rw-r--r--lib/ssl/doc/src/usersguide.xml55
-rw-r--r--lib/ssl/doc/src/using_ssl.xml113
-rw-r--r--lib/ssl/doc/src/warning.gifbin0 -> 1498 bytes
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&ouml;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&ouml;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&ouml;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
+ *
+ * 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>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; CallbackModule =
+ atom()</c>
+ </p> <p><c>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; DataTag =
+ atom() - tag used in socket data message.</c></p>
+ <p><c>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 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> &gt; 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
new file mode 100644
index 0000000000..6fffe30419
--- /dev/null
+++ b/lib/ssl/doc/src/note.gif
Binary files differ
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&ouml;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&ouml;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&ouml;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
+ </p>
+ <p>This product includes software written by Tim Hudson
+ </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&ouml;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
+ </p>
+ <p>This product includes software written by Tim Hudson
+ </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&ouml;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&ouml;gfeldt</prepared>
+ <responsible>Peter H&ouml;gfeldt</responsible>
+ <docno></docno>
+ <approved>Peter H&ouml;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&ouml;gfeldt</prepared>
+ <responsible>Peter H&ouml;gfeldt</responsible>
+ <docno></docno>
+ <approved>Peter H&ouml;gfeldt</approved>
+ <checked>Peter H&ouml;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&ouml;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
+ </p>
+ <p>This product includes software written by Tim Hudson
+ </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&ouml;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
new file mode 100644
index 0000000000..96af52360e
--- /dev/null
+++ b/lib/ssl/doc/src/warning.gif
Binary files differ