Update Fulcio certificate issuance doc (sigstore#219)

* Update Fulcio certificate issuance doc

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

* Update wording of security model for Fulcio

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

content/en/fulcio/certificate-issuing-overview.md

@@ -11,19 +11,29 @@ This page will walk through the process of issuing a code signing certificate fr
 
 ![Fulcio certificate request input](/fulcio-1-certificate-request-input.png)
 
-As a first step, the client submits a certificate request to Fulcio. This certificate request contains three items:
-
-- An OIDC identity token, which is constructed as a JWT (JSON web token) containing information about the principal (identity of our client), the issuer (who verified this identity), and related metadata.
-- The public key, which is the public half of an asymmetric key-pair generated by the client. The public key will be embedded in the final x509 certificate if this request is successful.
-- A challenge which proves the client is in possession of the private key that corresponds to the public key provided. This challenge is created by signing the subject portion of the OIDC ID token.
+As a first step, the client submits a certificate request to Fulcio. This certificate request contains the following:
+
+- An OpenID Connect (OIDC) identity token. This is a signed JWT containing information about the
+  principal (identity of the client), the issuer (who issued the identity token -
+  Google, Microsoft, GitHub, etc.) and additional metadata such as expiration. The princaipl identity
+  can either be a maintainer identity in the form of an email, or a workload identity.
+- The public key. This is the public portion of a cryptographic key pair generated
+  by the client. The public key will be embedded in the issued X.509 certificate.
+- A signed challenge. This challenge proves the client is in possession of the private
+  key that corresponds to the public key provided. The challenge is created by
+  signing the subject (`sub`) of the OIDC identity token.
+- Alternatively, instead of a public key and signed challenge, a client can provide a certificate
+  signing request (CSR), which also provides a proof of possession and the public key.
+
+See the [service definition](https://github.com/sigstore/fulcio/blob/main/fulcio.proto) for more details.
 
 ## 2 — Authentication
 
 ![Fulcio authentication](/fulcio-2-authentication.png)
 
 Authenticating the OIDC ID token begins the processing of the certificate request.
 
-To authorize the token, Fulcio must:
+To authenticate the token, Fulcio must:
 
 - Use the issuer claim from the token to find the issuer's OIDC discovery endpoint
 - Download the issuer's signing keys from the discovery endpoint
@@ -33,43 +43,73 @@ To authorize the token, Fulcio must:
 
 ![Fulcio verifying the challenge](/fulcio-3-verify-the-challenge.png)
 
-Once the client has been authenticated, the next step is to verify that the client is in possession of the private key of the public key they’ve submitted. To do this, we must verify the challenge. This is a signature of the subject identifier — or sub — claim that allows for the verification of the signature using the public key supplied.
+Once the client has been authenticated, the next step is to verify the client
+is in possession of the private key of the public key they’ve submitted. To do
+this, Fulcio verifies the signed challenge or CSR. For a signed challenge, this is
+a signature of the `sub` claim. For challenge and CSR are verified using the provided public key.
 
 ## 4 — Constructing a certificate
 
 ![Fulcio issue the certificate](/fulcio-4-issue-certificate.png)
 
-The client is now authorized and has proven that they own their private key, so a code signing certificate can be issued.
+The client is now authenticated and has proved possession of the private key. Fulcio now
+can issue a code signing certificate for the identity from the ID token.
 
-At a high level this process involves:
+At a high level, this process involves:
 
 - Embedding the provided public key in the certificate
-- Setting the subject alternative names to match the sub claim from the OIDC ID token
-- Setting various other customer x509 extensions depending on the metadata in the OIDC ID token claims 
+- Setting the certificate's subject alternative name (who the certificate is issued for) to
+  match the subject from the OIDC ID token. This could be an email, SPIFFE ID, or GitHub Actions workflow identity.
+- Including the OIDC ID token issuer in a custom field in the certificate
+- Setting various X.509 extensions depending on the metadata in
+  the OIDC ID token claims (e.g GitHub Actions workflow information)
 
 ## 5 — Signing the certificate
 
 ![Fulcio signing the certificate](/fulcio-5-sign-certificate.png)
 
-The code signing certificate is now complete in detail, but needs to be signed by the certificate authority so that it becomes connected to Fulcio's chain of trust.
+The code signing certificate is now populated, but needs to be signed
+by the certificate authority. This will form a chain of trust from the issued
+certificate to the certificate authority root certificate.
+
+
+Fulcio supports several signing backends to sign certificates:
+
+- KMS: A KMS key hosted on GCP, AWS, Azure or Hashicorp
+- [Tink](https://github.com/google/tink): A secure KMS-encrypted Tink keyset created with [tinkey](https://github.com/google/tink/blob/master/docs/TINKEY.md)
+- PKCS#11: This works with any PKCS#11 devices including AWS CloudHSM,
+  [softHSM](https://www.opendnssec.org/softhsm/) and others
+- [Google CA Service](https://cloud.google.com/certificate-authority-service/docs): A GCP-hosted certificate authority
+- Files: An on-disk password-protected private key
+- Ephemeral (for testing): An in-memory key pair generated on start up 
+
+See [Setting up a Fulcio instance](https://github.com/sigstore/fulcio/blob/main/docs/setup.md) for more details.
 
-Fulcio supports several certificate authority backends:
+## 6 — Certificate Transparency log inclusion
 
-- PKCS#11: This works with any PKCS#11 devices including AWS CloudHSM, [softHSM](https://www.opendnssec.org/softhsm/), and others
-- Google Private CA: A hosted certificate authority created by Google Cloud Platform
-- Files: A private key and certificate on disk
-- Ephemeral: An in-memory key-pair generated on start up 
+As part of certificate issuance, the certificate will be appended to an immutable, append-only,
+cryptographically verifiable certificate transparency (CT) log, which allows for issuance to be
+publicly auditable.
 
-## 6 — Certificate Transparency log upload
+A special X.509 extension, called a poison extension, is included in the certificate before it
+is appended to the log. This certificate is called a precertificate, and is not yet usuable by clients.
 
 ![Fulcio upload the certificate to the transparency log](/fulcio-6-transparency-log-upload.png)
 
-Once the certificate is signed, there is one final task to complete before returning the certificate to the client: it must be uploaded to a certificate transparency log.
+The certificate transparency log returns a _Signed Certificate Timestamp_
+(SCT). The SCT is a promise of inclusion in the log, signed by the CT log. It can be
+verified without accessing the log, though a client can also request a cryptographic proof
+of inclusion directly from the log.
 
-The certificate transparency log returns a _Signed Certificate Timestamp_ (SCT), which indicates the log index for the certificate, a timestamp of when it was included, and this is all signed by the certificate transparency log.
+The SCT is embedded within the certificate, and signed again.
 
-## 7 — Return certificate to client
+![Fulcio signs a certificate with the embedded SCT](/fulcio-7-sign-certificate-sct.png)
+
+Note that the Certificate Transparency (CT) log is separate from the [Rekor](https://github.com/sigstore/rekor)
+transparency log. Fulcio's CT Log only stores issued certificates, while Rekor stores artifact signatures and attestations.
 
-![Fulcio return the certificate to the client](/fulcio-7-return-to-client.png)
+See [Certificate Transparency Log Information](https://github.com/sigstore/fulcio/blob/main/docs/ctlog.md) for more details.
+
+## 7 — Return certificate to client
 
-Finally, both the certificate and the SCT are returned to the client!
+![Fulcio return the certificate to the client](/fulcio-8-return-to-client.png)

content/en/fulcio/overview.md

@@ -7,10 +7,10 @@ position: 201
 
 ![Fulcio Overview](/sigstore_fulcio-horizontal-color.svg)
 
-Fulcio is a free code signing Certificate Authority, built to make short-lived certificates available to anyone. Based on an Open ID Connect email address, Fulcio signs x509 certificates valid for under 20 minutes.
+Fulcio is a free code signing Certificate Authority, built to make short-lived certificates available to anyone. Based on an OpenID Connect email address, Fulcio signs X.509 certificates valid for 10 minutes.
 
-Fulcio was designed to run as a centralized, public-good instance backed up by other transparency logs. Development is now underway to support different delegation models, and to deploy and run Fulcio as a disconnected instance.
+Fulcio was designed to run as a centralized, public-good instance, auditable by a certificate transparency log. Fulcio can also be deployed as a self-hosted service.
 
 Fulcio is being developed as part of the sigstore project. Join us on our [Slack channel](https://sigstore.slack.com/) (need an [invite](https://links.sigstore.dev/slack-invite)?)
 
-You can learn more about Fulcio in the [Fulcio repo](https://github.com/sigstore/fulcio) and the [repo docs](https://github.com/sigstore/fulcio/tree/6ac6b8c94c3ec6106d68c0f92225016a3a6eef79/docs). 
+You can learn more about Fulcio in the [Fulcio repo](https://github.com/sigstore/fulcio) and the [repo docs](https://github.com/sigstore/fulcio/tree/main/docs). 

content/en/security.md

@@ -39,12 +39,12 @@ One of the targets secured by the Sigstore Trust Root is the Fulcio root certifi
 
 **Certificate Transparency Log**
 
-Fulcio assumes that a valid OIDC token from a trusted provider is sufficient “proof of ownership” of the associated identity.  To help protect against OIDC compromise, Fulcio uses an append-only certificate transparency log. This means:
+Fulcio assumes that a valid OIDC token from a trusted provider is sufficient “proof of ownership” of the associated identity. To mitigate against OIDC compromise, Fulcio appends certificates to an immutable, append-only cryptographically verifiable transparency log. This means:
 
 * Fulcio MUST publish all certificates to the log.
 * Clients MUST NOT trust certificates that are not in the log.
 
-As a result, users can detect any misissued certificates (detection). Combined with Rekor's signature transparency, artifacts signed with compromised accounts can be identified (auditability).
+As a result users can detect any mis-issued certificates, either due to the CA acting maliciously or a compromised OIDC identity provider. Combined with Rekor's signature transparency, artifacts signed with compromised accounts can be identified (auditability).
 
 _Note: Fulcio itself does not monitor the certificate transparency log; users are responsible for monitoring the log for unauthorized certificates issued to their identities._