| Serge Bazanski | 9411f7c | 2021-03-10 13:12:53 +0100 | [diff] [blame] | 1 | // Copyright 2020 The Monogon Project Authors. |
| 2 | // |
| 3 | // SPDX-License-Identifier: Apache-2.0 |
| 4 | // |
| 5 | // Licensed under the Apache License, Version 2.0 (the "License"); |
| 6 | // you may not use this file except in compliance with the License. |
| 7 | // You may obtain a copy of the License at |
| 8 | // |
| 9 | // http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | // |
| 11 | // Unless required by applicable law or agreed to in writing, software |
| 12 | // distributed under the License is distributed on an "AS IS" BASIS, |
| 13 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 | // See the License for the specific language governing permissions and |
| 15 | // limitations under the License. |
| 16 | |
| 17 | // package pki implements an x509 PKI (Public Key Infrastructure) system backed |
| 18 | // on etcd. |
| 19 | // |
| 20 | // The PKI is made of Certificates, all constrained within a Namespace. The |
| 21 | // Namespace allows for multiple users of this library to co-exist on a single |
| 22 | // etcd server. |
| 23 | // |
| 24 | // Any time a Certificate object is created, it describes the promise (or |
| 25 | // intent) of an x509 certificate to exist. For every created Certifiacte an |
| 26 | // Issuer must be specified - either another Certificate (which will act as a |
| 27 | // CA and sign that Certificate), or SelfSigned (which will cause the |
| 28 | // Certificate to be self-signed when generated). |
| 29 | // |
| 30 | // Once a Certificate object is created, a call to Ensure() must be placed to |
| 31 | // turn the intent of a certificate into physical bytes that can then be |
| 32 | // accessed by the appliaction. |
| 33 | // |
| 34 | // Two kinds of Certificates can be created: |
| 35 | // - Named certificates are stored in etcd, and an Ensure call will either |
| 36 | // create them, or return a Certificate already stored in etcd. Multiple |
| 37 | // concurrent calls to Ensure for a Certificate with the same name are |
| 38 | // permitted, even across machines, as long as the Certificate intent data |
| 39 | // is the same. If not, it is still safe to perform this action |
| 40 | // concurrently, but the first transaction will win, causing the losing |
| 41 | // transaction to return the Ensure call with a certificate that was not |
| 42 | // based on the same intent. |
| 43 | // It is the responsibility of the caller to ensure these cases are handled |
| 44 | // gracefully. |
| 45 | // - Volatile certificates are stored in memory, and have an empty ("") name. |
| 46 | // Any time Ensure is called, the certificate already present in memory is |
| 47 | // returned, or one is created if it does not yet exist. |
| 48 | // Currently, these certificates live fully in memory, but in the future we |
| 49 | // will likely perform audit logging (and revocation) of these certificate |
| 50 | // within etcd, too. |
| 51 | // |
| 52 | package pki |