Skip to content

Commit

Permalink
Cleaned up docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@dgud
dgud authored and Erlang/OTP committed Dec 10, 2009
1 parent 9855ed8 commit 8ac3190
Show file tree
Hide file tree
Showing 6 changed files with 45 additions and 357 deletions.
34 changes: 18 additions & 16 deletions lib/public_key/doc/src/cert_records.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
14 changes: 7 additions & 7 deletions lib/ssl/doc/src/create_certs.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,25 +98,25 @@
<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>
<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>
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.
Expand Down
23 changes: 5 additions & 18 deletions lib/ssl/doc/src/new_ssl.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
213 changes: 9 additions & 204 deletions lib/ssl/doc/src/pkix_certs.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down
Loading

0 comments on commit 8ac3190

Please sign in to comment.