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/public_key.xml | 500 ++++++++++++++++++++-------------- 1 file changed, 300 insertions(+), 200 deletions(-) (limited to 'lib/public_key/doc/src/public_key.xml') 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