alg_id: include der2ascii output in docs

The intention here is to make it easy to cross-reference these values with other sources of information, and to "lift the veil" on what these things actually are and are not. Some of these are trivial (ed25519) while others reveal their true horror (RSA-PSS). For the latter, include a reference to their defining RFC, and decorate the context-specific fields with their name in comments.
rustls · Dec 23, 2024 · 47ee598 · 47ee598
1 parent 955b2dc
commit 47ee598
Showing 1 changed file with 195 additions and 0 deletions.
diff --git a/src/alg_id.rs b/src/alg_id.rs
@@ -8,42 +8,122 @@ use super::AlgorithmIdentifier;
 // See src/data/README.md.
 
 /// AlgorithmIdentifier for `id-ecPublicKey` with named curve `secp256r1`.
+///
+/// This is:
+///
+/// ```text
+/// # ecPublicKey
+/// OBJECT_IDENTIFIER { 1.2.840.10045.2.1 }
+/// # secp256r1
+/// OBJECT_IDENTIFIER { 1.2.840.10045.3.1.7 }
+/// ```
 pub const ECDSA_P256: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-ecdsa-p256.der"));
 
 /// AlgorithmIdentifier for `id-ecPublicKey` with named curve `secp384r1`.
+///
+/// This is:
+///
+/// ```text
+/// # ecPublicKey
+/// OBJECT_IDENTIFIER { 1.2.840.10045.2.1 }
+/// # secp384r1
+/// OBJECT_IDENTIFIER { 1.3.132.0.34 }
+/// ```
 pub const ECDSA_P384: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-ecdsa-p384.der"));
 
 /// AlgorithmIdentifier for `id-ecPublicKey` with named curve `secp521r1`.
+///
+/// This is:
+///
+/// ```text
+/// # ecPublicKey
+/// OBJECT_IDENTIFIER { 1.2.840.10045.2.1 }
+/// # secp521r1
+/// OBJECT_IDENTIFIER { 1.3.132.0.35 }
+/// ```
 pub const ECDSA_P521: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-ecdsa-p521.der"));
 
 /// AlgorithmIdentifier for `ecdsa-with-SHA256`.
+///
+/// This is:
+///
+/// ```text
+/// # ecdsa-with-SHA256
+/// OBJECT_IDENTIFIER { 1.2.840.10045.4.3.2 }
+/// ```
 pub const ECDSA_SHA256: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-ecdsa-sha256.der"));
 
 /// AlgorithmIdentifier for `ecdsa-with-SHA384`.
+///
+/// This is:
+///
+/// ```text
+/// # ecdsa-with-SHA384
+/// OBJECT_IDENTIFIER { 1.2.840.10045.4.3.3 }
+/// ```
 pub const ECDSA_SHA384: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-ecdsa-sha384.der"));
 
 /// AlgorithmIdentifier for `ecdsa-with-SHA512`.
+///
+/// This is:
+///
+/// ```text
+/// # ecdsa-with-SHA512
+/// OBJECT_IDENTIFIER { 1.2.840.10045.4.3.4 }
+/// ```
 pub const ECDSA_SHA512: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-ecdsa-sha512.der"));
 
 /// AlgorithmIdentifier for `rsaEncryption`.
+///
+/// This is:
+///
+/// ```text
+/// # rsaEncryption
+/// OBJECT_IDENTIFIER { 1.2.840.113549.1.1.1 }
+/// NULL {}
+/// ```
 pub const RSA_ENCRYPTION: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-rsa-encryption.der"));
 
 /// AlgorithmIdentifier for `sha256WithRSAEncryption`.
+///
+/// This is:
+///
+/// ```text
+/// # sha256WithRSAEncryption
+/// OBJECT_IDENTIFIER { 1.2.840.113549.1.1.11 }
+/// NULL {}
+/// ```
 pub const RSA_PKCS1_SHA256: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-rsa-pkcs1-sha256.der"));
 
 /// AlgorithmIdentifier for `sha384WithRSAEncryption`.
+///
+/// This is:
+///
+/// ```text
+/// # sha384WithRSAEncryption
+/// OBJECT_IDENTIFIER { 1.2.840.113549.1.1.12 }
+/// NULL {}
+/// ```
 pub const RSA_PKCS1_SHA384: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-rsa-pkcs1-sha384.der"));
 
 /// AlgorithmIdentifier for `sha512WithRSAEncryption`.
+///
+/// This is:
+///
+/// ```text
+/// # sha512WithRSAEncryption
+/// OBJECT_IDENTIFIER { 1.2.840.113549.1.1.13 }
+/// NULL {}
+/// ```
 pub const RSA_PKCS1_SHA512: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-rsa-pkcs1-sha512.der"));
 
@@ -52,6 +132,42 @@ pub const RSA_PKCS1_SHA512: AlgorithmIdentifier =
 /// - hashAlgorithm: sha256
 /// - maskGenAlgorithm: mgf1 with sha256
 /// - saltLength: 32
+///
+/// This is:
+///
+/// ```text
+/// # rsassa-pss
+/// OBJECT_IDENTIFIER { 1.2.840.113549.1.1.10 }
+/// SEQUENCE {
+///   # hashAlgorithm:
+///   [0] {
+///     SEQUENCE {
+///       # sha256
+///       OBJECT_IDENTIFIER { 2.16.840.1.101.3.4.2.1 }
+///       NULL {}
+///     }
+///   }
+///   # maskGenAlgorithm:
+///   [1] {
+///     SEQUENCE {
+///       # mgf1
+///       OBJECT_IDENTIFIER { 1.2.840.113549.1.1.8 }
+///       SEQUENCE {
+///         # sha256
+///         OBJECT_IDENTIFIER { 2.16.840.1.101.3.4.2.1 }
+///         NULL {}
+///       }
+///     }
+///   }
+///   # saltLength:
+///   [2] {
+///     INTEGER { 32 }
+///   }
+/// }
+/// ```
+///
+/// See <https://datatracker.ietf.org/doc/html/rfc4055#section-3.1> for
+/// the meaning of the context-specific tags.
 pub const RSA_PSS_SHA256: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-rsa-pss-sha256.der"));
 
@@ -60,6 +176,42 @@ pub const RSA_PSS_SHA256: AlgorithmIdentifier =
 /// - hashAlgorithm: sha384
 /// - maskGenAlgorithm: mgf1 with sha384
 /// - saltLength: 48
+///
+/// This is:
+///
+/// ```text
+/// # rsassa-pss
+/// OBJECT_IDENTIFIER { 1.2.840.113549.1.1.10 }
+/// SEQUENCE {
+///   # hashAlgorithm:
+///   [0] {
+///     SEQUENCE {
+///       # sha384
+///       OBJECT_IDENTIFIER { 2.16.840.1.101.3.4.2.2 }
+///       NULL {}
+///     }
+///   }
+///   # maskGenAlgorithm:
+///   [1] {
+///     SEQUENCE {
+///       # mgf1
+///       OBJECT_IDENTIFIER { 1.2.840.113549.1.1.8 }
+///       SEQUENCE {
+///         # sha384
+///         OBJECT_IDENTIFIER { 2.16.840.1.101.3.4.2.2 }
+///         NULL {}
+///       }
+///     }
+///   }
+///   # saltLength:
+///   [2] {
+///     INTEGER { 48 }
+///   }
+/// }
+/// ```
+///
+/// See <https://datatracker.ietf.org/doc/html/rfc4055#section-3.1> for
+/// the meaning of the context-specific tags.
 pub const RSA_PSS_SHA384: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-rsa-pss-sha384.der"));
 
@@ -68,9 +220,52 @@ pub const RSA_PSS_SHA384: AlgorithmIdentifier =
 /// - hashAlgorithm: sha512
 /// - maskGenAlgorithm: mgf1 with sha512
 /// - saltLength: 64
+///
+/// This is:
+///
+/// ```text
+/// # rsassa-pss
+/// OBJECT_IDENTIFIER { 1.2.840.113549.1.1.10 }
+/// SEQUENCE {
+///   # hashAlgorithm:
+///   [0] {
+///     SEQUENCE {
+///       # sha512
+///       OBJECT_IDENTIFIER { 2.16.840.1.101.3.4.2.3 }
+///       NULL {}
+///     }
+///   }
+///   # maskGenAlgorithm:
+///   [1] {
+///     SEQUENCE {
+///       # mgf1
+///       OBJECT_IDENTIFIER { 1.2.840.113549.1.1.8 }
+///       SEQUENCE {
+///         # sha512
+///         OBJECT_IDENTIFIER { 2.16.840.1.101.3.4.2.3 }
+///         NULL {}
+///       }
+///     }
+///   }
+///   # saltLength:
+///   [2] {
+///     INTEGER { 64 }
+///   }
+/// }
+/// ```
+///
+/// See <https://datatracker.ietf.org/doc/html/rfc4055#section-3.1> for
+/// the meaning of the context-specific tags.
 pub const RSA_PSS_SHA512: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-rsa-pss-sha512.der"));
 
 /// AlgorithmIdentifier for `ED25519`.
+///
+/// This is:
+///
+/// ```text
+/// # ed25519
+/// OBJECT_IDENTIFIER { 1.3.101.112 }
+/// ```
 pub const ED25519: AlgorithmIdentifier =
     AlgorithmIdentifier::from_slice(include_bytes!("data/alg-ed25519.der"));