open-vault/ui/lib/pki/README.md

Vault PKI

Welcome to the Vault PKI (Ember) Engine! Below is an overview of PKI and resources for how to get started working within this engine.

About PKI

Public Key Infrastructure (PKI) is a system of processes, technologies, and policies that allows you to encrypt and sign data. (source: digicert.com)

The Vault PKI Secrets Engine allows security engineers to create a chain of PKI certificates much easier than they would with traditional workflows.

About the UI engine

If you couldn't tell from the documentation above, PKI is complex. As such, the data doesn't map cleanly to a CRUD model and so the first thing you might notice is that the models and adapters for PKI (which live in the main app, not the engine) have some custom logic that differentiate it from most other secret engines. Below are the models used throughout PKI and how they are used to interact with the mount. Aside from pki/action, each model has a corresponding tab in the UI that takes you to its LIST view.

• pki/action

  This model is used to perform different POST requests that receive similar parameters but don't create a single item (which would be a record in Ember data). These various actions may create multiple items that contain different attributes than those submitted in the POST request. For example:

  • POST pki/generate/root/:type creates a new self-signed CA certificate (an issuer) and private key, which is only returned if type = exported
  • POST pki/issuer/:issuer_ref/sign-intermediate creates a certificate, and returns issuing CA and CA chain data that is only available once

  The pki/actionadapter is used to map the desired action to the corresponding endpoint, and the pki/action serializer includes logic to send the relevant attributes. The following PKI workflows use this model:

  • Root generation and rotation
  • Import CA cert and keys
  • Generate intermediate CSR
  • Sign intermediate

• pki/certificate/base

  This model is for specific interactions with certificate data. The base model contains attributes that make up a certificate's content. The other models that extend this model certificate/generate and certificate/sign include additional attributes to perform their relevant requests.

  The parsedCertificate attribute is an object that houses all of the parsed certificate data returned by the parse-pki-cert.js util.

• pki/tidy

  This model is used to manage tidy operations in a few different contexts. All of the following endpoints share the same parameters except enabled and interval_duration which are reserved for auto-tidy operations only.

  pki/tidy-status does not use an Ember data model because it is read-only

  • POST pki/tidy - perform a single, manual tidy operation
  • POST pki/config/auto-tidy - set configuration for automating the tidy process
  • GET pki/config/auto-tidy - read auto-tidy configuration settings

  The auto-tidy config is the only data that persists so findRecord and updateRecord in the pki/tidy.js adapter only interact with the /config/auto-tidy endpoint. For each manual tidy operation, a new record is created so on save() the model uses the createRecord method which only ever uses the /tidy endpoint.

The following models more closely follow a CRUD pattern:

• pki/issuer

  Issuers are created by the pki/action model by either importing a CA or generating a root

  • update
  • read
  • list

• pki/role

  • create/update
  • read
  • list

• pki/key

  • CREATE has two options:
    • generate
    • import
  • read
  • list