Processes a PKCS #7 SignedData message.
Format
#include <gskcms.h>
gsk_status gsk_read_signed_data_msg_extended (
gsk_process_option option_flag
pkcs_certificates * local_certificates,
gsk_buffer * stream,
gsk_boolean * used_local,
pkcs_certificates * msg_certificates,
pkcs_certificates * signer_certificates,
gsk_attributes_signers * attributes_signers,
gsk_buffer * data)
Parameters
- option_flag
- Specifies process options to customize process behavior.
- Enforce signing certificate has digital signing capabilities.
That is, the purpose of the certificate key as reflected by the key
usage extension must indicate digitalSignature.
- Do not allow zero-length content data.
- local_certificates
- Specifies zero or more X.509 certificates to use when verifying
the message signatures. NULL can be specified for this parameter
if no local certificates are provided.
- stream
- Specifies the ASN.1 DER-encoded stream to be processed.
- used_local
- This parameter is set to TRUE if the signatures were verified
by using just the certificates that are supplied by the local_certificates
parameter. This parameter is set to FALSE if any of the signatures
were verified by using certificates that are contained within the
message.
- msg_certificates
- Returns the X.509 certificates that are contained within the message.
The application should call the gsk_free_certificates() routine
to release the certificates when they are no longer needed. Specify
NULL for this parameter if the message certificates are not needed.
- signer_certificates
- Returns the certificates that are used to sign the message. The
application should call the gsk_free_certificates() routine
to release the certificates when they are no longer needed. Specify
NULL for this parameter if the signer certificates are not needed.
- attributes_signers
- Returns the authenticated attributes per signer that is contained
within the message. The application should call the gsk_free_attributes_signers() routine
to release the gsk_attributes_signers structure when it is no longer
needed. Specify NULL for this parameter if the authenticated attributes
per signer are not needed. The set of authenticated attributes returned,
omits the content-type and message-digest authenticated attributes
as these authenticated attributes must always be present, if any authenticated
attributes are present, and are automatically verified by gsk_read_signed_data_msg_extended().
The digestAlgorithm field within each gsk_attributes_signer structure
returns the digest algorithm that is originally used for the signer.
- data
- Returns the content of the SignedData message. The application
should call the gsk_free_buffer() routine to release the data
when it is no longer needed.
Results
The function return value will be
0 if no error is detected. Otherwise, it is one of the return codes
listed in the gskcms.h include file. These are some possible
errors:
- [ASN_NO_MEMORY]
- Insufficient storage is available.
- [ASN_SELECTION_OUT_OF_RANGE]
- Certificate type or version number is not valid.
- [CMSERR_ALG_NOT_SUPPORTED]
- The digest algorithm is not supported.
- [CMSERR_CONTENT_NOT_SUPPORTED]
- The message content type is not SignedData or the content of the
SignedData message is not Data.
- [CMSERR_BAD_SIGNATURE]
- Signature is not correct.
- [CMSERR_DIGEST_KEY_MISMATCH]
- The digest algorithm is not supported for the private key type.
- [CMSERR_ECURVE_NOT_FIPS_APPROVED]
- Elliptic Curve not supported in FIPS mode.
- [CMSERR_ECURVE_NOT_SUPPORTED]
- Elliptic Curve is not supported.
- [CMSERR_ICSF_FIPS_DISABLED]
- ICSF PKCS #11 services are disabled.
- [CMSERR_ICSF_NOT_AVAILABLE]
- ICSF services are not available.
- [CMSERR_ICSF_NOT_FIPS]
- ICSF PKCS #11 not operating in FIPS mode.
- [CMSERR_ICSF_SERVICE_FAILURE]
- ICSF callable service returned an error.
- [CMSERR_INCORRECT_KEY_USAGE]
- A signer certificate does not allow digital signature.
- [CMSERR_NO_CONTENT_DATA]
- The content data length is zero.
- [CMSERR_NO_MEMORY]
- Insufficient storage is available.
- [CMSERR_SIGNER_NOT_FOUND]
- Signer certificate not found.
Usage
The gsk_read_signed_data_msg_extended() routine
processes a PKCS #7 (Cryptographic Message Syntax) SignedData message
that is created by the gsk_make_signed_data_msg_extended() routine
and returns the message content and all authenticated attributes (if
present). The signed data content type must be Data.
Processing
is equivalent to
gsk_read_signed_data_msg(), with these differences:
- The signing certificate key usage need not assert digital signing
capabilities depending on option_flag.
- Zero length content is acceptable depending on option_flag.
- Authenticated attributes and the digest algorithm that is used
to create the signed data per signer, if present, are returned.
Calling the gsk_read_signed_data_msg_extended() routine
is equivalent to calling the gsk_read_content_msg() routine,
the gsk_read_signed_data_content_extended() routine, and the gsk_read_data_content() routine.
The local_certificates parameter
can supply the signer certificates that are used to verify the message
signatures. If a certificate is not found for a message signer, the gsk_read_signed_data_msg_extended() routine
attempts to locate the signer certificate in the SignedData message.
An error is returned if the signer certificate cannot be found.
An error may optionally be returned if the certificate key usage does
not allow digital signature.
No certificate validation is performed
by the gsk_read_signed_data_msg_extended() routine. It is
assumed that the application validated the local certificates. The
certificates that are contained in the SignedData message are returned
in the msg_certificates parameter and the used_local parameter
is set to FALSE if any of these certificates were used to verify the
message signatures. It is the responsibility of the application to
validate the message certificates (for example, by calling the gsk_validate_certificate_mode() routine
for each of the signer certificates).
These digest algorithms
are supported:
- x509_alg_md2Digest
- MD2 digest (RSA keys only) - {1.2.840.113549.2.2}
- x509_alg_md5Digest
- MD5 digest (RSA keys only) - {1.2.840.113549.2.5}
- x509_alg_sha1Digest
- SHA-1 digest (RSA, DSA, and ECDSA keys only) - {1.3.14.3.2.26}
- x509_alg_sha224Digest
- SHA-224 digest (RSA, DSA, and ECDSA keys only)
- {2.16.840.1.101.3.4.2.4}
- x509_alg_sha256Digest
- SHA-256 digest (RSA, DSA, and ECDSA keys only)
- {2.16.840.1.101.3.4.2.1}
- x509_alg_sha384Digest
- SHA-384 digest (RSA and ECDSA keys only) - {2.16.840.1.101.3.4.2.2}
- x509_alg_sha512Digest
- SHA-512 digest (RSA and ECDSA keys only) - {2.16.840.1.101.3.4.2.3}
If authenticated attributes are returned from
the attributes_signers parameter, then it is recommended that
signing certificates for all signers represented within the gsk_attributes_signers
structure should be requested from the signer_certificates parameter.
When
executing in FIPS mode, digest algorithms x509_alg_md2Digest and x509_alg_md5Digest
are not supported.