View Source X509.Certificate.Extension (X509 v0.8.7)

Convenience functions for creating :Extension records for use in certificates.

Link to this section Summary

Types

Supported values in the key usage extension

An entry for use in the subject alternate name extension. Strings are mapped to DNSName values, tuples must contain values supported by Erlang's :public_key module

t()

:Extension record, as used in Erlang's :public_key module

Functions

The authority information access extension indicates how to access information and services for the issuer of the certificate in which the extension appears.

The authority key identifier extension provides a means of identifying the public key corresponding to the private key used to sign a certificate.

The basic constraints extension identifies whether the subject of the certificate is a CA and the maximum depth of valid certification paths that include this certificate.

The CRL distribution points extension identifies how CRL information is obtained.

This extension indicates one or more purposes for which the certified public key may be used, in addition to or in place of the basic purposes indicated in the key usage extension. In general, this extension will appear only in end entity certificates.

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

The key usage extension defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate.

The OCSP Nocheck extension indicates that the OCSP client can trust this OCSP responder certificate for the lifetime of the certificate, and no revocation checks are needed.

The subject alternative name extension allows identities to be bound to the subject of the certificate. These identities may be included in addition to or in place of the identity in the subject field of the certificate. Defined options include an Internet electronic mail address, a DNS name, an IP address, and a Uniform Resource Identifier (URI).

The subject key identifier extension provides a means of identifying certificates that contain a particular public key.

Link to this section Types

@type aia_access_method() :: :ocsp | :ca_issuers | :time_stamping | :ca_repository
@type extension_id() ::
  :basic_constraints
  | :key_usage
  | :ext_key_usage
  | :subject_key_identifier
  | :authority_key_identifier
  | :subject_alt_name
  | :crl_distribution_point
  | :authority_information_access
  | :ocsp_nocheck
@type key_usage_value() ::
  :digitalSignature
  | :nonRepudiation
  | :keyEncipherment
  | :dataEncipherment
  | :keyAgreement
  | :keyCertSign
  | :cRLSign
  | :encipherOnly
  | :decipherOnly

Supported values in the key usage extension

@type san_value() :: String.t() | {atom(), charlist()}

An entry for use in the subject alternate name extension. Strings are mapped to DNSName values, tuples must contain values supported by Erlang's :public_key module

@type t() :: X509.ASN1.record(:extension)

:Extension record, as used in Erlang's :public_key module

Link to this section Functions

Link to this function

authority_info_access(access_methods)

View Source
@spec authority_info_access([{aia_access_method(), String.t()}]) :: t()

The authority information access extension indicates how to access information and services for the issuer of the certificate in which the extension appears.

Information and services may include on-line validation services and CA policy data. This extension may be included in end entity or CA certificates.

This extension is marked as non-critical.

Example:

iex> X509.Certificate.Extension.authority_info_access(
...>   ocsp: "http://ocsp.example.net/"
...> )
{:Extension, {1, 3, 6, 1, 5, 5, 7, 1, 1}, false,
 [
   {:AccessDescription, {1, 3, 6, 1, 5, 5, 7, 48, 1},
    {:uniformResourceIdentifier, "http://ocsp.example.net/"}}
 ]}
Link to this function

authority_key_identifier(public_key)

View Source
@spec authority_key_identifier(X509.PublicKey.t() | binary()) :: t()

The authority key identifier extension provides a means of identifying the public key corresponding to the private key used to sign a certificate.

The value should be a public key record. It is possible to pass a pre-calculated SHA-1 value, though it is preferred to let the function calculate the correct value over the original public key.

This extension is marked as non-critical.

Example:

iex> X509.Certificate.Extension.authority_key_identifier({:RSAPublicKey, 55, 3})
{:Extension, {2, 5, 29, 35}, false,
 {:AuthorityKeyIdentifier,
  <<187, 230, 143, 92, 27, 37, 166, 93, 176, 137, 154, 111, 62, 152,
   215, 114, 3, 214, 71, 170>>, :asn1_NOVALUE, :asn1_NOVALUE}}
Link to this function

basic_constraints(ca, path_len_constraint \\ :asn1_NOVALUE)

View Source
@spec basic_constraints(boolean(), integer() | :asn1_NOVALUE) :: t()

The basic constraints extension identifies whether the subject of the certificate is a CA and the maximum depth of valid certification paths that include this certificate.

This extension is always marked as critical for CA certificates, and non-critical when CA is set to false.

Examples:

iex> X509.Certificate.Extension.basic_constraints(false)
{:Extension, {2, 5, 29, 19}, false,
 {:BasicConstraints, false, :asn1_NOVALUE}}

iex> X509.Certificate.Extension.basic_constraints(true)
{:Extension, {2, 5, 29, 19}, true, {:BasicConstraints, true, :asn1_NOVALUE}}

iex> X509.Certificate.Extension.basic_constraints(true, 0)
{:Extension, {2, 5, 29, 19}, true, {:BasicConstraints, true, 0}}
Link to this function

crl_distribution_points(uri_list)

View Source
@spec crl_distribution_points([String.t()]) :: t()

The CRL distribution points extension identifies how CRL information is obtained.

The list of distribution points must be specified as a list of strings containing HTTP, FTP and/or LDAP URIs. Other types of distribution points are defined in RFC 5280, but are not supported by this function at this time.

This extension is marked as non-critical.

Example:

iex> X509.Certificate.Extension.crl_distribution_points(["http://crl.example.org/root.crl"])
{:Extension, {2, 5, 29, 31}, false,
 [
   {:DistributionPoint,
    {:fullName, [uniformResourceIdentifier: 'http://crl.example.org/root.crl']},
    :asn1_NOVALUE, :asn1_NOVALUE}
 ]}
@spec ext_key_usage([atom() | :public_key.oid()]) :: t()

This extension indicates one or more purposes for which the certified public key may be used, in addition to or in place of the basic purposes indicated in the key usage extension. In general, this extension will appear only in end entity certificates.

Each of the values in the list must be an OID, either in raw tuple format or as an atom representing a well-known OID. Typical examples include:

  • :serverAuth - TLS WWW server authentication
  • :clientAuth - TLS WWW client authentication
  • :codeSigning - Signing of downloadable executable code
  • :emailProtection - Email protection
  • :timeStamping - Binding the hash of an object to a time
  • :ocspSigning - Signing OCSP responses

This extension is marked as non-critical.

Example:

iex> X509.Certificate.Extension.ext_key_usage([:serverAuth, :clientAuth])
{:Extension, {2, 5, 29, 37}, false,
 [{1, 3, 6, 1, 5, 5, 7, 3, 1}, {1, 3, 6, 1, 5, 5, 7, 3, 2}]}
Link to this function

find(list, extension_oid)

View Source
@spec find([t()], extension_id() | :public_key.oid()) :: t() | nil

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

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 key_usage([key_usage_value()]) :: t()

The key usage extension defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate.

Each of the key usage values must be one of the atoms recognized by Erlang's :public_key module, though this is not verified by this function.

This extension is always marked as critical.

Example:

iex> X509.Certificate.Extension.key_usage([:digitalSignature, :keyEncipherment])
{:Extension, {2, 5, 29, 15}, true, [:digitalSignature, :keyEncipherment]}
@spec ocsp_nocheck() :: t()

The OCSP Nocheck extension indicates that the OCSP client can trust this OCSP responder certificate for the lifetime of the certificate, and no revocation checks are needed.

This extension has no value, it acts as a flag simply by being present in a certificate's extension list.

This extension is marked as non-critical.

Example:

iex> X509.Certificate.Extension.ocsp_nocheck()
{:Extension, {1, 3, 6, 1, 5, 5, 7, 48, 1, 5}, false, <<5, 0>>}
@spec subject_alt_name([san_value()]) :: t()

The subject alternative name extension allows identities to be bound to the subject of the certificate. These identities may be included in addition to or in place of the identity in the subject field of the certificate. Defined options include an Internet electronic mail address, a DNS name, an IP address, and a Uniform Resource Identifier (URI).

Typically the subject alternative name extension is used to define the DNS domains or hostnames for which a certificate is valid, so this function maps string values to DNSName entries. Values of other types can be passed in a type/value tuples as supported by Erlang's :public_key module, if required. Note that Erlang will typically require the value to be a character list.

This extension is marked as non-critical.

Example:

iex> X509.Certificate.Extension.subject_alt_name(["www.example.com", "example.com"])
{:Extension, {2, 5, 29, 17}, false,
 [dNSName: 'www.example.com', dNSName: 'example.com']}

iex> X509.Certificate.Extension.subject_alt_name(emailAddress: 'user@example.com')
{:Extension, {2, 5, 29, 17}, false,
 [emailAddress: 'user@example.com']}
Link to this function

subject_key_identifier(public_key)

View Source
@spec subject_key_identifier(X509.PublicKey.t() | binary()) :: t()

The subject key identifier extension provides a means of identifying certificates that contain a particular public key.

The value should be a public key record or a pre-calculated binary SHA-1 value.

This extension is marked as non-critical.

Example:

iex> X509.Certificate.Extension.subject_key_identifier({:RSAPublicKey, 55, 3})
{:Extension, {2, 5, 29, 14}, false,
 <<187, 230, 143, 92, 27, 37, 166, 93, 176, 137, 154, 111, 62, 152,
  215, 114, 3, 214, 71, 170>>}