public_key

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

• 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

Use the following include directive to get access to the records and constant macros described here and in the User's Guide.

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

Data Types

boolean() = true | false

string() = [bytes()]

der_encoded() = binary()

pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'| 'RSAPublicKey' |
    'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' | 'SubjectPublicKeyInfo' |
    'PrivateKeyInfo' | 'CertificationRequest'

pem_entry () = {pki_asn1_type(), binary(), %% DER or encrypted DER
          not_encrypted | cipher_info()} 

cipher_info()  =  {"RC2-CBC | "DES-CBC" | "DES-EDE3-CBC", crypto:rand_bytes(8)} |
    'PBES2-params'} 

rsa_public_key()  = #'RSAPublicKey'{}

rsa_private_key() = #'RSAPrivateKey'{} 

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

dsa_private_key() = #'DSAPrivateKey'{}

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

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

 rsa_digest_type()  = 'md5' | 'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512' 

 dss_digest_type()  = 'sha' 

 crl_reason()  = unspecified | keyCompromise | cACompromise | affiliationChanged | superseded | cessationOfOperation | certificateHold | privilegeWithdrawn |  aACompromise
    

 ssh_file()  = openssh_public_key | rfc4716_public_key |
    known_hosts | auth_keys 

Types:

Public key decryption using the private key.

Types:

Public key decryption using the public key.

Types:

Decodes a public key ASN.1 DER encoded entity.

Types:

Encodes a public key entity with ASN.1 DER encoding.

Types:

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

Types:

Creates a PEM binary

Types:

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().

Types:

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

Types:

Public key encryption using the private key.

Types:

Public key encryption using the public key.

Types:

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.

Types:

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.

Types:

Checks if IssuerCert issued Cert

Types:

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

Types:

Checks if a Certificate is self signed.

Types:

Returns the issuer id.

Types:

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

Types:

Performs a basic path validation according to RFC 5280. However CRL validation is done separately by pkix_crls_validate/3 and should be called from the supplied verify_fun

Available options are:

{verify_fun, fun()}

The fun should be defined as:

fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} |
	                                     {extension, #'Extension'{}},
    InitialUserState :: term()) ->
	{valid, UserState :: term()} | {valid_peer, UserState :: term()} |
	{fail, Reason :: term()} | {unknown, UserState :: term()}.
	  

If the verify callback fun returns {fail, Reason}, the verification process is immediately stopped. If the verify callback fun returns {valid, UserState}, the verification process is continued, this can be used to accept specific path validation errors such as selfsigned_peer as well as verifying application specific extensions. If called with an extension unknown to the user application the return value {unknown, UserState} should be used.

{max_path_length, integer()}

The max_path_length is the maximum number of non-self-issued intermediate certificates that may follow the peer certificate in a valid certification path. So if max_path_length is 0 the PEER must be signed by the trusted ROOT-CA directly, if 1 the path can be PEER, CA, ROOT-CA, if it is 2 PEER, CA, CA, ROOT-CA and so on.

Types:

Performs CRL validation. It is intended to be called from the verify fun of pkix_path_validation/3

Available options are:

{update_crl, fun()}

The fun has the following type spec:

 fun(#'DistributionPoint'{}, #'CertificateList'{}) -> #'CertificateList'{}

The fun should use the information in the distribution point to acesses the lates possible version of the CRL. If this fun is not specified public_key will use the default implementation:

 fun(_DP, CRL) -> CRL end

Types:

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

Types:

Verify PKIX x.509 certificate signature.

Types:

Creates a digital signature.

Types:

Decodes a ssh file-binary. In the case of know_hosts or auth_keys the binary may include one or more lines of the file. Returns a list of public keys and their attributes, possible attribute values depends on the file type represented by the binary.

rfc4716 attributes - see RFC 4716

{headers, [{string(), utf8_string()}]}

auth_key attributes - see man sshd

{comment, string()}

{options, [string()]}

{bits, integer()} - In ssh version 1 files

known_host attributes - see man sshd

{hostnames, [string()]}

{comment, string()}

{bits, integer()} - In ssh version 1 files

Types:

Encodes a list of ssh file entries (public keys and attributes) to a binary. Possible attributes depends on the file type, see ssh_decode/2

Types:

Verifies a digital signature