proposal: crypto/x509: add functions for working with TBS certificates and revocation lists

[mcpherrinm]

Proposal Details

Golang’s crypto/x509 library is widely used in the WebPKI. As a certificate authority, it would be helpful if there was support for handling the “To Be Signed” portion of a certificate. While crypto/x509.Certificate exposes it as the RawTBSCertificate field today, there is no first-class support for handling a TBSCertificate as an in-memory structure, creating a serialized TBSCertificate from a struct, or parsing a DER TBSCertificate to a struct.

Currently, the ecosystem uses workarounds including signing certificates with throwaway keys or fixed dummy signatures, using forks of crypto/x509, or reimplementing parts of certificate parsing or encoding. While this works, it feels like something we could make better. This problem space may feel niche, but being able to operate on a certificate’s TBS is relatively important for a certificate authority. In particular, we want to run linters on the DER encoded TBS before signing. We want to log the TBS before signing it. And we want to be able to parse the stored TBS, whether for writing linters or just inspecting logged data.

All of the code required is in x509/crypto today, but isn’t public. I’ve prototyped the refactoring required in https://github.com/mcpherrinm/x509TBS to make sure this works. I think the most controversial part of this proposed API is going to be the signature algorithms in the APIs here, so I’m at least initially just taking what makes the implementation straightforward and open for alternate options.

Looking forward, exposing CreateTBSCertificate with the correct pkix.AlgorithmIdentifier (id-alg-mtcProof) will allow creating Merkle Tree Certificates without the rest of crypto/x509 needing to be aware of their format.

Specifications

Add the following functions to crypto/x509:

Three functions which create a TBS (Certificate, and Certificate Revocation List), refactored out of the existing CreateCertificate and CreateRevocationList functions:

func CreateTBSCertificate(rand io.Reader, template, parent *Certificate, pub any, signatureAlgorithm pkix.AlgorithmIdentifier) ([]byte, error)

func CreateTBSRevocationList(template *RevocationList, issuer *Certificate, signatureAlgorithm pkix.AlgorithmIdentifier) ([]byte, error)

Three matching Parse functions:

func ParseTBSCertificate(der []byte) (*Certificate, error)

func ParseTBSRevocationList(der []byte) (*RevocationList, error)

And a SignTBS function, which can be used to sign any of the two TBS types. Note this isn’t the same as current private signTBS function, as that doesn’t include serializing the result into DER.

func SignTBS(rand io.Reader, tbs []byte, signatureAlgorithm SignatureAlgorithm, algorithmIdentifier pkix.AlgorithmIdentifier, key crypto.Signer) ([]byte, error)

[ianlancetaylor]

CC @golang/security

[gabyhelp]

Related Issues

• crypto/x509: add ParseRevocationList, deprecate ParseCRL & ParseDERCRL #50674 (closed)
• proposal: x/crypto/ocsp: support request and response extensions #20001 (closed)
• proposal: x/crypto/ocsp: Export `certID` and the code that populates it #59284 (closed)
• proposal: x/crypto/ocsp: Return ocsp.Request from CreateRequest instead of []byte #37219

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[AGWA]

Is there a use case for working with TBS Certificate Requests? If they're only in the proposal for symmetry, I think they should be removed - CSRs are bad and we should try to limit additional APIs for working with them.

Can't the pkix.AlgorithmIdentifier be derived from template.SignatureAlgorithm and the public key (parent.PublicKey, issuer.PublicKey, pub)?

The Parse functions return the existing types - I presume that the Raw and Signature fields are left nil?

SignTBS would presumably allow the creation of a certificate/CRL/CSR whose inner signature algorithm doesn't match its outer signature algorithm. I think that's too much of a footgun for the standard library, and there should be separate functions for each type so the caller doesn't need to specify the signature algorithm again.

While I think the Parse functions would stand the test of time, MTCs are going to require new issuance flows and I'm not sure that CreateTBSCertificate and SignTBS would be the optimal API.¹ That makes me think it would be a bad idea to add them to the standard library.

Footnotes

1. Spitballing, I think you'd want CreateTBSCertificate to return a *x509.Certificate (with nil Raw and Signature) rather than []byte, and have methods on *x509.Certificate to create a MerkleTreeCertEntry, a standalone certificate, and landmark-relative certificates. ↩

[mcpherrinm]

Yes, I only included Certificate Request because it's essentially the same as the other two. I would be happy to exclude it, and will edit the original post to remove it now.

Yes, I was assuming Raw and Signature would be nil.

Merkle Tree Certificates are a big part of what is driving our desire to have this now: It would allow us to use CreateTBSCertifciate to handle most of the encoding of the certificate, passing in id-alg-mtcProof as the AlgorithmIdentifier. We wouldn't use SignTBS in that codepath because we need to construct the MTCSignature. The two formats (standalone and landmark-relative) share their TBS identically, so we'd just sign it twice.

In order to make that work, we do need to pass in our own AlgorithmIdentifier to CreateTBSCertificate. Otherwise, we don't need any additional support from crypto/x509.

I think there's definitely options for reducing the SignatureAlgorithm / pkix.AlgorithmIdentifier, but I decided to start out with the simplest option, which is just passing them in where they're needed.

If others think SignTBS allowing users to hold it wrong isn't safe enough, it would be easy enough for us to do that outside of crypto/x509, too. I think that isn't a huge problem in my view, as there's plenty of other ways to create invalid certificates, and this wouldn't exactly be a subtle problem.

[AGWA]

If #76133 is accepted, that could be used to set the MTC signature algorithm via template.

How are you planning to create the MerkleTreeCertEntry?

[mcpherrinm]

The TBSCertificateLogEntry in a MerkleTreeCertEntry in the log needs to match exactly to the TBSCertificate in the MTC, and so I expect it might be computed as a transformation of the TBSCertificate.

That would look something like pulling the encoded fields (version, issuer, validity, subject, extensions) out directly, computing spkiHash, and then reassembling into a TBSCertificateLogEntry. That should be relatively straightforward with cryptobyte, as it's just operating on the top level asn.1 structure.

[AGWA]

Make sense. Doesn't seem like there's any benefit to having CreateTBSCertificate return *x509.Certificate so I retract my spitball about that.

Assuming #76133 is accepted and CreateTBSCertificate honors template.RawSignatureAlgorithm, would the following API satisfy your needs:

func CreateTBSCertificate(rand io.Reader, template, parent *Certificate, pub any) ([]byte, error)
func CreateTBSRevocationList(template *RevocationList, issuer *Certificate) ([]byte, error)

func ParseTBSCertificate(der []byte) (*Certificate, error)
func ParseTBSRevocationList(der []byte) (*RevocationList, error)

I think the above API would be safe to use and reasonably future-proof.

[mcpherrinm]

Yes, I think that should work.