Struct cryptographic_message_syntax::SignerInfo

pub struct SignerInfo { /* private fields */ }

Represents a CMS SignerInfo structure.

This is a high-level interface to the SignerInfo ASN.1 type. It supports performing common operations against that type.

Instances of this type are logically equivalent to a single signed assertion within a SignedData payload. There can be multiple signers per SignedData, which is why this type exists on its own.

Implementations

impl SignerInfo

pub fn certificate_issuer_and_serial(&self) -> Option<(&Name, &Integer)>

Obtain the signing X.509 certificate’s issuer name and its serial number.

The returned value can be used to locate the certificate so verification can be performed.

pub fn digest_algorithm(&self) -> DigestAlgorithm

Obtain the message digest algorithm used by this signer.

pub fn signature_algorithm(&self) -> SignatureAlgorithm

Obtain the cryptographic signing algorithm used by this signer.

pub fn signature(&self) -> &[u8]

Obtain the raw bytes constituting the cryptographic signature.

This is the signature that should be verified.

Examples found in repository

src/lib.rs (line 569)

    pub fn verify_signature_with_signed_data_and_content(
        &self,
        signed_data: &SignedData,
        signed_content: &[u8],
    ) -> Result<(), CmsError> {
        let verifier = self.signature_verifier(signed_data.certificates())?;
        let signature = self.signature();

        verifier
            .verify(signed_content, signature)
            .map_err(|_| CmsError::SignatureVerificationError)
    }

pub fn signed_attributes(&self) -> Option<&SignedAttributes>

Obtain the SignedAttributes attached to this instance.

Examples found in repository

src/lib.rs (line 604)

    pub fn verify_message_digest_with_signed_data(
        &self,
        signed_data: &SignedData,
    ) -> Result<(), CmsError> {
        let signed_attributes = self
            .signed_attributes()
            .ok_or(CmsError::NoSignedAttributes)?;

        let wanted_digest: &[u8] = signed_attributes.message_digest.as_ref();
        let got_digest = self.compute_digest_with_signed_data(signed_data);

        // Susceptible to timing side-channel but we don't care per function
        // documentation.
        if wanted_digest == got_digest.as_ref() {
            Ok(())
        } else {
            Err(CmsError::DigestNotEqual)
        }
    }

    /// Verifies the message digest stored in signed attributes using explicit encapsulated content.
    ///
    /// Typically, the digest is computed over content stored in the [SignedData] instance.
    /// However, it is possible for the signed content to be external. This function
    /// allows you to define the source of that external content.
    ///
    /// Behavior is very similar to [SignerInfo::verify_message_digest_with_signed_data]
    /// except the original content that was digested is explicitly passed in. This
    /// content is appended with the signed attributes data on this [SignerInfo].
    ///
    /// The security limitations from [SignerInfo::verify_message_digest_with_signed_data]
    /// apply to this function as well.
    pub fn verify_message_digest_with_content(&self, data: &[u8]) -> Result<(), CmsError> {
        let signed_attributes = self
            .signed_attributes()
            .ok_or(CmsError::NoSignedAttributes)?;

        let wanted_digest: &[u8] = signed_attributes.message_digest.as_ref();
        let got_digest = self.compute_digest(Some(data));

        // Susceptible to timing side-channel but we don't care per function
        // documentation.
        if wanted_digest == got_digest.as_ref() {
            Ok(())
        } else {
            Err(CmsError::DigestNotEqual)
        }
    }

pub fn unsigned_attributes(&self) -> Option<&UnsignedAttributes>

Obtain the UnsignedAttributes attached to this instance.

Examples found in repository

src/lib.rs (line 708)

    pub fn time_stamp_token_signed_data(&self) -> Result<Option<SignedData>, CmsError> {
        if let Some(attrs) = self.unsigned_attributes() {
            if let Some(signed_data) = &attrs.time_stamp_token {
                Ok(Some(SignedData::try_from(signed_data)?))
            } else {
                Ok(None)
            }
        } else {
            Ok(None)
        }
    }

pub fn verify_signature_with_signed_data(
    &self,
    signed_data: &SignedData
) -> Result<(), CmsError>

Verifies the signature defined by this signer given a SignedData instance.

This function will perform cryptographic verification that the signature contained within this SignerInfo instance is valid for the content that was signed. The content that was signed is the encapsulated content from the SignedData instance (its .signed_data() value) combined with the SignedAttributes attached to this instance.

IMPORTANT SECURITY LIMITATIONS

This method only performs signature verification. It:

• DOES NOT verify the digest hash embedded within SignedAttributes (if present).
• DOES NOT validate the signing certificate in any way.
• DOES NOT validate that the cryptography used is appropriate.
• DOES NOT verify the time stamp token, if present.

See the crate’s documentation for more on the security implications.

Examples found in repository

src/lib.rs (line 741)

    pub fn verify_time_stamp_token(&self) -> Result<Option<()>, CmsError> {
        let signed_data = if let Some(v) = self.time_stamp_token_signed_data()? {
            v
        } else {
            return Ok(None);
        };

        if signed_data.signers.is_empty() {
            return Ok(None);
        }

        for signer in signed_data.signers() {
            signer.verify_signature_with_signed_data(&signed_data)?;
            signer.verify_message_digest_with_signed_data(&signed_data)?;
        }

        Ok(Some(()))
    }

pub fn verify_signature_with_signed_data_and_content(
    &self,
    signed_data: &SignedData,
    signed_content: &[u8]
) -> Result<(), CmsError>

Verifies the signature defined by this signer given a SignedData and signed content.

This function will perform cryptographic verification that the signature contained within this SignerInfo is valid for signed_content. Unlike Self::verify_signature_with_signed_data(), the content that was signed is passed in explicitly instead of derived from SignedData.

This is a low-level API that bypasses the normal rules for deriving the raw content a cryptographic signature was made over. You probably want to use Self::verify_signature_with_signed_data() instead. Also note that signed_content here may or may not be the encapsulated content which is ultimately signed.

This method only performs cryptographic signature verification. It is therefore subject to the same limitations as Self::verify_signature_with_signed_data().

Examples found in repository

src/lib.rs (line 546)

    pub fn verify_signature_with_signed_data(
        &self,
        signed_data: &SignedData,
    ) -> Result<(), CmsError> {
        let signed_content = self.signed_content_with_signed_data(signed_data);

        self.verify_signature_with_signed_data_and_content(signed_data, &signed_content)
    }

pub fn verify_message_digest_with_signed_data(
    &self,
    signed_data: &SignedData
) -> Result<(), CmsError>

Verifies the digest stored in signed attributes matches that of content in a SignedData.

If signed attributes are present on this instance, they must contain a message-digest attribute defining the digest of data that was signed. The specification says this digested data should come from the encapsulated content within SignedData (SignedData.signed_content()).

Note that some utilities of CMS will not store a computed digest in message-digest that came from SignedData or is using the digest algorithm indicated by this SignerInfo. This is strictly in violation of the specification but it does occur.

IMPORTANT SECURITY LIMITATIONS

This method only performs message digest verification. It:

• DOES NOT verify the signature over the signed data or anything about the signer.
• DOES NOT validate that the digest algorithm is strong/appropriate.
• DOES NOT compare the digests in a manner that is immune to timing side-channels.

See the crate’s documentation for more on the security implications.

Examples found in repository

src/lib.rs (line 742)

    pub fn verify_time_stamp_token(&self) -> Result<Option<()>, CmsError> {
        let signed_data = if let Some(v) = self.time_stamp_token_signed_data()? {
            v
        } else {
            return Ok(None);
        };

        if signed_data.signers.is_empty() {
            return Ok(None);
        }

        for signer in signed_data.signers() {
            signer.verify_signature_with_signed_data(&signed_data)?;
            signer.verify_message_digest_with_signed_data(&signed_data)?;
        }

        Ok(Some(()))
    }

pub fn verify_message_digest_with_content(
    &self,
    data: &[u8]
) -> Result<(), CmsError>

Verifies the message digest stored in signed attributes using explicit encapsulated content.

Typically, the digest is computed over content stored in the SignedData instance. However, it is possible for the signed content to be external. This function allows you to define the source of that external content.

Behavior is very similar to SignerInfo::verify_message_digest_with_signed_data except the original content that was digested is explicitly passed in. This content is appended with the signed attributes data on this SignerInfo.

The security limitations from SignerInfo::verify_message_digest_with_signed_data apply to this function as well.

pub fn signature_verifier<'a, C>(
    &self,
    certs: C
) -> Result<UnparsedPublicKey<Vec<u8>>, CmsError>where
    C: Iterator<Item = &'a CapturedX509Certificate>,

Obtain an entity for validating the signature described by this instance.

This will attempt to locate the certificate used by this signing info structure in the passed iterable of certificates and then construct a signature verifier that can be used to verify content integrity.

If the certificate referenced by this signing info could not be found, an error occurs.

If the signing key’s algorithm or signature algorithm aren’t supported, an error occurs.

Examples found in repository

src/lib.rs (line 568)

    pub fn verify_signature_with_signed_data_and_content(
        &self,
        signed_data: &SignedData,
        signed_content: &[u8],
    ) -> Result<(), CmsError> {
        let verifier = self.signature_verifier(signed_data.certificates())?;
        let signature = self.signature();

        verifier
            .verify(signed_content, signature)
            .map_err(|_| CmsError::SignatureVerificationError)
    }

pub fn time_stamp_token_signed_data(
    &self
) -> Result<Option<SignedData>, CmsError>

Resolve the time-stamp token SignedData for this signer.

The time-stamp token is a SignedData ASN.1 structure embedded as an unsigned attribute. This is a convenience method to extract it and turn it into a SignedData.

Returns Ok(Some) on success, Ok(None) if there is no time-stamp token, and Err if there is a parsing error.

Examples found in repository

src/lib.rs (line 730)

    pub fn verify_time_stamp_token(&self) -> Result<Option<()>, CmsError> {
        let signed_data = if let Some(v) = self.time_stamp_token_signed_data()? {
            v
        } else {
            return Ok(None);
        };

        if signed_data.signers.is_empty() {
            return Ok(None);
        }

        for signer in signed_data.signers() {
            signer.verify_signature_with_signed_data(&signed_data)?;
            signer.verify_message_digest_with_signed_data(&signed_data)?;
        }

        Ok(Some(()))
    }

pub fn verify_time_stamp_token(&self) -> Result<Option<()>, CmsError>

Verify the time-stamp token in this instance.

The time-stamp token is a SignedData ASN.1 structure embedded as an unsigned attribute. So this method reconstructs that data structure and effectively calls SignerInfo::verify_signature_with_signed_data and SignerInfo::verify_message_digest_with_signed_data.

Returns Ok(None) if there is no time-stamp token and Ok(Some(())) if there is and the token validates. Err occurs on any parse or verification error.

pub fn signed_content_with_signed_data(
    &self,
    signed_data: &SignedData
) -> Vec<u8>

Obtain the raw bytes of content that was signed given a SignedData.

This joins the encapsulated content from SignedData with SignedAttributes on this instance to produce a new blob. This new blob is the message that is signed and whose signature is embedded in SignerInfo instances.

Examples found in repository

src/lib.rs (line 544)

    pub fn verify_signature_with_signed_data(
        &self,
        signed_data: &SignedData,
    ) -> Result<(), CmsError> {
        let signed_content = self.signed_content_with_signed_data(signed_data);

        self.verify_signature_with_signed_data_and_content(signed_data, &signed_content)
    }

pub fn signed_content(&self, content: Option<&[u8]>) -> Vec<u8>

Obtain the raw bytes of content that were digested and signed.

The returned value is the message that was signed and whose signature of which needs to be verified.

The optional content argument is the encapContentInfo eContent field, typically the value of SignedData.signed_content().

Examples found in repository

src/lib.rs (line 754)

    pub fn signed_content_with_signed_data(&self, signed_data: &SignedData) -> Vec<u8> {
        self.signed_content(signed_data.signed_content())
    }

pub fn signed_attributes_data(&self) -> Option<&[u8]>

Obtain the raw bytes constituting SignerInfo.signedAttrs as encoded for signatures.

Cryptographic signatures in the SignerInfo ASN.1 type are made from the digest of the EXPLICIT SET OF DER encoding of SignerInfo.signedAttrs, if signed attributes are present. This function resolves the raw bytes that are used for digest computation and later signing.

This should always be Some if the instance was constructed from an ASN.1 value that had signed attributes.

pub fn compute_digest_with_signed_data(&self, signed_data: &SignedData) -> Digest

Compute a message digest using a SignedData instance.

This will obtain the encapsulated content blob from a SignedData and digest it using the algorithm configured on this instance.

The resulting digest is typically stored in the message-digest attribute of SignedData.

Examples found in repository

src/lib.rs (line 608)

    pub fn verify_message_digest_with_signed_data(
        &self,
        signed_data: &SignedData,
    ) -> Result<(), CmsError> {
        let signed_attributes = self
            .signed_attributes()
            .ok_or(CmsError::NoSignedAttributes)?;

        let wanted_digest: &[u8] = signed_attributes.message_digest.as_ref();
        let got_digest = self.compute_digest_with_signed_data(signed_data);

        // Susceptible to timing side-channel but we don't care per function
        // documentation.
        if wanted_digest == got_digest.as_ref() {
            Ok(())
        } else {
            Err(CmsError::DigestNotEqual)
        }
    }

pub fn compute_digest(&self, content: Option<&[u8]>) -> Digest

Compute a message digest using the configured algorithm.

This method calls into compute_digest_with_algorithm() using the digest algorithm stored in this instance.

Examples found in repository

src/lib.rs (line 637)

    pub fn verify_message_digest_with_content(&self, data: &[u8]) -> Result<(), CmsError> {
        let signed_attributes = self
            .signed_attributes()
            .ok_or(CmsError::NoSignedAttributes)?;

        let wanted_digest: &[u8] = signed_attributes.message_digest.as_ref();
        let got_digest = self.compute_digest(Some(data));

        // Susceptible to timing side-channel but we don't care per function
        // documentation.
        if wanted_digest == got_digest.as_ref() {
            Ok(())
        } else {
            Err(CmsError::DigestNotEqual)
        }
    }

    /// Obtain an entity for validating the signature described by this instance.
    ///
    /// This will attempt to locate the certificate used by this signing info
    /// structure in the passed iterable of certificates and then construct
    /// a signature verifier that can be used to verify content integrity.
    ///
    /// If the certificate referenced by this signing info could not be found,
    /// an error occurs.
    ///
    /// If the signing key's algorithm or signature algorithm aren't supported,
    /// an error occurs.
    pub fn signature_verifier<'a, C>(
        &self,
        mut certs: C,
    ) -> Result<UnparsedPublicKey<Vec<u8>>, CmsError>
    where
        C: Iterator<Item = &'a CapturedX509Certificate>,
    {
        // The issuer of this signature is matched against the list of certificates.
        let signing_cert = certs
            .find(|cert| {
                // We're only verifying signatures here, not validating the certificate.
                // So even if the certificate comparison functionality is incorrect
                // (the called function does non-exact matching of the RdnSequence in
                // case the candidate certs have extra fields), that shouldn't have
                // security implications.
                certificate_is_subset_of(
                    &self.serial_number,
                    &self.issuer,
                    cert.serial_number_asn1(),
                    cert.issuer_name(),
                )
            })
            .ok_or(CmsError::CertificateNotFound)?;

        let key_algorithm = signing_cert.key_algorithm().ok_or_else(|| {
            CmsError::UnknownKeyAlgorithm(signing_cert.key_algorithm_oid().clone())
        })?;

        let verification_algorithm = self
            .signature_algorithm
            .resolve_verification_algorithm(key_algorithm)?;

        let public_key = UnparsedPublicKey::new(
            verification_algorithm,
            signing_cert.public_key_data().to_vec(),
        );

        Ok(public_key)
    }

    /// Resolve the time-stamp token [SignedData] for this signer.
    ///
    /// The time-stamp token is a SignedData ASN.1 structure embedded as an unsigned
    /// attribute. This is a convenience method to extract it and turn it into
    /// a [SignedData].
    ///
    /// Returns `Ok(Some)` on success, `Ok(None)` if there is no time-stamp token,
    /// and `Err` if there is a parsing error.
    pub fn time_stamp_token_signed_data(&self) -> Result<Option<SignedData>, CmsError> {
        if let Some(attrs) = self.unsigned_attributes() {
            if let Some(signed_data) = &attrs.time_stamp_token {
                Ok(Some(SignedData::try_from(signed_data)?))
            } else {
                Ok(None)
            }
        } else {
            Ok(None)
        }
    }

    /// Verify the time-stamp token in this instance.
    ///
    /// The time-stamp token is a SignedData ASN.1 structure embedded as an unsigned
    /// attribute. So this method reconstructs that data structure and effectively
    /// calls [SignerInfo::verify_signature_with_signed_data] and
    /// [SignerInfo::verify_message_digest_with_signed_data].
    ///
    /// Returns `Ok(None)` if there is no time-stamp token and `Ok(Some(()))` if
    /// there is and the token validates. `Err` occurs on any parse or verification
    /// error.
    pub fn verify_time_stamp_token(&self) -> Result<Option<()>, CmsError> {
        let signed_data = if let Some(v) = self.time_stamp_token_signed_data()? {
            v
        } else {
            return Ok(None);
        };

        if signed_data.signers.is_empty() {
            return Ok(None);
        }

        for signer in signed_data.signers() {
            signer.verify_signature_with_signed_data(&signed_data)?;
            signer.verify_message_digest_with_signed_data(&signed_data)?;
        }

        Ok(Some(()))
    }

    /// Obtain the raw bytes of content that was signed given a `SignedData`.
    ///
    /// This joins the encapsulated content from `SignedData` with `SignedAttributes`
    /// on this instance to produce a new blob. This new blob is the message
    /// that is signed and whose signature is embedded in `SignerInfo` instances.
    pub fn signed_content_with_signed_data(&self, signed_data: &SignedData) -> Vec<u8> {
        self.signed_content(signed_data.signed_content())
    }

    /// Obtain the raw bytes of content that were digested and signed.
    ///
    /// The returned value is the message that was signed and whose signature
    /// of which needs to be verified.
    ///
    /// The optional content argument is the `encapContentInfo eContent`
    /// field, typically the value of `SignedData.signed_content()`.
    pub fn signed_content(&self, content: Option<&[u8]>) -> Vec<u8> {
        // Per RFC 5652 Section 5.4:
        //
        //    The result of the message digest calculation process depends on
        //    whether the signedAttrs field is present.  When the field is absent,
        //    the result is just the message digest of the content as described
        //    above.  When the field is present, however, the result is the message
        //    digest of the complete DER encoding of the SignedAttrs value
        //    contained in the signedAttrs field.  Since the SignedAttrs value,
        //    when present, must contain the content-type and the message-digest
        //    attributes, those values are indirectly included in the result.  The
        //    content-type attribute MUST NOT be included in a countersignature
        //    unsigned attribute as defined in Section 11.4.  A separate encoding
        //    of the signedAttrs field is performed for message digest calculation.
        //    The IMPLICIT [0] tag in the signedAttrs is not used for the DER
        //    encoding, rather an EXPLICIT SET OF tag is used.  That is, the DER
        //    encoding of the EXPLICIT SET OF tag, rather than of the IMPLICIT [0]
        //    tag, MUST be included in the message digest calculation along with
        //    the length and content octets of the SignedAttributes value.

        if let Some(signed_attributes_data) = &self.digested_signed_attributes_data {
            signed_attributes_data.clone()
        } else if let Some(content) = content {
            content.to_vec()
        } else {
            vec![]
        }
    }

    /// Obtain the raw bytes constituting `SignerInfo.signedAttrs` as encoded for signatures.
    ///
    /// Cryptographic signatures in the `SignerInfo` ASN.1 type are made from the digest
    /// of the `EXPLICIT SET OF` DER encoding of `SignerInfo.signedAttrs`, if signed
    /// attributes are present. This function resolves the raw bytes that are used
    /// for digest computation and later signing.
    ///
    /// This should always be `Some` if the instance was constructed from an ASN.1
    /// value that had signed attributes.
    pub fn signed_attributes_data(&self) -> Option<&[u8]> {
        self.digested_signed_attributes_data
            .as_ref()
            .map(|x| x.as_ref())
    }

    /// Compute a message digest using a `SignedData` instance.
    ///
    /// This will obtain the encapsulated content blob from a `SignedData`
    /// and digest it using the algorithm configured on this instance.
    ///
    /// The resulting digest is typically stored in the `message-digest`
    /// attribute of `SignedData`.
    pub fn compute_digest_with_signed_data(&self, signed_data: &SignedData) -> Digest {
        self.compute_digest(signed_data.signed_content())
    }

pub fn compute_digest_with_algorithm(
    &self,
    content: Option<&[u8]>,
    alg: DigestAlgorithm
) -> Digest

Compute a message digest using an explicit digest algorithm.

This will compute the hash/digest of the passed in content.

Examples found in repository

src/lib.rs (line 824)

    pub fn compute_digest(&self, content: Option<&[u8]>) -> Digest {
        self.compute_digest_with_algorithm(content, self.digest_algorithm)
    }

Trait Implementations

impl Clone for SignerInfo

fn clone(&self) -> SignerInfo

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SignerInfo

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<&SignerInfo> for SignerInfo

type Error = CmsError

The type returned in the event of a conversion error.

fn try_from(signer_info: &SignerInfo) -> Result<Self, Self::Error>

Performs the conversion.