X509
v0.8.8

View Source X509.Test.Suite (X509 v0.8.8)

This module may be used to generate a suite of certificates for client or server testing, and offers an sni_fun hook for setting up a test scenario based on the requested hostname.

test-scenarios

 Test scenarios:

  • valid - presenting a valid server certificate

  • valid-missing-chain - presenting a valid server certificate, but configured without the required intermediate CA; should be rejected unless peer verification is disabled or the intermediate CA is trusted by the client

  • valid-expired-chain - presenting a valid server certificate, but configured with an expired intermediate CA; should be rejected unless peer verification is disabled

  • valid-revoked-chain - presenting a valid server certificate, but configured with a revoked intermediate CA; should be rejected unless peer verification is disabled

  • valid-wrong-key - presenting a valid server certificate, but configured with the wrong private key; should always be rejected

  • valid-wrong-host - presenting a valid server certificate with a SAN hostname that does not match; should be rejected unless peer verification is disabled

  • valid-cross-signed - presenting a valid server certificate, cross-signed by an alternative root CA, and with a certificate chain that resolves to both the standard root CA and the cross-signing root CA

  • valid.wildcard - presenting a valid wildcard server certificate

  • wildcard - presenting a valid wildcard server certificate, but without a SAN hostname for the bare domain; should be rejected unless peer verification is disabled

  • invalid.subdomain.wildcard - presenting a valid wildcard server certificate, but accessed using an invalid nested subdomain; should be rejected unless peer verification is disabled

  • expired - presenting an expired server certificate; should be rejected unless peer verification is disabled

  • revoked - presenting a revoked server certificate; should be rejected unless peer verification is disabled

  • selfsigned - presenting a self-signed server certificate; should normally be rejected by a client unless server certificate verification is disabled or the client is configured to explicitly allow the specific certificate ('pinning')

  • selfsigned-wrong-key - presenting a self-signed server certificate, but configured with the wrong private key; should always be rejected

  • selfsigned-wrong-host - presenting a self-signed server certificate with a SAN hostname that does not match; should be rejected unless peer verification is disabled

  • client-cert - requires that the client present a valid certificate

Link to this section Summary

Types

t()

Functions

new(opts \\ [])

Builds and returns a new test suite.

sni_fun(suite)

Returns a suitable SNI (Server Name Indication) handler function for the given test suite. May be used to configure custom servers to act as a test suite endpoint.

Link to this section Types

Link to this type

t()

View Source 
@type t() :: %X509.Test.Suite{
  alternate_cacerts: [binary()],
  alternate_chain: [binary()],
  cacerts: [binary()],
  chain: [binary()],
  client: X509.Certificate.t(),
  client_key: X509.PrivateKey.t(),
  crls: %{required(String.t()) => X509.CRL.t()},
  domain: String.t(),
  expired: X509.Certificate.t(),
  expired_chain: [binary()],
  key_type:
    {:rsa, non_neg_integer()}
    | {:ec, :crypto.ec_named_curve() | :public_key.oid()},
  other_key: X509.PrivateKey.t(),
  revoked: X509.Certificate.t(),
  revoked_chain: [binary()],
  selfsigned: X509.Certificate.t(),
  server_key: X509.PrivateKey.t(),
  valid: X509.Certificate.t(),
  wildcard: X509.Certificate.t()
}

Link to this section Functions

Link to this function

new(opts \\ [])

View Source 
@spec new(Keyword.t()) :: t()

Builds and returns a new test suite.

options

 Options:

  • :domain - the test domain to use; any subdomain for the given domain needs to resolve to the IP address where the test server will be hosted, e.g. 127.0.0.1 or ::1; the default value is 'localtest.me', which requires Internet access during test execution
  • :crl_server - the base URL for a CRL server that may be used as a CRL DP; if none is specified, no CRL DPs are included in the generated certificates, and revocation scenarios are not supported
  • :key_type - the type of private keys to generate; may be set to {:rsa, bits} to select RSA keys of the given length, or {:ec, curve} to select ECC keys based on the given curve (default: {:rsa, 1024})
Link to this function

sni_fun(suite)

View Source 
@spec sni_fun(t()) :: (charlist() -> [Keyword.t()])

Returns a suitable SNI (Server Name Indication) handler function for the given test suite. May be used to configure custom servers to act as a test suite endpoint.

In addition to setting the sni_fun parameter to the return value of this function, the reuse_sessions parameter must be set to false. This ensures that a new handshake is performed on each connection.