diff options
| -rw-r--r-- | lib/public_key/doc/src/cert_records.xml | 34 | ||||
| -rw-r--r-- | lib/ssl/doc/src/create_certs.xml | 14 | ||||
| -rw-r--r-- | lib/ssl/doc/src/new_ssl.xml | 23 | ||||
| -rw-r--r-- | lib/ssl/doc/src/pkix_certs.xml | 213 | ||||
| -rw-r--r-- | lib/ssl/doc/src/remember.xml | 83 | ||||
| -rw-r--r-- | lib/ssl/doc/src/ssl.xml | 35 |
6 files changed, 45 insertions, 357 deletions
diff --git a/lib/public_key/doc/src/cert_records.xml b/lib/public_key/doc/src/cert_records.xml index 8fb4ea5fd0..8cfe57f670 100644 --- a/lib/public_key/doc/src/cert_records.xml +++ b/lib/public_key/doc/src/cert_records.xml @@ -41,10 +41,18 @@ </p> <p>Use the following include directive to get access to the - records and constant macros described in the following sections.</p> + records and constant macros (OIDs) described in the following sections.</p> <code> -include_lib("public_key/include/public_key.hrl"). </code> + <p>The used specification is available in <c>OTP-PKIX.asn1</c>, + 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>asn1</c> subdirectory + of the application <c>public_key</c>. + </p> + <section> <title>Common Data Types</title> @@ -148,8 +156,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p> }. </code> -<p><c>id_attributes() = ?oid_name_as_erlang_atom</c> -for available oid names see table below. Ex: ?'id-at-name'</p> +<p><c>id_attributes() </c></p> <table> <row> <cell align="left" valign="middle">OID name</cell> @@ -231,8 +238,7 @@ for available oid names see table below. Ex: ?'id-at-name'</p> }. </code> -<p><c> id_public_key_algorithm() = ?oid_name_as_erlang_atom</c> for available -oid names see table below. Ex: ?'id-dsa'</p> +<p><c> id_public_key_algorithm() </c></p> <table> <row> <cell align="left" valign="middle">OID name</cell> @@ -264,14 +270,11 @@ oid names see table below. Ex: ?'id-dsa'</p> }. </code> -<p><c>id_extensions() = ?oid_name_as_erlang_atom</c> for -available oid names see tables. Ex: ?'id-ce-authorityKeyIdentifier'<seealso -marker="#StdCertExt">Standard Certificate Extensions</seealso>, - <seealso - marker="#PrivIntExt">Private Internet Extensions</seealso>, <seealso - marker="#CRLCertExt">CRL Extensions</seealso> and - <seealso - marker="#CRLEntryExt">CRL Entry Extensions</seealso>. +<p><c>id_extensions()</c> + <seealso marker="#StdCertExt">Standard Certificate Extensions</seealso>, + <seealso marker="#PrivIntExt">Private Internet Extensions</seealso>, + <seealso marker="#CRLCertExt">CRL Extensions</seealso> and + <seealso marker="#CRLEntryExt">CRL Entry Extensions</seealso>. </p> </section> @@ -368,9 +371,8 @@ marker="#StdCertExt">Standard Certificate Extensions</seealso>, decipherOnly </c></p> - <p><c> id_key_purpose() = ?oid_name_as_erlang_atom</c> for available -oid names see table below. Ex: ?'id-kp-serverAuth'</p> - + <p><c> id_key_purpose()</c></p> + <table> <row> <cell align="left" valign="middle">OID name</cell> 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ö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> |