From 12dfe961aeaf1a826d851361a24519e54d8ef119 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Mon, 5 Jul 2010 17:24:40 +0200 Subject: Revise the public_key API Cleaned up and documented the public_key API to make it useful for general use. --- lib/public_key/doc/src/cert_records.xml | 37 ++- lib/public_key/doc/src/public_key.xml | 500 +++++++++++++++++++------------- 2 files changed, 329 insertions(+), 208 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 8cfe57f670..0d6113acef 100644 --- a/lib/public_key/doc/src/cert_records.xml +++ b/lib/public_key/doc/src/cert_records.xml @@ -1,4 +1,4 @@ - + @@ -37,7 +37,7 @@

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 - component for this we refer you to RFC 3280. + component for this we refer you to RFC 5280.

Use the following include directive to get access to the @@ -45,11 +45,7 @@ -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 +

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

@@ -62,6 +58,9 @@ marker="public_key">public key reference manual or follows here.

+

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

+

time() = uct_time() | general_time()

uct_time() = {utcTime, "YYMMDDHHMMSSZ"}

@@ -119,9 +118,31 @@ algorithm, % oid() parameters % asn1_der_encoded() }. + + + +#'OTPCertificate'{ + tbsCertificate, % #'OTPTBSCertificate'{} + signatureAlgorithm, % #'SignatureAlgorithm' + signature % {0, binary()} - asn1 compact bitstring + }. + +#'OTPTBSCertificate'{ + version, % v1 | v2 | v3 + serialNumber, % integer() + signature, % #'SignatureAlgorithm' + issuer, % {rdnSequence, [#AttributeTypeAndValue'{}]} + validity, % #'Validity'{} + subject, % {rdnSequence, [#AttributeTypeAndValue'{}]} + subjectPublicKeyInfo, % #'SubjectPublicKeyInfo'{} + issuerUniqueID, % binary() | asn1_novalue + subjectUniqueID, % binary() | asn1_novalue + extensions % [#'Extension'{}] + }. + #'SignatureAlgorithm'{ algorithm, % id_signature_algorithm() - parameters % public_key_params() + parameters % asn1_novalue | #'Dss-Parms'{} }. diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index dc9a96906f..c72719fac4 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -1,4 +1,4 @@ - + @@ -34,11 +34,7 @@ API module for public key infrastructure.

This module provides functions to handle public key infrastructure - from RFC 3280 - X.509 certificates (will later be upgraded to RFC 5280) - and some parts of the PKCS-standard. - Currently this application is mainly used by the new - ssl implementation. The API is yet under construction - and only a few of the functions are currently documented and thereby supported. + from RFC 5280 - X.509 certificates and some parts of the PKCS-standard.

@@ -62,37 +58,37 @@

boolean() = true | false

-

string = [bytes()]

- -

asn1_der_encoded() = binary() | [bytes()]

+

string = [bytes()]

+ +

der_encoded() = binary()

-

der_bin() = binary()

+

decrypt_der() = binary()

-

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

- -

public_key() = rsa_public_key() | dsa_public_key()

+

pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'| + 'DSAPrivateKey' | 'DHParameter'

+

pem_entry () = {pki_asn1_type(), der_encoded() | decrypt_der(), not_encrypted | + {"DES-CBC" | "DES-EDE3-CBC", crypto:rand_bytes(8)}}.

+

rsa_public_key() = #'RSAPublicKey'{}

rsa_private_key() = #'RSAPrivateKey'{}

-

dsa_public_key() = integer()

- -

public_key_params() = dsa_key_params()

- -

dsa_key_params() = #'Dss-Parms'{}

- -

private_key() = rsa_private_key() | dsa_private_key()

+

dsa_public_key() = {integer(), #'Dss-Parms'{}}

rsa_private_key() = #'RSAPrivateKey'{}

dsa_private_key() = #'DSAPrivateKey'{}

+ +

public_crypt_options() = [{rsa_pad, rsa_padding()}].

-

x509_certificate() = "#Certificate{}"

- -

x509_tbs_certificate() = #'TBSCertificate'{}

- +

rsa_padding() = 'rsa_pkcs1_padding' | 'rsa_pkcs1_oaep_padding' + | 'rsa_no_padding'

+ +

rsa_digest_type() = 'md5' | 'sha'

+ +

dss_digest_type() = 'none' | 'sha'

+ @@ -121,197 +117,301 @@ - - - - decode_private_key(KeyInfo) -> - decode_private_key(KeyInfo, Password) -> {ok, PrivateKey} | {error, Reason} - Decodes an asn1 der encoded private key. - - KeyInfo = {KeyType, der_bin(), ChipherInfo} - As returned from pem_to_der/1 for private keys - KeyType = rsa_private_key | dsa_private_key - ChipherInfo = opaque() | no_encryption - ChipherInfo may contain encryption parameters if the private key is password - protected, these are opaque to the user just pass the value returned by pem_to_der/1 - to this function. - Password = string() - Must be specified if CipherInfo =/= no_encryption - PrivateKey = private_key() - Reason = term() - - -

Decodes an asn1 der encoded private key.

- - - + + + - pem_to_der(File) -> {ok, [Entry]} - Reads a PEM file and translates it into its asn1 der - encoded parts. + decrypt_private(CipherText, Key [, Options]) -> binary() + Public key decryption. - File = path() - Password = string() - Entry = {entry_type(), der_bin(), CipherInfo} - ChipherInfo = opaque() | no_encryption - ChipherInfo may contain encryption parameters if the private key is password - protected, these will be handled by the function decode_private_key/2. - entry_type() = cert | cert_req | rsa_private_key | dsa_private_key | - dh_params + CipherText = binary() + Key = rsa_private_key() + Options = public_crypt_options() -

Reads a PEM file and translates it into its asn1 der - encoded parts.

+

Public key decryption using the private key.

+ + + + + decrypt_public(CipherText, Key [, Options]) - > binary() + + + CipherText = binary() + Key = rsa_public_key() + Options = public_crypt_options() + + +

Public key decryption using the public key.

 - - - pkix_decode_cert(Cert, Type) -> {ok, DecodedCert} | {error, Reason} - Decodes an asn1 der encoded pkix certificate. - - Cert = asn1_der_encoded() - Type = plain | otp - DecodeCert = x509_certificate() - When type is specified as otp the asn1 spec OTP-PKIX.asn1 is used to decode known - extensions and enhance the signature field in - #'Certificate'{} and '#TBSCertificate'{}. This is currently used by the new ssl - implementation but not documented and supported for the public_key application. - Reason = term() + + + der_decode(Asn1type, Der) -> term() + Decodes a public key asn1 der encoded entity. + + Asn1Type = atom() - + Asn1 type present in the public_key applications + asn1 specifications. + Der = der_encoded() - -

Decodes an asn1 encoded pkix certificate.

+ +

Decodes a public key asn1 der encoded entity.

 + + + der_encode(Asn1Type, Entity) -> der_encoded() + Encodes a public key entity with asn1 DER encoding. + + Asn1Type = atom() + Asn1 type present in the public_key applications + asn1 specifications. + Entity = term() - The erlang representation of Asn1Type + + +

Encodes a public key entity with asn1 DER encoding.

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

Decode PEM binary data and return + entries as asn1 der encoded entities.

+ + + + + pem_encode(PemEntries) -> binary() + Creates a PEM binary + + PemEntries = [pem_entry()] + + +

Creates a PEM binary

+ + + + + pem_entry_decode(PemEntry [, Password]) -> term() + Decodes a pem entry. + + PemEntry = pem_entry() + Password = string() + + +

Decodes a pem entry. pem_decode/1 returns a list of + pem entries.

+ + + + + pem_entry_encode(Asn1Type, Entity [,{CipherInfo, Password}]) -> pem_entry() + Creates a pem entry that can be feed to pem_encode/1. + + Asn1Type = atom() + Entity = term() + CipherInfo = {"DES-CBC" | "DES-EDE3-CBC", crypto:rand_bytes(8)} + Password = string() + + +

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

+ + + + + encrypt_private(PlainText, Key) -> binary() + Public key encryption using the private key. + + PlainText = binary() + Key = rsa_private_key() + + +

Public key encryption using the private key.

+ + + + + encrypt_public(PlainText, Key) -> binary() + Public key encryption using the public key. + + PlainText = binary() + Key = rsa_public_key() + + +

Public key encryption using the public key.

+ + - - - - - - - - - - - - + + pkix_decode_cert(Cert, otp|plain) -> #'Certificate'{} | #'OTPCertificate'{} + Decodes an asn1 der encoded pkix x509 certificate. + + Cert = der_encoded() + + +

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

+ + - - - - - - - - - - - + + pkix_encode(Asn1Type, Entity, otp | plain) -> der_encoded() + Der encodes a pkix x509 certificate or part of such a + certificate. + + Asn1Type = atom() + The asn1 type can be 'Certificate', 'OTPCertificate' or a subtype of either . + + +

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 on the otp format, whereas for the plain format this + function will directly call der_encode/2.

+ + + + + pkix_is_issuer(Cert, IssuerCert) -> boolean() + Checks if IssuerCert issued Cert + + Cert = der_encode() | #'OTPCertificate'{} + IssuerCert = der_encode() | #'OTPCertificate'{} + + +

Checks if IssuerCert issued Cert

+ + + + + pkix_is_fixed_dh_cert(Cert) -> boolean() + Checks if a Certificate is a fixed Diffie-Hellman Cert. + + Cert = der_encode() | #'OTPCertificate'{} + + +

Checks if a Certificate is a fixed Diffie-Hellman Cert.

+ + + + + pkix_is_self_signed(Cert) -> boolean() + Checks if a Certificate is self signed. + + Cert = der_encode() | #'OTPCertificate'{} + + +

Checks if a Certificate is self signed.

+ + + + + pkix_issuer_id(Cert, IssuedBy) -> {ok, IssuerID} | {error, Reason} + Returns the issuer id. + + Cert = der_encode() | #'OTPCertificate'{} + IssuedBy = self | other + IssuerID = {integer(), {rdnSequence, [#'AttributeTypeAndValue'{}]}} + The issuer id consists of the serial number and the issuers name. + Reason = term() + + +

Returns the issuer id.

+ + - - - - - - - - - - - + + pkix_normalize_name(Issuer) -> Normalized + Normalizes a issuer name so that it can be easily + compared to another issuer name. + + Issuer = {rdnSequence,[#'AttributeTypeAndValue'{}]} + Normalized = {rdnSequence, [#'AttributeTypeAndValue'{}]} + + +

Normalizes a issuer name so that it can be easily + compared to another issuer name.

+ + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + pkix_sign(#'OTPTBSCertificate'{}, Key) -> der_encode() + Signs certificate. + + Key = rsa_public_key() | dsa_public_key() + + +

Signs a 'OTPTBSCertificate'. Returns the corresponding + der encoded certificate.

+ + - - - - - - - - - - - - - - - - - - - - + + pkix_verify(Cert, Key) -> boolean() + Verify pkix x.509 certificate signature. + + Cert = der_encode() + Key = rsa_public_key() | dsa_public_key() + + +

Verify pkix x.509 certificate signature.

+ + - - - - - - - - - - - - - - - + + sign(Msg, DigestType, Key) -> binary() + Create digital signature. + + Msg = binary() + The msg is either the binary "plain text" data to be + signed or in the case that digest type is none + it is the hashed value of "plain text" i.e. the digest. + DigestType = rsa_digest_type() | dsa_digest_type() + Key = rsa_public_key() | dsa_public_key() + + +

Creates a digital signature.

+ + - - - - - - - - - - - - - - - - - - + + verify(Msg, DigestType, Signature, Key) -> boolean() + Verifies a digital signature. + + Msg = binary() + The msg is either the binary "plain text" data + or in the case that digest type is none + it is the hashed value of "plain text" i.e. the digest. + DigestType = rsa_digest_type() | dsa_digest_type() + Signature = binary() + Key = rsa_public_key() | dsa_public_key() + + +

Verifies a digital signature

+ + + -- cgit v1.2.3