README.rst 13.6 KB
Newer Older
Łukasz Nowak's avatar
Łukasz Nowak committed
1 2
..  Note to the editor: beware of implicit inline
    targets aliasing, keep global title different from all commands
3

Łukasz Nowak's avatar
Łukasz Nowak committed
4 5 6
=============================================================================
caucase - Certificate Authority for Users, Certificate Authority for SErvices
=============================================================================
Vincent Pelletier's avatar
Vincent Pelletier committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

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
Łukasz Nowak's avatar
Łukasz Nowak committed
30
prolonged at a simple request of the key holder while the to-renew
Vincent Pelletier's avatar
Vincent Pelletier committed
31 32 33
certificate is still valid (not expired, not revoked).

Bootstrapping the system (creating the first service certificate for
Łukasz Nowak's avatar
Łukasz Nowak committed
34
`caucased`_ to operate on HTTPS, and creating the first user certificate to
Vincent Pelletier's avatar
Vincent Pelletier committed
35 36 37 38 39 40
control further certificate issuance) works by caucase automatically signing a
set number of certificates upon submission.

Vocabulary
==========

Łukasz Nowak's avatar
Łukasz Nowak committed
41
Caucase manipulates the following asymmetric cryptography concepts.
Vincent Pelletier's avatar
Vincent Pelletier committed
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57

- 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
Łukasz Nowak's avatar
Łukasz Nowak committed
58
  of attributes, or to not issue a certificate.
Vincent Pelletier's avatar
Vincent Pelletier committed
59 60

- Certificate revocation list: Lists the certificates which were issued by a CA
Łukasz Nowak's avatar
Łukasz Nowak committed
61 62
  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
Vincent Pelletier's avatar
Vincent Pelletier committed
63 64 65 66 67 68 69 70 71 72
  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
===============

Łukasz Nowak's avatar
Łukasz Nowak committed
73
Cryptographic keys wear out as are used and as they age.
Vincent Pelletier's avatar
Vincent Pelletier committed
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90

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
Łukasz Nowak's avatar
Łukasz Nowak committed
91
multi-CA-certificate support on verifier side), there is a hard lower bound of
Vincent Pelletier's avatar
Vincent Pelletier committed
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
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
Łukasz Nowak's avatar
Łukasz Nowak committed
110
previous one on each certificate renewal.
Vincent Pelletier's avatar
Vincent Pelletier committed
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138

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.

caucase
+++++++

Reference caucase "one-shot" client.

This command is intended to be used for isolated actions:

- listing and signing pending certificate signature requests

- revoking certificates

It is also able to submit certificate signing requests, retrieve signed
certificates, requesting certificate renewals and updating both
CA certificates and revocation lists, but you may be interested in using
Łukasz Nowak's avatar
Łukasz Nowak committed
139
`caucase-updater`_ for this instead.
Vincent Pelletier's avatar
Vincent Pelletier committed
140

141
caucase-updater
Vincent Pelletier's avatar
Vincent Pelletier committed
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
+++++++++++++++

Reference caucase certificate renewal daemon.

Monitors a key pair, corresponding CA certificate and CRL, and renew them
before expiration.

When the key-pair lacks a signed certificate, issues a pre-existing CSR to
caucase server and waits for the certificate to be issued.

caucase-probe
+++++++++++++

Caucase server availability tester.

Performs minimal checks to verify a caucase server is available at given URL.

caucase-rerequest
+++++++++++++++++

Utility allowing to re-issue a CSR using a locally-generated private key.

Łukasz Nowak's avatar
Łukasz Nowak committed
164
Intended to be used in conjunction with `caucase-updater`_ when user cannot
Vincent Pelletier's avatar
Vincent Pelletier committed
165 166 167 168 169 170 171 172 173
generate the CSR on the system where the certificate is desired (ex: automated
HTTPS server deployment), where user is not the intended audience for
caucase-produced certificate:

- User generates a CSR on their own system, and signs it with any key (it will
  not be needed later
- User sends the CSR to the system where the certificate is desired
- User gets caucase-rerequest to run on this CSR, producing a new private key
  and a CSR similar to issued one, but signed with this new private key
174
- From then on, caucase-updater can take over
Vincent Pelletier's avatar
Vincent Pelletier committed
175 176 177 178 179 180 181 182 183 184 185

This way, no private key left their original system, and user could still
freely customise certificate extensions.

caucase-key-id
++++++++++++++

Utility displaying the identifier of given key, or the identifier of keys
involved in given backup file.

Allows identifying users which hold a private key candidate for restoring a
Łukasz Nowak's avatar
Łukasz Nowak committed
186
caucased backup (see `Restoration procedure`_).
Vincent Pelletier's avatar
Vincent Pelletier committed
187 188 189 190 191 192 193 194 195 196

caucased
++++++++

Reference caucase server daemon.

This daemon provides access to both CAU and CAS services over both HTTP and
HTTPS.

It handles its own certificate issuance and renewal, so there is no need to use
Łukasz Nowak's avatar
Łukasz Nowak committed
197
`caucase-updater`_ for this service.
Vincent Pelletier's avatar
Vincent Pelletier committed
198

199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
CORS
----

caucased implements CORS protection: when receiving a cross-origin request,
it will respond with 401 Unauthorized, with the WWW-Authenticate header set to
a custom scheme ("cors") with an "url" parameter containing an URI template
with one variable field: "return" (more on it later).

Upon receiving this response, the application is expected to render the URL
template and redirect the user to resulting URL. There, the user will be
informed of the cross-origin access attempt, and offered the choice to grant or
deny access to given origin.

Once their decision is made, their browser will receive a cookie remembering
this decision, and they will be redirected to the URL received in the "return"
field received upon above-described redirection.

Then, the application should retry the original request, which will be
accompanied by that cookie.

Vincent Pelletier's avatar
Vincent Pelletier committed
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
Backups
-------

Loosing the CA private key prevents issuing any new certificate trusted by
services which trusted the CA. Also, it prevents issuing any new CRL.
Recovering from such total loss requires starting a new CA and rolling it out
to all services which used the previous one. This is very time-costly.

So backups are required.

On the other hand, if someone gets their hand on the CA private key, they can
issue certificates for themselves, allowing them to authenticate with services
trusting the CA managed by caucase - including caucased itself if they issue a
user certificate: they can then revoke existing certificates and cause a lot of
damage.

So backups cannot happen in clear text, they must be encrypted.

But the danger of encrypted backups is that by definition they become worthless
if they cannot be decrypted. So as many (trusted) entities as possible should
be granted the ability to decrypt the backups.

The solution proposed by caucased is to encrypt produced backups in a way which
allows any of the caucase users to decrypt the archive.

As these users are already entrusted with issuing certificates, this puts
only a little more power in their hands than they already have. The little
extra power they get is that by having unrestricted access to the CA private
key they can issue certificates bypassing all caucase restrictions. The
proposed parade is to only make the backups available to a limited subset of
caucase users when there is an actual disaster, and otherwise keep it out of
their reach. This mechanism is not handled by caucase.

As there are few trusted users, caucase can keep their still-valid certificates
in its database for the duration of their validity with minimal size cost.

Backup procedure
----------------

Backups happen periodically as long as caucased is running. See
`--backup-period` and `--backup-directory`.

As discussed above, produced files should be kept out of reach of caucase
users until a disaster happens.

Restoration procedure
---------------------

267
See `caucased-manage --restore-backup`.
Vincent Pelletier's avatar
Vincent Pelletier committed
268 269 270 271 272 273 274 275 276 277 278 279 280

To restore, one of the trusted users must voluntarily compromise their own
private key, providing it to the administrator in charge of the restoration
procedure. Restoration procedure will hence immediately revoke their
certificate. They must also provide a CSR generated with a different private
key, so that caucase can provide them with a new certificate, so they keep
their access only via different credentials.

- admin identifies the list of keys which can decipher a backup, and broadcasts
  that list to key holders

- key holders manifest themselves

281
- admin picks a key holder, requests them to provide their existing private key
Łukasz Nowak's avatar
Łukasz Nowak committed
282
  and to generate a new key and accompanying CSR
Vincent Pelletier's avatar
Vincent Pelletier committed
283 284 285 286

- key holder provide requested items

- admin initiates restoration with `--restore-backup` and provides key holder
287 288 289
  with replacement certificate

- admin starts caucased, service is back online.
Vincent Pelletier's avatar
Vincent Pelletier committed
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356

Backup file format
------------------

- 64bits: 'caucase\0' magic string

- 32bits LE: header length

- header: json-encoded header (see below)

- encrypted byte stream (aka payload)

Header schema (inspired from s/mime, but s/mime tools available do not
support at least iterative production or iterative generation)::

  {
    "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"
  }