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 and asn1 applications, the latter since R16 (hopefully the runtime dependency on asn1 will be removed again in the future).
• Supports RFC 5280 - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
• Supports PKCS-1 - RSA Cryptography Standard
• Supports DSS- Digital Signature Standard (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

oid() - Object Identifier, a tuple of integers as generated by the ASN1 compiler.

boolean() = true | false

string() = [bytes()]

der_encoded() = binary()

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

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) | {#'PBEParameter{}, digest_type()} |#'PBES2-params'{}}

public_key()  = rsa_public_key() | dsa_public_key() | ec_public_key()

private_key() = rsa_private_key() | dsa_private_key() | ec_private_key()

rsa_public_key()  = #'RSAPublicKey'{}

rsa_private_key() = #'RSAPrivateKey'{}

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

dsa_private_key() = #'DSAPrivateKey'{}

ec_public_key()   = {#'ECPoint'{}, #'EcpkParameters'{} |
    {namedCurve, oid()}}

ec_private_key()  = #'ECPrivateKey'{}

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

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

digest_type() - Union of below digest types

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

dss_digest_type()   = 'sha'

ecdsa_digest_type() = 'sha'| 'sha224' | 'sha256' | 'sha384' | 'sha512'

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

issuer_name() = {rdnSequence,[#'AttributeTypeAndValue'{}]} 

ssh_file()  = openssh_public_key | rfc4716_public_key | known_hosts |
    auth_keys

Types:

Compute shared secret

Types:

Public key decryption using the private key. See also crypto:private_decrypt/4

Types:

Public key decryption using the public key. See also crypto:public_decrypt/4

Types:

Decodes a public key ASN.1 DER encoded entity.

Types:

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

Types:

Generates a new keypair

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. See also crypto:private_encrypt/4

Types:

Public key encryption using the public key. See also crypto:public_encrypt/4

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() | {revoked, 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.

Possible reasons for a bad certificate are:

cert_expired

The certificate is no longer valid as its expiration date has passed.

invalid_issuer

The certificate issuer name does not match the name of the issuer certificate in the chain.

invalid_signature

The certificate was not signed by its issuer certificate in the chain.

name_not_permitted

Invalid Subject Alternative Name extension.

missing_basic_constraint

Certificate, required to have the basic constraints extension, does not have a basic constraints extension.

invalid_key_usage

Certificate key is used in an invalid way according to the key usage extension.

{revoked, crl_reason()}

Certificate has been revoked.

atom()

Application specific error reason that should be checked by the verify_fun

Types:

Returns the issuer of the CRL.

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

{issuer_fun, fun()}

The fun has the following type spec:

fun(#'DistributionPoint'{}, #'CertificateList'{},
    {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) ->
	{ok, #'OTPCertificate'{}, [der_encoded]}

The fun should return the root certificate and certificate chain that has signed the CRL.

 fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}

Types:

Verify that Cert is the CRL signer.

Types:

Creates a distribution point for CRLs issued by the same issuer as Cert. Can be used as input to pkix_crls_validate/3

Types:

Extracts distribution points from the certificates extensions.

Types:

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

Types:

Translates signature algorithm oid to erlang digest and signature types.

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