From 8ac319031230b354dcea105d94ef2a232a9d7afe Mon Sep 17 00:00:00 2001 From: Dan Gudmundsson Date: Thu, 10 Dec 2009 10:09:12 +0000 Subject: Cleaned up docs --- lib/public_key/doc/src/cert_records.xml | 34 ++--- lib/ssl/doc/src/create_certs.xml | 14 +-- lib/ssl/doc/src/new_ssl.xml | 23 +--- lib/ssl/doc/src/pkix_certs.xml | 213 ++------------------------------ lib/ssl/doc/src/remember.xml | 83 ------------- lib/ssl/doc/src/ssl.xml | 35 +----- 6 files changed, 45 insertions(+), 357 deletions(-) delete mode 100644 lib/ssl/doc/src/remember.xml (limited to 'lib') 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 @@

Use the following include directive to get access to the - records and constant macros described in the following sections.

+ records and constant macros (OIDs) described in the following sections.

-include_lib("public_key/include/public_key.hrl"). +

The used specification is available in OTP-PKIX.asn1, + which is an amelioration of + the PKIX1Explicit88.asn1, PKIX1Implicit88.asn1 + and PKIX1Algorithms88.asn1 modules. + You find all these modules in the asn1 subdirectory + of the application public_key. +

+
Common Data Types @@ -148,8 +156,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

}. -

id_attributes() = ?oid_name_as_erlang_atom -for available oid names see table below. Ex: ?'id-at-name'

+

id_attributes()

OID name @@ -231,8 +238,7 @@ for available oid names see table below. Ex: ?'id-at-name'

}. -

id_public_key_algorithm() = ?oid_name_as_erlang_atom for available -oid names see table below. Ex: ?'id-dsa'

+

id_public_key_algorithm()

OID name @@ -264,14 +270,11 @@ oid names see table below. Ex: ?'id-dsa'

}. -

id_extensions() = ?oid_name_as_erlang_atom for -available oid names see tables. Ex: ?'id-ce-authorityKeyIdentifier'Standard Certificate Extensions, - Private Internet Extensions, CRL Extensions and - CRL Entry Extensions. +

id_extensions() + Standard Certificate Extensions, + Private Internet Extensions, + CRL Extensions and + CRL Entry Extensions.

@@ -368,9 +371,8 @@ marker="#StdCertExt">Standard Certificate Extensions, decipherOnly

-

id_key_purpose() = ?oid_name_as_erlang_atom for available -oid names see table below. Ex: ?'id-kp-serverAuth'

- +

id_key_purpose()

+
OID name 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 @@ Creating the Erlang root CA

The Erlang root CA is created with the command

-\011openssl req -new -x509 -config /some/path/req.cnf \\ -\011 -keyout /some/path/key.pem -out /some/path/cert.pem + openssl req -new -x509 -config /some/path/req.cnf \\ + -keyout /some/path/key.pem -out /some/path/cert.pem

where the option -new indicates that we want to create a new certificate request and the option -x509 implies that a self-signed certificate is created. -

+

@@ -111,12 +111,12 @@

The OTP CA is created by first creating a certificate request with the command

-\011openssl req -new -config /some/path/req.cnf \\ -\011 -keyout /some/path/key.pem -out /some/path/req.pem + openssl req -new -config /some/path/req.cnf \\ + -keyout /some/path/key.pem -out /some/path/req.pem

and the ask the Erlang CA to sign it:

-\011openssl ca -batch -notext -config /some/path/req.cnf \\ -\011 -extensions ca_cert -in /some/path/req.pem -out /some/path/cert.pem + openssl ca -batch -notext -config /some/path/req.cnf \\ + -extensions ca_cert -in /some/path/req.pem -out /some/path/cert.pem

where the option -extensions 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 - peercert(Socket) -> - peercert(Socket, Opts) -> {ok, Cert} | {error, Reason} + peercert(Socket) -> {ok, Cert} | {error, Reason} Return the peer certificate. Socket = sslsocket() - Opts = [] | [otp] | [plain] - Cert = term() + Cert = binary() Subject = term() -

peercert(Cert) is equivalent to peercert(Cert, []). -

-

The form of the returned certificate depends on the - options. -

-

If the options list is empty the certificate is returned as - a DER encoded binary. -

-

The option otp or plain 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. -

+

The peer certificate is returned as a DER encoded binary. + The certificate can be decoded with public_key:pkix_decode_cert/2. +

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 @@

Certificates were originally defined by ITU (CCITT) and the latest definitions are described in , but those definitions are (as always) not working. -

+

Working certificate definitions for the Internet Community are found - in the the PKIX RFCs and . + in the the PKIX RFCs and . The parsing of certificates in the Erlang/OTP SSL application is based on those RFCS. -

+

Certificates are defined in terms of ASN.1 (). For an introduction to ASN.1 see ASN.1 Information Site. -

+

PKIX Certificates -

Here we base the PKIX certificate definitions in RFCs and . We however present the - definitions according to SSL-PKIX.asn1 module, - which is an amelioration of the PKIX1Explicit88.asn1, - PKIX1Implicit88.asn1, and PKIX1Algorithms88.asn1 - modules. You find all these modules in the pkix subdirectory - of SSL. -

-

The Erlang terms that are returned by the functions - ssl:peercert/1/2, ssl_pkix:decode_cert/1/2, and - ssl_pkix:decode_cert_file/1/2 when the option ssl - is used in those functions, correspond the ASN.1 structures - described in the sequel. -

- -
- Certificate and TBSCertificate - -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 } - -

The meaning of the fields version, serialNumber, - and validity are quite obvious given the type definitions - above, so we do not go further into their details. -

-

The signatureAlgorithm field of Certificate and - the signature field of TBSCertificate contain - the name and parameters of the algorithm used for signing the - certificate. The values of these two fields must be equal. -

-

The signature field of Certificate contains the - value of the signature that the issuer computed by using the - prescribed algorithm. -

-

The and subject]]> fields can contain many - different types av data, and is therefore considered in a - separate section. The same holds for the extensions - field. - The issuerUniqueID and the subjectUniqueID fields - are not considered further.

-
- -
- TBSCertificate issuer and subject -

- -
- -
- TBSCertificate extensions -

The extensions field of a TBScertificate is a - sequence of type Extension, defined as follows,

- -Extension ::= SEQUENCE { - extnID OBJECT IDENTIFIER, - critical BOOLEAN DEFAULT FALSE, - extnValue ANY } -

Each extension has a unique object identifier. An extension - with a critical value set to TRUEmust - be recognised by the reader of a certificate, or else the - certificate must be rejected. -

-

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 - authorityInfoAccess and subjectInfoAccess, which - are internet extensions. -

-

Depending on the object identifier the extnValue is - parsed into an appropriate welldefined structure. -

-

The following table shows the purpose of each extension, but - does not specify the structure. To see the structure consult - the PKIX1Implicit88.asn1 module. -

-
- - authorityKeyIdentifier - Used by to identify a certificate signed that has multiple signing keys. - - - subjectKeyIdentifier - Used to identify certificates that contain a public key. Must appear i CA certificates. - - - keyUsage - Defines the purpose of the certificate. Can be one or several ofdigitalSignature, nonRepudiation,keyEncipherment, dataEncipherment,keyAgreement, keyCertSign, cRLSign,encipherOnly, decipherOnly. - - - privateKeyUsagePeriod - Allows certificate issuer to provide a private key usage period to be short than the certificate usage period. - - - certificatePolicies - Contains one or more policy information terms indicating the policies under which the certificate has been issued. - - - policyMappings - Used i CA certificates. - - - subjectAltName - Allows additional identities to be bound the the subject. - - - issuerAltName - Allows additional identities to be bound the the issuer. - - - subjectDirectoryAttributes - Conveys identity attributes of the subject. - - - basicConstraints - Tells if the certificate holder is a CA or not. - - - nameConstraints - Used in CA certificates. - - - policyConstraints - Used in CA certificates. - - - extKeyUsage - Indicates for which purposed the public key may be used. - - - cRLDistributionPoints - Indicates how CRL (Certificate Revokation List) information is obtained. - - - inhibitAnyPolicy - Used i CA certificates. - - - freshestCRL - For CRLs. - - - authorityInfoAccess - How to access CA information of the issuer of the certificate. - - - subjectInfoAccess - How to access CA information of the subject of the certificate. - - PKIX Extensions -
-
+

Certificate handling is now handled by the public_key application.

+

+ DER encoded certificates returned by ssl:peercert/1 can for example + be decoded by the public_key:pkix_decode_cert/2 function. +

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 @@ - - - - -
- - 20032009 - Ericsson AB. 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. - - - - PKIX Certificates - UAB/F/P Peter Högfeldt - - 2003-06-09 - A - pkix_certs.sgml -
- -
- Introduction to Certificates -

Outline:

- - 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. - - private keys - password protection - key generation - file - formats. - - ssl_pkix and alternate decodings. - - Attribute Certificates (not used by SSL). - - Certificate requests - certificate authorities - signing of - certificates - certificate revocation lists. - - standards: ASN.1, X.509, X.520, PKIX, PKCS, PEM. - - incompatibilities between standards (X.509-1997 vs old) - the - ASN.1 problem of ANY, BIT STRING and OCTET STRING - the module - ssl_pkix. - - test suites: NIST - - Warnings: *creation* of trusted certificate (OpenSSL). - - Erlang SSL and certificates - - The need for seeding the random generator. See also John - S. Denker: High-Entropy Symbol Generator - (http://www.monmouth.com/~jsd). - - links to standards and documents. Books (Rescorla). - - ASN.1 crash course. - - Nagel algorithm. - - -

For an introduction to ASN.1 see ASN.1 Information Site. -

-
- - - 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 @@ - peercert(Socket) -> - peercert(Socket, Opts) -> {ok, Cert} | {ok, Subject} | {error, Reason} + peercert(Socket) -> {ok, Cert} | {error, Reason} Return the peer certificate. Socket = sslsocket() - Opts = [pkix | ssl | subject]() - Cert = term()() + Cert = binary()() Subject = term()() -

peercert(Cert) is equivalent to peercert(Cert, []). -

-

The form of the returned certificate depends on the - options. -

-

If the options list is empty the certificate is returned as - a DER encoded binary. -

-

The options pkix and ssl implies that the - certificate is returned as a parsed ASN.1 structure in the - form of an Erlang term. -

-

The ssl option gives a more elaborate return - structure, with more explicit information. In particular - object identifiers are replaced by atoms. -

-

The options pkix, and ssl are mutually - exclusive. -

-

The option subject implies that only the subject's - distinguished name part of the peer certificate is returned. - It can only be used together with the option pkix or - the option ssl.

+

Returns the DER encoded peer certificate, the certificate can be decoded with + public_key:pkix_decode_cert/2. +

@@ -719,8 +697,7 @@
SEE ALSO -

gen_tcp(3), inet(3) -

+

gen_tcp(3), inet(3) public_key(3)

-- cgit v1.2.3