CFXXL

v0.1.0

CFXXL v0.1.0 CFXXL View Source

A module containing functions to interact with the CFSSL API.

For more information on the contents of the results of each call, see the relative cfssl API documentation

Link to this section Summary

Functions

authsign(client, token, csr, opts \\ [])

Request to sign a CSR with authentication

bundle(client, opts)

Request a certificate bundle

certinfo(client, opts)

Request information about a certificate

crl(client, expiry \\ nil)

Generate a CRL from the database

get(client, route, params \\ %{})

Perform a generic GET to the CFSSL API

info(client, label, opts \\ [])

Get signer information

init_ca(client, hosts, dname, opts \\ [])

Request a new CA key/certificate pair

newcert(client, hosts, dname, opts \\ [])

Request a new key/signed certificate pair

newkey(client, hosts, dname, opts \\ [])

Request a new key/CSR pair

post(client, route, body)

Perform a generic POST to the CFSSL API

revoke(client, serial, aki, reason)

Request to revoke a certificate

scan(client, host, opts \\ [])

Scan an host

scaninfo(client)

Get information on scan families

sign(client, csr, opts \\ [])

Request to sign a CSR

Link to this section Functions

Link to this function authsign(client, token, csr, opts \\ []) View Source

Request to sign a CSR with authentication.

Arguments

  • client: the CFXXL.Client to use for the call
  • token: the authentication token
  • csr: the CSR as a PEM encoded string
  • opts: a keyword list of optional parameters

Options

  • timestamp: a Unix timestamp
  • remote_address: an address used in making the request
  • bundle: a boolean specifying whether to include an “optimal” certificate bundle along with the certificate
  • all the opts supported in sign/3

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function bundle(client, opts) View Source

Request a certificate bundle

Arguments

  • client: the CFXXL.Client to use for the call
  • opts: a keyword list of parameters

Options

opts must contain one of these two keys

  • certificate: the PEM-encoded certificate to be bundled
  • domain: a domain name indicating a remote host to retrieve a certificate for

If certificate is given, the following options are available:

  • private_key: the PEM-encoded private key to be included with the bundle. This is valid only if the server is not running in “keyless” mode
  • flavor: one of :ubiquitous, :force, or :optimal, with a default value of :ubiquitous. A ubiquitous bundle is one that has a higher probability of being verified everywhere, even by clients using outdated or unusual trust stores. Force will cause the endpoint to use the bundle provided in the certificate parameter, and will only verify that the bundle is a valid (verifiable) chain
  • domain: the domain name to verify as the hostname of the certificate
  • ip: the IP address to verify against the certificate IP SANs

Otherwise, using domain, the following options are available:

  • ip: the IP address of the remote host; this will fetch the certificate from the IP, and verify that it is valid for the domain name

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function certinfo(client, opts) View Source

Request information about a certificate

Arguments

  • client: the CFXXL.Client to use for the call
  • opts: a keyword list of parameters

Options

opts must contain one of these two keys

  • certificate: the PEM-encoded certificate to be parsed
  • domain: a domain name indicating a remote host to retrieve a certificate for

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function crl(client, expiry \\ nil) View Source

Generate a CRL from the database

Arguments

  • client: the CFXXL.Client to use for the call
  • expiry: an optional string to specify the time after which the CRL should expire from the moment of the request

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function get(client, route, params \\ %{}) View Source

Perform a generic GET to the CFSSL API.

Arguments

  • client: the CFXXL.Client to use for the call
  • route: the part to be appended to the url to make the call, without a leading slash
  • params: a map with the parameters to be appended to the URL of the GET

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function info(client, label, opts \\ []) View Source

Get signer information

Arguments

  • client: the CFXXL.Client to use for the call
  • label: a string specifying the signer
  • opts: a keyword list of optional parameters

Options

  • profile: a string specifying the signing profile for the signer. Signing profile specifies what key usages should be used and how long the expiry should be set

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function init_ca(client, hosts, dname, opts \\ []) View Source

Request a new CA key/certificate pair.

Arguments

  • client: the CFXXL.Client to use for the call
  • hosts: a list of strings representing SAN (subject alternative names) for the CA certificate
  • dname: a CFXXL.DName struct representing the DN for the CA certificate
  • opts: a keyword list of optional parameters

Options

  • CN: a string representing the CN for the certificate
  • key: a CFXXL.KeyConfig to configure the key, default to ECDSA-256
  • ca: a CFXXL.CAConfig to configure the CA

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function newcert(client, hosts, dname, opts \\ []) View Source

Request a new key/signed certificate pair.

Arguments

  • client: the CFXXL.Client to use for the call
  • hosts: a list of strings representing SAN (subject alternative names) for the certificate
  • dname: a CFXXL.DName struct representing the DN for the certificate
  • opts: a keyword list of optional parameters

Options

  • label: a string specifying which signer to be appointed to sign the CSR, useful when interacting with a remote multi-root CA signer
  • profile: a string specifying the signing profile for the signer, useful when interacting with a remote multi-root CA signer
  • bundle: a boolean specifying whether to include an “optimal” certificate bundle along with the certificate
  • all the opts supported in newkey/4

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function newkey(client, hosts, dname, opts \\ []) View Source

Request a new key/CSR pair.

Arguments

  • client: the CFXXL.Client to use for the call
  • hosts: a list of strings representing SAN (subject alternative names) for the certificate
  • dname: a CFXXL.DName struct representing the DN for the certificate
  • opts: a keyword list of optional parameters

Options

  • CN: a string representing the CN for the certificate
  • key: a CFXXL.KeyConfig to configure the key, default to ECDSA-256

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function post(client, route, body) View Source

Perform a generic POST to the CFSSL API.

Arguments

  • client: the CFXXL.Client to use for the call
  • route: the part to be appended to the url to make the call, without a leading slash
  • body: a map that will be serialized to JSON and used as the body of the request

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function revoke(client, serial, aki, reason) View Source

Request to revoke a certificate.

Arguments

  • client: the CFXXL.Client to use for the call
  • serial: the serial of the certificate to be revoked
  • aki: the AuthorityKeyIdentifier of the certificate to be revoked
  • reason: a string representing the reason of the revocation, see ReasonFlags in Section 4.2.1.13 of RFC5280

Return

  • :ok on success
  • {:error, reason} if it fails
Link to this function scan(client, host, opts \\ []) View Source

Scan an host

Arguments

  • client: the CFXXL.Client to use for the call
  • host: the hostname (optionally including port) to scan
  • opts: a keyword list of optional parameters

Options

  • ip: IP Address to override DNS lookup of host
  • timeout: The amount of time allotted for the scan to complete (default: 1 minute)
  • family: regular expression specifying scan famil(ies) to run
  • scanner: regular expression specifying scanner(s) to run

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function scaninfo(client) View Source

Get information on scan families

Arguments

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails
Link to this function sign(client, csr, opts \\ []) View Source

Request to sign a CSR.

Arguments

  • client: the CFXXL.Client to use for the call
  • csr: the CSR as a PEM encoded string
  • opts: a keyword list of optional parameters

Options

  • hosts: a list of strings representing SAN (subject alternative names) which overrides the ones in the CSR
  • subject: a CFXXL.Subject that overrides the ones in the CSR
  • serial_sequence: a string specifying the prefix which the generated certificate serial should have
  • label: a string specifying which signer to be appointed to sign the CSR, useful when interacting with a remote multi-root CA signer
  • profile: a string specifying the signing profile for the signer, useful when interacting with a remote multi-root CA signer
  • bundle: a boolean specifying whether to include an “optimal” certificate bundle along with the certificate

Return

  • {:ok, result} with the contents of the result key of the API
  • {:error, reason} if it fails