View Source X509.Certificate (X509 v0.8.9)

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

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

Returns the list of extensions included in a certificate.

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

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

Attempts to parse a certificate in PEM format.

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

Returns the Issuer field of a certificate.

Returns attribute values of the Issuer field of a certificate.

Returns the public key embedded in a certificate.

Generates a new self-signed certificate.

Returns the serial number of the certificate.

Returns the Subject field of a certificate.

Returns attribute values of the Subject field of a certificate.

Converts a certificate to DER (binary) format.

Converts a certificate to PEM format.

Returns the Validity of a certificate.

Returns the Version field of a certificate.

Link to this section Types

@type 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

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.

@spec 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
@spec 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_der!(der, type \\ :OTPCertificate)

View Source
@spec 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_pem(pem, type \\ :OTPCertificate)

View Source
@spec 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

from_pem!(pem, type \\ :OTPCertificate)

View Source
@spec 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.

@spec issuer(t()) :: X509.RDNSequence.t()

Returns the Issuer field of a certificate.

@spec 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

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

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
@spec 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
@spec 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

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
@spec serial(t()) :: non_neg_integer()

Returns the serial number of the certificate.

@spec subject(t()) :: X509.RDNSequence.t()

Returns the Subject field of a certificate.

Link to this function

subject(cert, attr_type)

View Source
@spec 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.

@spec to_der(t()) :: binary()

Converts a certificate to DER (binary) format.

@spec to_pem(t()) :: String.t()

Converts a certificate to PEM format.

@spec validity(t()) :: X509.Certificate.Validity.t()

Returns the Validity of a certificate.

@spec version(t()) :: atom()

Returns the Version field of a certificate.

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