Private Key Serialization

[bnewbold]

This is a note about a common/default way to serialize/deserialize private (secret) cryptographic keys in the atproto ecosystem. This is loosely normative, not a firm part of the protocol, but could be helpful for interop or for when folks just need a default way to solve this need.

Private keys are not always "exportable" (bytes available), but when they are, they often need to be serialized to a string to be included in a secrets manager, environment variable, etc. They are not transmitted as part of the protocol, which is why there isn't a serialization format already specified.

Some encodings commonly used for this task are:

• simple hex encoding. does not include any indication of what key type has been encoded (eg, P-256 or K-256). this is what the atproto PDS implementation does today, including for sandbox environment
• JWK, a JSON format for cryptographic keys from the JWT ecosystem. includes metadata, but somewhat verbose, flexible, and can require special processing to get key material (splits keys in to parts or points). the indigo golang codebase uses this encoding a bit
• custom base64 or other string encodings. usually with no metadata

We are planning to migrate to multibase encoding, similar to how public keys are encoded in multiple places in atproto already. These result in simple strings, and contain metadata about the key type (P-256 vs K-256), and that the key is a secret key not a public key (important to head off machine confusion and parsing errors).

If needed we'll provide conversion tools and a compatibility period for sandbox PDS instances specifically. We don't have any particular urgency or timeline for this, just communicating the intention to do things this way at some point.