@spec new(named_template() | t(), Keyword.t()) :: t()

Returns a template, optionally customized with user-provided validity, hash and extensions options.

The base template can be selected from a list of built-in named templates, or as a custom template. The following named templates are supported:

• :root_ca - intended for a self-signed root CA.

  The default path length constraint is set to 1, meaning the root CA can be used to issue intermediate CAs, and those CAs can only sign end certificates. The value can be overridden by passing a custom value for the :basic_constraints extension.

  The default validity is 25 years.

• :ca - intended for intermediate CA certificates.

  The default path length constraint is set to 0, meaning the CA can only sign end certificates. The value can be overridden by passing a custom value for the :basic_constraints extension (assuming the issuing CA allows it).

  The Extended Key Usage extension is set to TLS server & client. Many (but not all) TLS implementations will interpret this as a constraint on the type of certificates the CA is allowed to issue. This constraint can be removed by setting :ext_key_usage to false, or by overriding the value to set the desired constraints.

  The default validity is 10 years.

• :server - intended for end-certificates.

  The Extended Key Usage extension is set to TLS server & client. For other types of end-certificates, set the :ext_key_usage extension to the desired value. It may be necessary to update the :key_usage value as well.

  The default validity is 1 year, plus a 30 day grace period.

• :ocsp_responder - designated responder to sign OCSP responses on behalf of the issuing CA.

  The Extended Key Usage extension is set to allow OCSP signing only. Must be issued directly from the CA certificate for which OCSP responses will be signed.

  The OCSP Nocheck extension is included, to disable revocation checks for the OCSP responder certificate. To exclude this extension override it with a value of false (e.g. extensions: [ocsp_nocheck: false])

  The default validity is just 30 days, due to the fact that revocation is not possible when OCSP Nocheck is set.

All of the above templates generate a random 8 byte (64 bit) serial number, which can be overridden through the :serial option (see below).

The extensions attribute of a template is a keyword list of extension name/value pairs, where the value should typically be an X509.Certificate.Extension record. The subject_key_identifier and authority_key_identifier extensions may simply be set to true: the actual values will be calculated during the certificate signing process.

options

Options:

• :hash - the hash algorithm to use when signing the certificate
• :serial - the serial number of the certificate (an integer >0) or {:random, n} to generate an n-byte random serial number
• :validity - override the validity period; can be specified as the number of days (integer) or a X509.Certificate.Validity value
• :extensions - a keyword list of extensions to be merged into the template's defaults; set an extension value to false to exclude that extension from the certificate

examples

Examples:

iex> X509.Certificate.Template.new(:root_ca,
...>   hash: :sha512, serial: 1,
...>   extensions: [authority_key_identifier: false]
...> )
%X509.Certificate.Template{
  extensions: [
    basic_constraints: {:Extension, {2, 5, 29, 19}, true,
     {:BasicConstraints, true, 1}},
    key_usage: {:Extension, {2, 5, 29, 15}, true,
     [:digitalSignature, :keyCertSign, :cRLSign]},
    subject_key_identifier: true,
    authority_key_identifier: false
  ],
  hash: :sha512,
  serial: 1,
  validity: 9131
}

iex> X509.Certificate.Template.new(:server, extensions: [
...>   ext_key_usage: X509.Certificate.Extension.ext_key_usage([:codeSigning])
...> ])
%X509.Certificate.Template{
  extensions: [
    basic_constraints: {:Extension, {2, 5, 29, 19}, false,
     {:BasicConstraints, false, :asn1_NOVALUE}},
    key_usage: {:Extension, {2, 5, 29, 15}, true,
     [:digitalSignature, :keyEncipherment]},
    subject_key_identifier: true,
    authority_key_identifier: true,
    ext_key_usage: {:Extension, {2, 5, 29, 37}, false,
     [{1, 3, 6, 1, 5, 5, 7, 3, 3}]}
  ],
  hash: :sha256,
  serial: {:random, 8},
  validity: 395
}