// Copyright 2020 The Monogon Project Authors.
//
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// package pki implements an x509 PKI (Public Key Infrastructure) system backed
// on etcd.
//
// The PKI is made of Certificates, all constrained within a Namespace. The
// Namespace allows for multiple users of this library to co-exist on a single
// etcd server.
//
// Any time a Certificate object is created, it describes the promise (or
// intent) of an x509 certificate to exist. For every created Certifiacte an
// Issuer must be specified - either another Certificate (which will act as a
// CA and sign that Certificate), or SelfSigned (which will cause the
// Certificate to be self-signed when generated).
//
// Once a Certificate object is created, a call to Ensure() must be placed to
// turn the intent of a certificate into physical bytes that can then be
// accessed by the appliaction.
//
// Two kinds of Certificates can be created:
//  - Named certificates are stored in etcd, and an Ensure call will either
//    create them, or return a Certificate already stored in etcd. Multiple
//    concurrent calls to Ensure for a Certificate with the same name are
//    permitted, even across machines, as long as the Certificate intent data
//    is the same. If not, it is still safe to perform this action
//    concurrently, but the first transaction will win, causing the losing
//    transaction to return the Ensure call with a certificate that was not
//    based on the same intent.
//    It is the responsibility of the caller to ensure these cases are handled
//    gracefully.
//  - Volatile certificates are stored in memory, and have an empty ("") name.
//    Any time Ensure is called, the certificate already present in memory is
//    returned, or one is created if it does not yet exist.
//    Currently, these certificates live fully in memory, but in the future we
//    will likely perform audit logging (and revocation) of these certificate
//    within etcd, too.
//
package pki