From d3722779a1ae228718bda15a93b9385721297ce8 Mon Sep 17 00:00:00 2001 From: Joe Birr-Pixton Date: Mon, 23 Dec 2024 13:01:32 +0000 Subject: [PATCH] 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. --- src/alg_id.rs | 195 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) diff --git a/src/alg_id.rs b/src/alg_id.rs index 6c39b19..637027d 100644 --- 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 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 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 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"));