Release Summary:

Add new s2n_connection_get_signature_scheme method to retrieve the IANA description of the server signature scheme

Resolved issues:

Description of changes:

Add a getter for signature_schemes, modeled after s2n_connection_get_key_exchange_group.

This meets a customer request for easier logging, specifically for PQ signatures (MLDSA). That means that the customer is primarily interested in actual, official TLS1.3 signature schemes.

Call-outs:

How should we handle non-IANA signature schemes?

We could:

1. Error if no official signature scheme
2. Return a combo of "signature algorithm" and "hash algorithm"

I went with 2. I worry that 1 would be awkward for customers to use. The primary use case for this API is for logging, but 1 would probably require checking the actual protocol version every time you perform the logging to avoid errors. Since TLS1.2 can also sometimes choose an official signature scheme, the behavior might be even more confusing and inconsistent if we didn't always treat actual_protocol_version<S2N_TLS13 as an error.

How should we format non-IANA signature scheme names?

We could use:

1. "<signature_algorithm>+<hash_algorithm>"
2. "legacy_<signature_algorithm>_<hash_algorithm>"
3. "legacy_<signature_algorithm, with '_pkcs1' if 'rsa'>_<hash_algorithm>"

I went with 2. I think the "legacy" in front is a clear indicator for non-IANA names.

I initially liked 1, but I think seeing it appear in policy snapshots made how odd it would look very clear:

- rsa_pkcs1_sha384
- rsa_pkcs1_sha512
- rsa+sha224
- ecdsa_sha256
- ecdsa_sha384
- ecdsa_sha512
- ecdsa+sha224
- rsa_pkcs1_sha1
- ecdsa_sha1

To me, it's jarring to see the random "+" but also simultaneously not obvious that the "+" indicates non-IANA / legacy.

Our names currently follow 3. I like how that matches the official names, but I worry that's not well defined enough: it's easier to say "combine the IANA descriptions of the signature algorithm and hash algorithm" than "combine the IANA descriptions of the signature algorithm and hash algorithm, and append _pkcsa1 to any rsa signature algorithms". Like documenting that would probably get confusing. We'll need to merge #5472 first if we want 2 instead of 3.

How should we handle no signature at all?

No signature scheme will be chosen if no signature is used, such as for session resumption. In that case, we could:

1. Treat it as an error.
2. Return NULL
3. Return "none"

I'd vote for "none". NULL also seems reasonable, but I worry about the usual issues around handling unexpected NULLs. And if a customer was using this method for logging / metrics, they'd still probably need to map NULL -> "none".

I really don't want to treat it as an error because that will make the method very hard to use. Customers shouldn't need to determine whether their connection negotiated a signature scheme or not in order to call this method or handle its errors.

Testing:

New unit tests.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.