WIP: Signed pipelines guide docs

pages/agent/v3/signed_pipelines.md

@@ -0,0 +1,59 @@
+# Signed Pipelines
+
+## What are Signed Sipelines?
+
+Signed Pipelines is a security feature on the Buildkite Agent that allows you to cryptographically sign steps that are uploaded Buildkite, and then verify that signature on the Buildkite Agent before running the step. This can prevent a malicious actor from modifying the steps that are run on your agents, especially in the (hopefully unlikely) event that the Buildkite backend is compromised.
+
+These signatures mean that while a threat actor could modify jobs in flight, when the Agent runs those steps, when it tries to verify the signature, it will fail, and the step will not be run.
+
+## Enabling signed pipelines on your pipelines
+
+Behind the scenes, Signed Pipelines uses [JSON Web Signing (JWS)](https://datatracker.ietf.org/doc/html/rfc7797) to generate its signatures. This means that you'll need to generate a [JSON Web Key Set (JWKS)](https://datatracker.ietf.org/doc/html/rfc7517) to sign and verify your pipelines with.
+
+### How do I generate a key pair?
+
+Luckily, the Buildkite Agent has you covered! There's a JWKS generation tool built into the agent, which you can use to generate a key pair for you. To run it, you'll need to [install the agent on your machine](/docs/agent/v3/installation), and then run:
+```bash
+buildkite-agent tool keygen --alg <algorithm> --key-id <key-id>
+```
+
+replacing `<algorithm>` and `<key-id>` with the algorithm you want to use, and the key ID you want to use. For example, to generate an RSA-PSS key pair with a key ID of `my-key-id`, you'd run:
+```bash
+buildkite-agent tool keygen --alg PS256 --key-id my-key-id
+```
+
+The agent will then generate two JSON Web Keysets for you, one public and one private, and output them to files in the current directory. You can then use these keys to sign and verify your pipelines.
+
+If no key id is provided, the agent will generate a random one for you.
+
+Note that the value of `--alg` must be a valid [JSON Web Signing Algorithm](https://datatracker.ietf.org/doc/html/rfc7518#section-3). Note that the agent does not support the `none` algorithm, or any signature algorithms in the `RS` series (such as `RS256` - signing algorithms that use RSASSA-PKCS1 v1.5 signatures).
+
+<details>
+  <summary>Why doesn't the agent support RSASSA-PKCS1 v1.5 signatures?</summary>
+  In short, it's because RSASSA-PKCS1 v1.5 signatures are generally regarded to be less secure than the newer RSA-PSS signatures. While RSASSA-PKCS1 v1.5 signatures are still largely known to be relatively secure, we want to encourage our users to use the most secure algorithms possible, so when using RSA keys, we only support RSA-PSS signatures. We also recommend looking into ECDSA and EdDSA signatures, which are generally regarded to be more secure than RSA signatures.
+</details>
+
+### What algorithm should I use?
+
+Signed Pipelines supports a number of different signing algorithms, which can largely be broken down into two categories: Symmetric Signing Algorithms (where signing and verification use the same keys), and Asymmetric Signing Algorithms (where signing and verification use different keys).
+
+The TL;DR: We recommend using an asymmetric signing algorithm, and basically any of the asymmetric signing algorithms we support are fine and will be secure. If you're not sure which one to use, `EdDSA` is proven to be secure [ed: fact check this], and produces nice short signatures.
+
+#### Symmetric Signing Algorithms
+
+For symmetric signing algorithms, we support the following algorithms:
+- `HS256`
+- `HS384`
+- `HS512`
+
+
+
+
+
+### Making your agents sign steps they upload 
+
+### Signing the initial steps for your pipeline
+
+### Hard Mode: Static Signatures
+
+## Rotating signing keys