X509

v0.5.4

X509 v0.5.4 X509.Certificate View Source

Module for issuing and working with X.509 certificates.

The primary data type for this module is the :OTPCertificate record, but the PEM and DER import and export functions also support the :Certificate record type. The former is more convenient to work with, since nested ASN.1 elements are further decoded, and some named elements are identified by atoms rather than OID values.

Link to this section Summary

Types

t()

:OTPCertificate record , as used in Erlang’s :public_key module

Functions

extension(cert, extension_id)

Looks up the value of a specific extension in a certificate

extensions(arg)

Returns the list of extensions included in a certificate

from_der!(der, type \\ :OTPCertificate)

Attempts to parse a certificate in DER (binary) format. Raises in case of failure

from_der(der, type \\ :OTPCertificate)

Attempts to parse a certificate in DER (binary) format

from_pem!(pem, type \\ :OTPCertificate)

Attempts to parse a certificate in PEM format. Raises in case of failure

from_pem(pem, type \\ :OTPCertificate)

Attempts to parse a certificate in PEM format

issuer(arg)

Returns the Issuer field of a certificate

issuer(cert, attr_type)

Returns attribute values of the Issuer field of a certificate

new(public_key, subject_rdn, issuer, issuer_key, opts \\ [])

Issues a new certificate

public_key(arg)

Returns the public key embedded in a certificate

self_signed(private_key, subject_rdn, opts \\ [])

Generates a new self-signed certificate

serial(arg)

Returns the serial number of the certificate

subject(arg)

Returns the Subject field of a certificate

subject(cert, attr_type)

Returns attribute values of the Subject field of a certificate

to_der(certificate)

Converts a certificate to DER (binary) format

to_pem(certificate)

Converts a certificate to PEM format

validity(arg)

Returns the Validity of a certificate

version(arg)

Returns the Version field of a certificate

Link to this section Types

Link to this type t() View Source 
t() :: X509.ASN1.record(:otp_certificate)

:OTPCertificate record , as used in Erlang’s :public_key module

Link to this section Functions

Link to this function extension(cert, extension_id) View Source 
extension(t(), X509.Certificate.Extension.extension_id() | :public_key.oid()) ::
  X509.Certificate.Extension.t() | nil

Looks up the value of a specific extension in a certificate.

The desired extension can be specified as an atom or an OID value. Returns nil if the specified extension is not present in the certificate.

Link to this function extensions(arg) View Source 
extensions(t()) :: [X509.Certificate.Extension.t()]

Returns the list of extensions included in a certificate.

Link to this function from_der!(der, type \\ :OTPCertificate) View Source 
from_der!(binary(), OTPCertificate | Certificate) :: t() | no_return()

Attempts to parse a certificate in DER (binary) format. Raises in case of failure.

The optional second parameter specifies the record type to be returned: :OTPCertificate (default) or :Certificate.

Link to this function from_der(der, type \\ :OTPCertificate) View Source 
from_der(binary(), :OTPCertificate | :Certificate) ::
  {:ok, t()} | {:error, :malformed}

Attempts to parse a certificate in DER (binary) format.

The optional second parameter specifies the record type to be returned: :OTPCertificate (default) or :Certificate.

Returns an :ok tuple in case of success, or an :error tuple in case of failure. Possible error reasons are:

  • :malformed - the data could not be decoded as a certificate
Link to this function from_pem!(pem, type \\ :OTPCertificate) View Source 
from_pem!(String.t(), :OTPCertificate | :Certificate) :: t() | no_return()

Attempts to parse a certificate in PEM format. Raises in case of failure.

Processes the first PEM entry of type CERTIFICATE found in the input. The optional second parameter specifies the record type to be returned: :OTPCertificate (default) or :Certificate.

Link to this function from_pem(pem, type \\ :OTPCertificate) View Source 
from_pem(String.t(), :OTPCertificate | :Certificate) ::
  {:ok, t()} | {:error, :malformed | :not_found}

Attempts to parse a certificate in PEM format.

Processes the first PEM entry of type CERTIFICATE found in the input. The optional second parameter specifies the record type to be returned: :OTPCertificate (default) or :Certificate.

Returns an :ok tuple in case of success, or an :error tuple in case of failure. Possible error reasons are:

  • :not_found - no PEM entry of type CERTIFICATE was found
  • :malformed - the entry could not be decoded as a certificate
Link to this function issuer(arg) View Source 
issuer(t()) :: X509.RDNSequence.t()

Returns the Issuer field of a certificate.

Link to this function issuer(cert, attr_type) View Source 
issuer(t(), binary() | :public_key.oid()) :: [String.t()]

Returns attribute values of the Issuer field of a certificate.

See also X509.RDNSequence.get_attr/2.

Link to this function new(public_key, subject_rdn, issuer, issuer_key, opts \\ []) View Source 
new(
  X509.PublicKey.t(),
  String.t() | X509.RDNSequence.t(),
  t(),
  X509.PrivateKey.t(),
  Keyword.t()
) :: t()

Issues a new certificate.

The public key can be an RSA key or an EC key (which results in an ECDSA certificate).

The Subject can be specified as a string, to be parsed by X509.RDNSequence.new/1, or a custom RDN sequence tuple.

The next parameters are the issuing certificate and the associated private key (RSA or EC). The Issuer field of the new certificate is taken from the issuing certificate’s Subject.

Options:

  • :template - an X509.Certificate.Template struct, or an atom selecting a built-in template (default: :server)
  • :hash - the hashing algorithm to use when signing the certificate (default: from template)
  • :serial - the certificate’s serial number (an integer >0), {:random, n} to generate an n-byte random value, or nil. (default: from template)
  • :validity - an integer specifying the certificate’s validity in days, or an X509.Certificate.Validity record defining the ‘not before’ and ‘not after’ timestamps (default: from template)
  • :extensions - a keyword list of extension names and values, to be merged with the extensions defined in the template; refer to the X509.Certificate.Template documentation for details
Link to this function public_key(arg) View Source 
public_key(t()) :: X509.PublicKey.t()

Returns the public key embedded in a certificate.

Link to this function self_signed(private_key, subject_rdn, opts \\ []) View Source 
self_signed(X509.PrivateKey.t(), String.t() | X509.RDNSequence.t(), Keyword.t()) ::
  t()

Generates a new self-signed certificate.

The private key is used both to sign and to extract the public key to be embedded in the certificate. It can be an RSA key or an EC key (which results in an ECDSA certificate).

The Subject can be specified as a string, to be parsed by X509.RDNSequence.new/1, or a custom RDN sequence tuple. The same value is used in the Issuer field as well.

Options:

  • :template - an X509.Certificate.Template struct, or an atom selecting a built-in template (default: :server)
  • :hash - the hashing algorithm to use when signing the certificate (default: from template)
  • :serial - the certificate’s serial number (default: from template, where it will typically be set to nil, resulting in a random value)
  • :validity - an integer specifying the certificate’s validity in days, or an X509.Certificate.Validity record defining the ‘not before’ and ‘not after’ timestamps (default: from template)
  • :extensions - a keyword list of extension names and values, to be merged with the extensions defined in the template; refer to the X509.Certificate.Template documentation for details
Link to this function serial(arg) View Source 
serial(t()) :: non_neg_integer()

Returns the serial number of the certificate.

Link to this function subject(arg) View Source 
subject(t()) :: X509.RDNSequence.t()

Returns the Subject field of a certificate.

Link to this function subject(cert, attr_type) View Source 
subject(t(), binary() | :public_key.oid()) :: [String.t()]

Returns attribute values of the Subject field of a certificate.

See also X509.RDNSequence.get_attr/2.

Link to this function to_der(certificate) View Source 
to_der(t()) :: binary()

Converts a certificate to DER (binary) format.

Link to this function to_pem(certificate) View Source 
to_pem(t()) :: String.t()

Converts a certificate to PEM format.

Link to this function validity(arg) View Source 
validity(t()) :: X509.Certificate.Validity.t()

Returns the Validity of a certificate.

Link to this function version(arg) View Source 
version(t()) :: atom()

Returns the Version field of a certificate.

Returns the X.509 certificate version as an atom, e.g. :v3.