caucase 0.9.8

Overview

The goal of caucase is to automate certificate issuance and renewal without constraining how the certificate will be used.

For example, there is no assumption that the certificate will be used to secure HTTP, nor to serve anything at all: you may need certificates to authenticate users, or sign your mails, or secure an SQL server socket.

As an unfortunate consequence, it is not possible for caucase to automatically validate a signing request content against a service (ex: as one could check the certificate for an HTTPS service was requested by someone with the ability to make it serve a special file).

This also means that, while caucase imposes RFC-recommended constraints on many certificate fields and extensions to be worthy of trust, it imposes no constraint at all on subject and alternate subject certificate fields.

To still allow certificates to be used, caucase uses itself to authenticate users (humans or otherwise) who implement the validation procedure: they tell caucase what certificates to emit. Once done, any certificate can be prolonged at a simple request of the key holder while the to-renew certificate is still valid (not expired, not revoked).

Bootstrapping the system (creating the first service certificate for caucased to operate on HTTPS, and creating the first user certificate to control further certificate issuance) works by caucase automatically signing a set number of certificates upon submission.

Vocabulary

Caucase manipulates the following asymmetric cryptography concepts.

• Key pair: A private key and corresponding public key. The public key can be derived from the private key, but not the other way around. As a consequence, the private key is itself considered to be a key pair.

• Certificate: A certificate is the assurante, by a certificate authority, that a given public key and set of attributes belong to an authorised entity. Abbreviated cert or crt. A certificate is by definition signed by a CA.

• Certificate Authority: An entry, arbitrarily trusted (but worthy of trust by its actions and decision) which can issue certificates. Abbreviated CA.

• Certificate signing request: A document produced by an entity desiring to get certified, which they send to a certificate authority. The certificate signing request contains the public key and desired set of attributes that the CA should pronounce itself on. The CA has all liberty to issue a different set of attributes, or to not issue a certificate.

• Certificate revocation list: Lists the certificates which were issued by a CA but which should not be trusted anymore. This can happen for a variety of reasons: the private key was compromised, or its owning entity should not be trusted anymore (ex: entity’s permission to access to protected service was revoked).

• PEM: A serialisation mechanism commonly used for various cryptographic data pieces. It relies on base64 so it is 7-bits-safe (unlike DER), and is very commonly supported. Caucase exclusively uses PEM format.

Validity period

Cryptographic keys wear out as are used and as they age.

Of course, they do not bit-rot nor become thinner with use. But each time one uses a key and each minute an attacker had access to a public key, fractions of the private key bits are inevitably leaked, weakening it overall.

So keys must be renewed periodically to preserve intended security level. So there is a limited life span to each certificate, including the ones emitted by caucase.

The unit duration for caucase-emitted certificates is the “normal” certificate life span. It default to 93 days from the moment the certificate was signed, or about 3 months.

Then the CA certificate has a default life span of 4 “normal” certificate validity periods. As CA renewal happens in caucase without x509-level cross signing (by decision, to avoid relying on intermediate CA support on certificate presenter side and instead rely on more widespread multi-CA-certificate support on verifier side), there is a hard lower bound of 3 validity periods, under which the CA certificate cannot be reliably renewed without risking certificate validation issues for emitted “normal” certificates. CA certificate renewal is composed of 2 phases:

• Passive distribution phase: current CA certificate has a remaining life span of less than 2 “normal” certificate life spans: a new CA certificate is generated and distributed on-demand (on “normal” certificate renewal and issuance, on CRL retrieval with caucase tools…), but not used to sign anything.

• Active use phase: new CA certificate is valid for more than one “normal” certificate life span. This means that all existing certificates which are still in active use had to be renewed at least once since the new CA certificate exists. This means all the certificate holders had the opportunity to learn about the new CA certificate. So the new CA certificate starts being used to sign new certificates, and the old CA certificate falls out of use as its signed “normal” certificates expire.

By default, all caucase tools will generate a new private key unrelated to the previous one on each certificate renewal.

Lastly, there is another limited validity period, although not for the same reasons: the list of revoked certificates also has a maximum life span. In caucase, the CRL is re-generated whenever it is requested and:

• there is no previous CRL

• previous CRL expired

• any revocation happened since previous CRL was created

Commands

Caucase provides several commands to work with certificates.

{
  "description": "Caucase backup header",
  "required": ["algorithm", "key_list"],
  "properties": {
    "cipher": {
      "description": "Symetric ciher used for payload",
      "required": ["name"],
      "properties": {
        "name":
          "enum": ["aes256_cbc_pkcs7_hmac_10M_sha256"],
          "type": "string"
        },
        "parameter": {
          "description": "Name-dependend clear cipher parameter (ex: IV)",
          "type": "string"
        }
      }
      "type": "object"
    },
    "key_list": {
      "description": "Content key, encrypted with public keys",
      "minItems": 1,
      "items": {
        "required": ["id", "cipher", "key"],
        "properties": {
          "id": {
            "description": "Hex-encoded sha1 hash of the public key",
            "type": "string"
          },
          "cipher": {
            "description": "Asymetric cipher used for symetric key",
            "required": ["name"],
            "properties": {
              "name": {
                "enum": ["rsa_oaep_sha1_mgf1_sha1"],
                "type": "string"
              }
            },
            "type": "object"
          }
          "key": {
            "description": "Hex-encoded encrypted concatenation of signing and symetric encryption keys",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

0.9.8 (2020-06-29)

• Add support for python3.

• Add support for one-CA-cert-per-file layout. For services which do not support loading multiple CA certificates from a single file.

• Fix caucase.sh authenticated usage (was broken by 0.9.4 “Make caucased https CA certificate safer”).

• Avoid busy-loop in caucase-updater when it thinks a renewal is due but caucased does not offer a newer version.

• Fix tests timeouts on slower machined. Anything faster than a Raspberry Pi 1 should now pass.

0.9.7 (2020-06-04)

• Fix CRL renewal: * teach caucased to renew CRLs ahead of their expirations. * make caucase-updater check CRL expiration date.

• Grant extra permissions in license.

0.9.6 (2019-05-27)

• Do not use a 128bits OID arc for caucase internal use, as it is not widely supported.

• Assorted CLI usability improvements.

0.9.5 (2019-01-24)

• Add –version support.

• Logging is reworked to reduce verbosity (especially in tests).

• Fix caucased sometimes crashing when renewing its https certificate.

• Make caucased logs more apache-like.

• Make caucased responses more standard-compliant (“Allow” header in 405 response and “Date” header in all responses).

• Fix unintended dependency on system timezone.

0.9.4 (2018-11-14)

• Improved documentation.

• Tentative web-friendliness (not used in real life yet, so practicality is still uncertain): * Make caucased https CA certificate safer for adding in a trust store (ex: browser) by constraining the certificates it can sign. * cookie-based CORS access control with crude UI. * API is self-documenting using application/hal+json format.

• Tentative python3 friendliness, there may still be file IO encoding issues.

0.9.3 (2018-09-21)

• Add support for listening to multiple specific addresses in caucased.

• shell implementation does not rely on an external file anymore.

• Do not start listening on https port before wrapping sockets with an ssl context

• Make caucase-updater usable by anonymous services (ex: they only need to connect to a caucase-certified service, without authenticating themselves using caucase)

• Use stricter file permissions for caucased sqlite database.

• Include caucase version in user agent header.

• Make caucased logging format more similar to apache’s default.

• Fix caucased https certificate renewal. Fixes a crash which happens every 2 months.

• Make caucase-updater retry on network errors. Fixes crashes on transient network error.

0.9.2 (2017-11-03)

• Add support for migrating an existing CA to caucase: import CA cert and CRLs.

• Require CRL signature checks (bumps cryptography module version requirements).

• Provide CRL distribution point extension in CA certificates.

• Play nicer with http: * Catch more errors to provide nice status codes * Add support for “Transfer-Encoding: chunked” * Add support for “Expect: 100-continue”

• Produce TLS-compliant certificates (domain name must be in an alternative name extension, subject is not enough).

• Reduce speed requirements in tests.

• Add shell implementation of “caucase” command.

• Certificate renewal bypasses pending CSR limits.

• caucase-manage: new command for offline database maintenance.

0.9.1 (2017-09-21)

• Documentation improvements

• Packaging improvements

0.9.0 (2017-08-02)

• implement the “cau” half of “caucase”

• massive rework: removal of flask dependency, removal of HTML UI, rework of the REST API, rework of the CLI tools, rework of the WGSI application, incomatible redesign of the database.

0.1.4 (2017-07-21)

• caucase web parameter ‘auto-sign-csr-amount’ can be used to set how many csr must be signed automatically.

0.1.3 (2017-06-30)

• add support for backup caucase database to cli

• serial is a random unique formatted hexadecimal number get from the csr_id

• allow to set custom subject (X509Name) when signing a certificate

• add new cliweb command which when required will download/update crl file from caucase web

0.1.2 (2017-05-12)

• cliweb: renew now takes threshold option to check if renew is required and optional on-renew script to run after certificate renewal

0.1.1 (2017-04-27)

• initial implementation of certificate authority