aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc
diff options
context:
space:
mode:
authorDan Gudmundsson <[email protected]>2009-12-10 10:09:12 +0000
committerErlang/OTP <[email protected]>2009-12-10 10:09:12 +0000
commit8ac319031230b354dcea105d94ef2a232a9d7afe (patch)
tree139f52d1fad7786dcab88f4b65956f780cd3da00 /lib/ssl/doc
parent9855ed863b58f7325f39b00c60813198ec41f528 (diff)
downloadotp-8ac319031230b354dcea105d94ef2a232a9d7afe.tar.gz
otp-8ac319031230b354dcea105d94ef2a232a9d7afe.tar.bz2
otp-8ac319031230b354dcea105d94ef2a232a9d7afe.zip
Cleaned up docs
Diffstat (limited to 'lib/ssl/doc')
-rw-r--r--lib/ssl/doc/src/create_certs.xml14
-rw-r--r--lib/ssl/doc/src/new_ssl.xml23
-rw-r--r--lib/ssl/doc/src/pkix_certs.xml213
-rw-r--r--lib/ssl/doc/src/remember.xml83
-rw-r--r--lib/ssl/doc/src/ssl.xml35
5 files changed, 27 insertions, 341 deletions
diff --git a/lib/ssl/doc/src/create_certs.xml b/lib/ssl/doc/src/create_certs.xml
index 15958ee457..79cc8a0537 100644
--- a/lib/ssl/doc/src/create_certs.xml
+++ b/lib/ssl/doc/src/create_certs.xml
@@ -98,12 +98,12 @@
<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>
+ openssl req -new -x509 -config /some/path/req.cnf \\
+ -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>
+ </p>
</section>
<section>
@@ -111,12 +111,12 @@
<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>
+ openssl req -new -config /some/path/req.cnf \\
+ -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>
+ openssl ca -batch -notext -config /some/path/req.cnf \\
+ -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.
diff --git a/lib/ssl/doc/src/new_ssl.xml b/lib/ssl/doc/src/new_ssl.xml
index f50f714fe6..a11919eb51 100644
--- a/lib/ssl/doc/src/new_ssl.xml
+++ b/lib/ssl/doc/src/new_ssl.xml
@@ -437,30 +437,17 @@ end
</func>
<func>
- <name>peercert(Socket) -> </name>
- <name>peercert(Socket, Opts) -> {ok, Cert} | {error, Reason}</name>
+ <name>peercert(Socket) -> {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>Cert = binary()</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>
+ <p>The peer certificate is returned as a DER encoded binary.
+ The certificate can be decoded with <c>public_key:pkix_decode_cert/2</c>.
+ </p>
</desc>
</func>
<func>
diff --git a/lib/ssl/doc/src/pkix_certs.xml b/lib/ssl/doc/src/pkix_certs.xml
index 47818c1b7d..1de807cadc 100644
--- a/lib/ssl/doc/src/pkix_certs.xml
+++ b/lib/ssl/doc/src/pkix_certs.xml
@@ -34,219 +34,24 @@
<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>
<p>Working certificate definitions for the Internet Community are found
- in the the PKIX RFCs <cite id="rfc3279"></cite>and <cite id="rfc3280"></cite>.
+ 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>
<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>
+ </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>
+ <p>Certificate handling is now handled by the <c>public_key</c> application.</p>
+ <p>
+ DER encoded certificates returned by <c>ssl:peercert/1</c> can for example
+ be decoded by the <c>public_key:pkix_decode_cert/2</c> function.
+ </p>
</section>
</chapter>
diff --git a/lib/ssl/doc/src/remember.xml b/lib/ssl/doc/src/remember.xml
deleted file mode 100644
index 799627a33c..0000000000
--- a/lib/ssl/doc/src/remember.xml
+++ /dev/null
@@ -1,83 +0,0 @@
-<?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.xml b/lib/ssl/doc/src/ssl.xml
index 9b780b14ce..217eb791d0 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -347,39 +347,17 @@
</desc>
</func>
<func>
- <name>peercert(Socket) -> </name>
- <name>peercert(Socket, Opts) -> {ok, Cert} | {ok, Subject} | {error, Reason}</name>
+ <name>peercert(Socket) -> {ok, Cert} | {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>Cert = binary()()</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>
+ <p>Returns the DER encoded peer certificate, the certificate can be decoded with
+ <c>public_key:pkix_decode_cert/2</c>.
+ </p>
</desc>
</func>
<func>
@@ -719,8 +697,7 @@
<section>
<title>SEE ALSO</title>
- <p>gen_tcp(3), inet(3)
- </p>
+ <p>gen_tcp(3), inet(3) public_key(3) </p>
</section>
</erlref>