From 228aa99db473dc2145c8f55819e972f5dc6bb501 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Fri, 11 Jan 2013 15:04:03 +0100 Subject: public_key: Enhance documentation --- lib/public_key/doc/src/cert_records.xml | 25 +++++++------- lib/public_key/doc/src/introduction.xml | 20 ++++++----- lib/public_key/doc/src/part.xml | 8 +++-- lib/public_key/doc/src/public_key.xml | 49 +++++++++++++++++++-------- lib/public_key/doc/src/public_key_records.xml | 12 +++---- lib/public_key/doc/src/using_public_key.xml | 6 ++-- 6 files changed, 71 insertions(+), 49 deletions(-) (limited to 'lib/public_key/doc') diff --git a/lib/public_key/doc/src/cert_records.xml b/lib/public_key/doc/src/cert_records.xml index 6d3d4b3107..f01f7dbaf5 100644 --- a/lib/public_key/doc/src/cert_records.xml +++ b/lib/public_key/doc/src/cert_records.xml @@ -5,7 +5,7 @@
2008 - 2012 + 2013 Ericsson AB, All Rights Reserved @@ -34,12 +34,11 @@ cert_records.xml
-

This chapter briefly describes erlang records derived from asn1 - specifications used to handle X509 certificates. The intent is to - describe the data types and not to specify the meaning of each +

This chapter briefly describes erlang records derived from ASN1 + specifications used to handle X509 certificates and CertificationRequest. + The intent is to describe the data types and not to specify the meaning of each component for this we refer you to RFC 5280. Also - descirbed is

CertificationRequest

that is defined by + href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280 and PKCS-10.

@@ -48,7 +47,7 @@ -include_lib("public_key/include/public_key.hrl"). -

The used asn1 specifications are available asn1 subdirectory +

The used ASN1 specifications are available asn1 subdirectory of the application public_key.

@@ -62,7 +61,7 @@ follows here.

oid() - a tuple of integers - as generated by the asn1 compiler.

+ as generated by the ASN1 compiler.

time() = uct_time() | general_time()

@@ -101,7 +100,7 @@ #'Certificate'{ tbsCertificate, % #'TBSCertificate'{} signatureAlgorithm, % #'AlgorithmIdentifier'{} - signature % {0, binary()} - asn1 compact bitstring + signature % {0, binary()} - ASN1 compact bitstring }. #'TBSCertificate'{ @@ -127,7 +126,7 @@ #'OTPCertificate'{ tbsCertificate, % #'OTPTBSCertificate'{} signatureAlgorithm, % #'SignatureAlgorithm' - signature % {0, binary()} - asn1 compact bitstring + signature % {0, binary()} - ASN1 compact bitstring }. #'OTPTBSCertificate'{ @@ -531,7 +530,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

#'CertificateList'{ tbsCertList, % #'TBSCertList{} signatureAlgorithm, % #'AlgorithmIdentifier'{} - signature % {0, binary()} - asn1 compact bitstring + signature % {0, binary()} - ASN1 compact bitstring }). #'TBSCertList'{ @@ -643,7 +642,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

#'CertificationRequest'{ certificationRequestInfo #'CertificationRequestInfo'{}, signatureAlgorithm #'CertificationRequest_signatureAlgorithm'{}}. - signature {0, binary()} - asn1 compact bitstring + signature {0, binary()} - ASN1 compact bitstring } #'CertificationRequestInfo'{ @@ -655,7 +654,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

#'CertificationRequestInfo_subjectPKInfo'{ algorithm #'CertificationRequestInfo_subjectPKInfo_algorithm'{} - subjectPublicKey {0, binary()} - asn1 compact bitstring + subjectPublicKey {0, binary()} - ASN1 compact bitstring } #'CertificationRequestInfo_subjectPKInfo_algorithm'{ diff --git a/lib/public_key/doc/src/introduction.xml b/lib/public_key/doc/src/introduction.xml index e0dd5603f7..4b59cc2245 100644 --- a/lib/public_key/doc/src/introduction.xml +++ b/lib/public_key/doc/src/introduction.xml @@ -5,7 +5,7 @@
2008 - 2012 + 2013 Ericsson AB, All Rights Reserved @@ -36,11 +36,13 @@
Purpose -

This application provides an API to public key infrastructure - from RFC - 5280 (X.509 certificates) and public key formats defined by - the - PKCS-standard

+

public_key deals with public key related file formats, digital + signatures and + X-509 certificates. It is a library application that + provides encode/decode, sign/verify, encrypt/decrypt and similar + functionality, it does not read or write files it expects or returns + file contents or partial file contents as binaries. +

@@ -51,9 +53,9 @@
Performance tips -

The public_key decode and encode functions will try to use the nifs - which are in the asn1 compilers runtime modules if they can be found. - So for the best performance you want to have the asn1 application in the +

The public_key decode and encode functions will try to use the NIFs + which are in the ASN1 compilers runtime modules if they can be found. + So for the best performance you want to have the ASN1 application in the path of your system.

diff --git a/lib/public_key/doc/src/part.xml b/lib/public_key/doc/src/part.xml index ea3123b5bd..08fa4eec58 100644 --- a/lib/public_key/doc/src/part.xml +++ b/lib/public_key/doc/src/part.xml @@ -5,7 +5,7 @@
2008 - 2011 + 2013 Ericsson AB, All Rights Reserved @@ -32,8 +32,10 @@

This application provides an API to public key infrastructure - from RFC 3280 (X.509 certificates) and some public key formats defined - by the PKCS-standard.

+ from RFC + 5280 (X.509 certificates) and public key formats defined by + the + PKCS-standard

 diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index 93ba45e457..66c9217579 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -33,11 +33,29 @@ public_key API module for public key infrastructure. -

This module provides functions to handle public key infrastructure - from RFC 5280- X.509 certificates and some parts of the PKCS-standard. +

This module provides functions to handle public key infrastructure. It can + encode/decode different file formats (PEM, openssh), sign and verify digital signatures and vlidate + certificate paths and certificate revokation lists.

+
+ public_key + + + public_key requires the crypto application. + + Supports RFC 5280 - + Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile + Supports PKCS-1 - RSA Cryptography Standard + Supports DSA- Digital Signature Algorithm + Supports PKCS-3 - Diffie-Hellman Key Agreement Standard + Supports PKCS-5 - Password-Based Cryptography Standard + Supports PKCS-8 - Private-Key Information Syntax Standard + Supports PKCS-10 - Certification Request Syntax Standard + +
+
COMMON DATA TYPES @@ -156,7 +174,7 @@ der_decode(Asn1type, Der) -> term() - Decodes a public key asn1 der encoded entity. + Decodes a public key ASN.1 DER encoded entity. Asn1Type = atom() ASN.1 type present in the public_key applications @@ -164,7 +182,7 @@ Der = der_encoded() -

Decodes a public key ASN.1 der encoded entity.

+

Decodes a public key ASN.1 DER encoded entity.

 @@ -186,14 +204,14 @@ pem_decode(PemBin) -> [pem_entry()] Decode PEM binary data and return - entries as ASN.1 der encoded entities. + entries as ASN.1 DER encoded entities. PemBin = binary() Example {ok, PemBin} = file:read_file("cert.pem").

Decode PEM binary data and return - entries as ASN.1 der encoded entities.

+ entries as ASN.1 DER encoded entities.

 @@ -217,8 +235,8 @@ Password = string() -

Decodes a pem entry. pem_decode/1 returns a list of pem - entries. Note that if the pem entry is of type +

Decodes a PEM entry. pem_decode/1 returns a list of PEM + entries. Note that if the PEM entry is of type 'SubjectPublickeyInfo' it will be further decoded to an rsa_public_key() or dsa_public_key().

 @@ -227,7 +245,7 @@ pem_entry_encode(Asn1Type, Entity) -> pem_entry() pem_entry_encode(Asn1Type, Entity, {CipherInfo, Password}) -> pem_entry() - Creates a pem entry that can be fed to pem_encode/1. + Creates a PEM entry that can be fed to pem_encode/1. Asn1Type = pki_asn1_type() Entity = term() @@ -241,7 +259,7 @@ Password = string() -

Creates a pem entry that can be feed to pem_encode/1.

+

Creates a PEM entry that can be feed to pem_encode/1.

 @@ -271,12 +289,12 @@ pkix_decode_cert(Cert, otp|plain) -> #'Certificate'{} | #'OTPCertificate'{} - Decodes an ASN.1 der encoded pkix x509 certificate. + Decodes an ASN.1 DER encoded PKIX x509 certificate. Cert = der_encoded() -

Decodes an ASN.1 der encoded pkix certificate. The otp option +

Decodes an ASN.1 DER encoded PKIX certificate. The otp option will use the customized ASN.1 specification OTP-PKIX.asn1 for decoding and also recursively decode most of the standard parts.

@@ -285,14 +303,15 @@ pkix_encode(Asn1Type, Entity, otp | plain) -> der_encoded() - Der encodes a pkix x509 certificate or part of such a + DER encodes a PKIX x509 certificate or part of such a certificate. Asn1Type = atom() The ASN.1 type can be 'Certificate', 'OTPCertificate' or a subtype of either . + Entity = #'Certificate'{} | #'OTPCertificate'{} | a valid subtype -

Der encodes a pkix x509 certificate or part of such a +

DER encodes a PKIX x509 certificate or part of such a certificate. This function must be used for encoding certificates or parts of certificates that are decoded/created in the otp format, whereas for the plain format this function will directly call der_encode/2.

@@ -480,7 +499,7 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | Key = rsa_public_key() | dsa_public_key() -

Verify pkix x.509 certificate signature.

+

Verify PKIX x.509 certificate signature.

 diff --git a/lib/public_key/doc/src/public_key_records.xml b/lib/public_key/doc/src/public_key_records.xml index bb90290266..e39ad0ec64 100644 --- a/lib/public_key/doc/src/public_key_records.xml +++ b/lib/public_key/doc/src/public_key_records.xml @@ -1,11 +1,11 @@ - +
2008 - 2011 + 2013 Ericsson AB, All Rights Reserved @@ -34,7 +34,7 @@ public_key_records.xml
-

This chapter briefly describes Erlang records derived from asn1 +

This chapter briefly describes Erlang records derived from ASN1 specifications used to handle public and private keys. The intent is to describe the data types and not to specify the meaning of each component for this we refer you to the relevant standards and RFCs.

@@ -67,9 +67,9 @@ }. #'OtherPrimeInfo'{ - prime, % integer() - exponent, % integer() - coefficient % integer() + prime, % integer() + exponent, % integer() + coefficient % integer() }. diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml index 1224b57aed..5d9f1536d9 100644 --- a/lib/public_key/doc/src/using_public_key.xml +++ b/lib/public_key/doc/src/using_public_key.xml @@ -4,7 +4,7 @@
- 20112011 + 20112013 Ericsson AB. All Rights Reserved. @@ -40,7 +40,7 @@
PEM files -

Pulic key data (keys, certificates etc) may be stored in PEM format. PEM files +

Public key data (keys, certificates etc) may be stored in PEM format. PEM files comes from the Private Enhanced Mail Internet standard and has a structure that looks like this:

@@ -63,7 +63,7 @@ 1> {ok, PemBin} = file:read_file("dsa.pem"). {ok,<<"-----BEGIN DSA PRIVATE KEY-----\nMIIBuw"...>>} -

This PEM file only has one entry a private DSA key.

+

This PEM file only has one entry, a private DSA key.

2> [DSAEntry] = public_key:pem_decode(PemBin). [{'DSAPrivateKey',<<48,130,1,187,2,1,0,2,129,129,0,183, 179,230,217,37,99,144,157,21,228,204, -- cgit v1.2.3