gsk_sign_data()

Signs a data stream.

Format

#include <gskcms.h>

gsk_status gsk_sign_data (
                          x509_algorithm_type               sign_algorithm,
                          pkcs_private_key_info *           private_key,
                          gsk_boolean                       is_digest, 
                          gsk_buffer *                      data,
                          gsk_buffer *                      signature)

Parameters

sign_algorithm: Specifies the signature algorithm.
private_key: Specifies the private key.
is_digest: Specify TRUE if the data stream digest has been computed or FALSE if the data stream digest needs to be computed.
data: Specifies either the data stream digest (is_digest is TRUE) or the data stream (is_digest is FALSE).
signature: Returns the generated signature. The caller should release the signature buffer when it is no longer needed by calling the gsk_free_buffer() routine.

Results

The return status will be zero if the signature is successfully generated. Otherwise, it will be one of the return codes listed in the gskcms.h include file. These are some possible errors:

[CMSERR_ALG_NOT_SUPPORTED]: The signature algorithm is not supported.
[CMSERR_BAD_DIGEST_SIZE]: The digest size is not correct.
[CMSERR_BAD_EC_PARAMS]: Elliptic Curve parameters are not valid.
[CMSERR_BAD_KEY_SIZE]: The key size is not valid.
[CMSERR_BAD_RNG_OUTPUT]: In FIPS mode, random bytes generation produced duplicate output.
[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_INVALID_KEY_ATTRIBUTE]: Key does not have required PKCS #11 attributes to perform signing.
[CMSERR_KEY_MISMATCH]: The supplied key does not match the signature algorithm.
[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_NO_PKCS11_KEY_LABEL]: A TKDS secure key label is either invalid or missing.
[CMSERR_NO_PRIVATE_KEY]: Private key does not exist, is not accessible, or the PKCS #11 TKDS secure key is not a supported algorithm type.

Usage

The gsk_sign_data() routine will generate the signature for a data stream using the supplied private key. The private key can be an RSA key, a DSA key, or an ECDSA key. If executing in FIPS mode, the minimum key size for RSA and DSA keys is 1024 bits, and the minimum size for ECDSA keys is 160 bits. The private key can be an ASN.1-encoded value contained in the privateKey field or an ICSF key label contained in the keyToken field. In either case, the key type must be specified by the privateKeyAlgorithm field.

The application can either provide the message digest or have the gsk_sign_data() routine compute the message digest.

When the application provides the message digest, the digest length must be correct for the specified signature algorithm. Digest lengths: MD2 and MD5 are 16 bytes; SHA-1 is 20 bytes; SHA-224 is 28 bytes; SHA-256 is 32 bytes; SHA-384 is 48 bytes and SHA-512 is 64 bytes. The supplied digest will be used as-is without any further processing (specifically, for an RSA encryption key, the digest will not be encoded as an ASN.1 DigestInfo sequence before generating the signature).

The following signature algorithms are supported:

x509_alg_md2WithRsaEncryption: RSA encryption with MD2 digest - {1.2.840.113549.1.1.2}
x509_alg_md5WithRsaEncryption: RSA encryption with MD5 digest - {1.2.840.113549.1.1.4}
x509_alg_sha1WithRsaEncryption: RSA encryption with SHA-1 digest - {1.2.840.113549.1.1.5}
x509_alg_sha224WithRsaEncryption: RSA encryption with SHA-224 digest - {1.2.840.113549.1.1.14}
x509_alg_sha256WithRsaEncryption: RSA encryption with SHA-256 digest - {1.2.840.113549.1.1.11}
x509_alg_sha384WithRsaEncryption: RSA encryption with SHA-384 digest - {1.2.840.113549.1.1.12}
x509_alg_sha512WithRsaEncryption: RSA encryption with SHA-512 digest - {1.2.840.113549.1.1.13}
x509_alg_dsaWithSha1: Digital Signature Standard with SHA-1 digest - {1.2.840.10040.4.3}
x509_alg_dsaWithSha224: Digital Signature Standard with SHA-224 digest – {2.16.840.1.101.3.4.3.1}
x509_alg_dsaWithSha256: Digital Signature Standard with SHA-256 digest – {2.16.840.1.101.3.4.3.2}
x509_alg_ecdsaWithSha1: Elliptic Curve Digital Signature Algorithm with SHA-1 digest – {1.2.840.10045.4.1}
x509_alg_ecdsaWithSha224: Elliptic Curve Digital Signature Algorithm with SHA-224 digest – {1.2.840.10045.4.3.1}
x509_alg_ecdsaWithSha256: Elliptic Curve Digital Signature Algorithm with SHA-256 digest – {1.2.840.10045.4.3.2}
x509_alg_ecdsaWithSha384: Elliptic Curve Digital Signature Algorithm with SHA-384 digest – {1.2.840.10045.4.3.3}
x509_alg_ecdsaWithSha512: Elliptic Curve Digital Signature Algorithm with SHA-512 digest – {1.2.840.10045.4.3.4}
x509_alg_md5Sha1WithRsaEncryption: RSA encryption with combined MD5 and SHA-1 digests

When executing in FIPS mode, signature algorithms x509_alg_md2WithRSAEncryption and x509_alg_md5WithRsaEncryption are not supported.