docs: add security policy certificate preferences #4441
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
|
||
| The security policy struct contains three fields related to certificate preferences. These function differently from the other security policy fields because they are not sent to the peer as part of negotiation. Instead they are a set of rules that the endpoint will enforce locally. | ||
|
|
||
| `certificate_signature_preferences` determine which certificate signatures are allowed in certificates. This field is an allowlist of `(signature_algorithm, digest)` tuples. Allowed `signature_algorithm`s are ECDSA, RSA PKCS v1.5, and RSA PSS. Note that s2n-tls does not currently provide support for restricting the digest types of RSA PSS signature, so a security policy using certificate signature preferences must either allow all digests with RSA PSS signatures or disallow RSA PSS signatures entirely. |
There was a problem hiding this comment.
would it make sense to have these be the actual values, as in S2N_SIGNATURE_ECDSA, S2N_SIGNATURE_RSA_PSS_PSS, S2N_SIGNATURE_RSA_PSS_RSAE
|
|
||
| `certificate_signature_preferences` determine which certificate signatures are allowed in certificates. This field is an allowlist of `(signature_algorithm, digest)` tuples. Allowed `signature_algorithm`s are ECDSA, RSA PKCS v1.5, and RSA PSS. Note that s2n-tls does not currently provide support for restricting the digest types of RSA PSS signature, so a security policy using certificate signature preferences must either allow all digests with RSA PSS signatures or disallow RSA PSS signatures entirely. | ||
|
|
||
| `certificate_key_preferences` determine which key types are allowed in certificates. This field is an allowlist of `(key type, size)` tuples, where key type is the OID (Object Identifier) contained in the cert. Allowed RSA key types are `rsaEncryption` and `rsassaPSS` with 1024, 2048, 3072, and 4096 bit moduli. Allowed EC key types are `prime256v1`, `secp384r1`, and `secp521r1` with their respective sizes. |
There was a problem hiding this comment.
this looks different than what I see in the test_cert_key_preferences?
s2n-tls/tests/unit/s2n_security_policy_cert_preferences_test.c
Lines 80 to 81 in 91ad940
|
|
||
| Certificates received from a peer are validated after they have been parsed, but before any cryptographic verification has been done. These certificates will be validated even if they aren't used in the construction of the final cert chain. Note that certificate signature preferences are not enforced on self signed certs, because the signature of a self signed cert does not affect the security of the certificate chain. | ||
|
|
||
| Certificates in a trust store are only validated when are used to build a chain. For example, if the security policy certificate key preferences only allows 3096 bit RSA certs, the config could still load a system trust store that contains 2048 bit certs. However no connections will actually be able to use the non-compliant 2048 bit RSA certs, and they will be effectively untrusted by s2n-tls. |
There was a problem hiding this comment.
missing or extra word in "when are used to build a chain:
There was a problem hiding this comment.
comma after However
|
|
||
| Certificates in a trust store are only validated when are used to build a chain. For example, if the security policy certificate key preferences only allows 3096 bit RSA certs, the config could still load a system trust store that contains 2048 bit certs. However no connections will actually be able to use the non-compliant 2048 bit RSA certs, and they will be effectively untrusted by s2n-tls. | ||
|
|
||
| Certificates loaded into a config are only validated if the `certificate_preferences_apply_locally` field in the security policy is true. Validation happens when `s2n_connection_set_config` is called, or when `s2n_connection_set_cipher_preferences` is used to set a connection override. If the certificate loaded into the config are not permitted by the certificate preferences, then `s2n_connection_set_config` will fail. Note that certificate signature preferences are enforced on all certs loaded into the config, even if they are self signed. |
There was a problem hiding this comment.
Suggested change
| Certificates loaded into a config are only validated if the `certificate_preferences_apply_locally` field in the security policy is true. Validation happens when `s2n_connection_set_config` is called, or when `s2n_connection_set_cipher_preferences` is used to set a connection override. If the certificate loaded into the config are not permitted by the certificate preferences, then `s2n_connection_set_config` will fail. Note that certificate signature preferences are enforced on all certs loaded into the config, even if they are self signed. | |
| Certificates loaded into a config are only validated if the `certificate_preferences_apply_locally` field in the security policy is `true`. Validation happens when `s2n_connection_set_config` is called, or when `s2n_connection_set_cipher_preferences` is used to set a connection override. If the certificate loaded into the config are not permitted by the certificate preferences, then `s2n_connection_set_config` will fail. Note that certificate signature preferences are enforced on all certs loaded into the config, even if they are self signed. |
|
This PR has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description of changes:
Adds documentation for the certificate preferences fields in the security policy struct.
Call Outs:
I'm not 100% certain where this information should live. It feels a little odd to have information about the internals of security policies in the Usage Guide? Ideally customer's wouldn't have to directly look at security policies, but that feels like more of an aspirational goal than a realistic one.
Testing:
docs change, no testing. Although I do have a spell check extension installed in my IDE.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.