Add external PKI provider documentation

Splits the PKI documentation out into multiple pages, adding documentation for
how to set up AWS as an external PKI provider.

The local PKI guide is also split into a separate page, which gets linked to
from the main PKI page, alongside a link to the AWS page.

Signed-off-by: Trond Snekvik <trond@golioth.io>

Author: trond-snekvik

docs/connectivity/2-credentials/1-pki.md

@@ -0,0 +1,114 @@
+---
+title: "AWS Private CA"
+---
+
+To allow Golioth to use your AWS Private Certificate Authority service as a PKI
+provider for your project, you need to go through a few steps in the AWS Console
+before you can configure a connection from Golioth.
+
+For information about how you can establish a CA in AWS Private CA and issue
+end-entity certificates, please refer to [the official AWS
+documentation](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html).
+
+## Configuring AWS
+
+To allow Golioth to securely connect directly to your AWS Private CA service,
+you'll need to create an IAM user with the required permissions.
+
+### 1. Create an IAM user
+
+Golioth connects to your AWS Private CA service as an IAM user. Although it's
+possible for Golioth to authenticate as an existing user, we strongly recommend
+establishing a dedicated user with a narrow set of permissions.
+
+As an admin or an IAM user with the required permissions, navigate to the [IAM
+User Management Dashboard](https://console.aws.amazon.com/iamv2/home#/users) in
+the AWS Console, and click **Create User**.
+
+![Create a user](./assets/aws-user.png)
+
+Pick a recognizable user name, and click **Next** to go to the permissions
+screen.
+
+### 2. Set Permissions
+
+The Golioth user requires read access to the Private CA service to be able to
+authenticate device certificates. This can be enabled by attaching the
+**AWSPrivateCAReadOnly** policy to the user.
+
+To enable certificate rotation for your devices, you additionally need write
+permission for the AWS Private CA service. This can be enabled by attaching the
+**AWSPrivateCAUser** policy to the user.
+
+:::note
+Other, more permissive policies, such as **AWSPrivateCAFullAccess** and
+**AWSPrivateCAPrivilegedUser** also grant the required permissions to verify and
+issue device certificates, but these policies additionally grant the user the
+ability to manage the CA certificates themselves, which is not necessary, and
+thus not recommended.
+:::
+
+![Attaching Policies](./assets/aws-policies.png)
+
+Policies can either be attached to the user directly when you create it, or by
+assigning the user to a user group with the required permissions.
+
+:::note
+In AWS, the standard IAM policies grant sets of permissions that are commonly
+used together. If you wish to create your own policy for the Golioth integration,
+it'll need to be granted the following permissions:
+
+- Verify device certificates (required):
+  - `acm-pca:ListCertificateAuthorities`
+  - `acm-pca:GetCertificateAuthorityCertificate`
+- Performing certificate rotation (optional):
+  - `acm-pca:IssueCertificate`
+  - `acm-pca:GetCertificate`
+:::
+
+### 3. Create an access key
+
+Once the user is created with the required permissions, you'll need to create an
+access key that Golioth can use to authenticate as that user.
+
+Follow [the AWS
+documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-keys-admin-managed.html)
+for instructions on how to create an access key for an IAM user. Note that the
+secret access key is only available during the creation process, and must be
+saved before leaving the page.
+
+## Connecting to AWS from the Golioth Console
+
+Once you have an AWS IAM user with the required permissions, you can configure
+Golioth's connection to the AWS Private CA from the Golioth Console. Navigate to
+the PKI Providers section in the sidebar, and click **Add Provider**. In the
+modal window, select _AWS Private Certificate Authority_, and the correct region
+for your AWS instance. Add the Access Key ID and Secret Access Key that you
+created in the AWS Console, and click **Connect**. The provider will be added to
+the list of known providers, and a provider status check will run.
+
+If everything is configured correctly, the provider status should change to
+"Connected", and list the number of available certificate authorities.
+
+![Configured Provider](./assets/configured-provider.png)
+
+## Issuing Device Certificates
+
+Device certificates are [End Entity
+Certificates](https://docs.aws.amazon.com/privateca/latest/userguide/PcaIssueCert.html)
+in AWS.
+
+As outlined in the [Certificate ID section](./README.md#certificate-ids),
+the device certificate subject needs to include the following attributes:
+
+- `Organization`: the device's project ID
+- `CommonName`: a unique device certificate ID
+
+Other subject attributes are ignored.
+
+When performing certificate rotation, Golioth will submit certificate signing
+requests to the AWS Private CA with the
+[`EndEntityClientAuthCertificate_APIPassthrough/V1`
+template](https://docs.aws.amazon.com/privateca/latest/userguide/template-definitions.html#EndEntityClientAuthCertificate_APIPassthrough).
+The request will be submitted with an API passthrough value containing the
+subject attributes above.