CryptoSys PKI Pro Manual

CMS_MakeSigData

Creates a CMS object of type SignedData from an input data file.

VBA/VB6 Syntax

Public Declare Function CMS_MakeSigData Lib "diCrPKI.dll" (ByVal strFileOut As String, ByVal strFileIn As String, ByVal strCertList As String, ByVal strPrivateKey As String, ByVal nOptions As Long) As Long

nRet = CMS_MakeSigData(strFileOut, strFileIn, strCertList, strPrivateKey, nOptions) As Long

C/C++ Syntax

long __stdcall CMS_MakeSigData(const char *szFileOut, const char *szFileIn, const char *szCertList, const char *szPrivateKey, long nOptions);

Parameters

szFileOut
[in] name of output file to be created.
szFileIn
[in] name of file containing message data to be signed.
szCertList
[in] filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;). Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.
szPrivateKey
[in] private key data for the sender in "internal" string format.
nOptions
[in] Option flags. Select one of:
PKI_SIG_RSA_SHA1 (0) to use RSASSA-PKCS-v1_5 with SHA-1 (sha1WithRSAEncryption) (default - CAUTION)
PKI_SIG_RSA_SHA224 to use RSASSA-PKCS-v1_5 with SHA-224 (sha224WithRSAEncryption)
PKI_SIG_RSA_SHA256 to use RSASSA-PKCS-v1_5 with SHA-256 (sha256WithRSAEncryption) [minimum recommended]
PKI_SIG_RSA_SHA384 to use RSASSA-PKCS-v1_5 with SHA-384 (sha384WithRSAEncryption)
PKI_SIG_RSA_SHA512 to use RSASSA-PKCS-v1_5 with SHA-512 (sha512WithRSAEncryption)
PKI_SIG_RSA_MD5 to use RSASSA-PKCS-v1_5 with MD5 (md5WithRSAEncryption) [legacy, not recommended for new implementations]
PKI_SIG_RSA_PSS_SHA1 to use RSASSA-PSS with SHA-1
PKI_SIG_RSA_PSS_SHA224 to use RSASSA-PSS with SHA-224
PKI_SIG_RSA_PSS_SHA256 to use RSASSA-PSS with SHA-256
PKI_SIG_RSA_PSS_SHA384 to use RSASSA-PSS with SHA-384
PKI_SIG_RSA_PSS_SHA512 to use RSASSA-PSS with SHA-512
PKI_SIG_ECDSA_SHA1 to use ecdsaWithSHA1
PKI_SIG_ECDSA_SHA224 to use ecdsaWithSHA224
PKI_SIG_ECDSA_SHA256 to use ecdsaWithSHA256
PKI_SIG_ECDSA_SHA384 to use ecdsaWithSHA384
PKI_SIG_ECDSA_SHA512 to use ecdsaWithSHA512
PKI_SIG_ED25519 to use Ed25519 [New in v20.0]
PKI_SIG_ED448 to use Ed448 [New in v22.0]

And optionally add any combination of the following flags:
PKI_CMS_EXCLUDE_CERTS to exclude signer's certificate
PKI_CMS_EXCLUDE_DATA to exclude the eContent data
PKI_CMS_CERTS_ONLY to create a "certs-only" PKCS#7 certficate chain
PKI_CMS_USE_SKI to use subjectKeyIdentifier (SKI) instead of issuerAndSerialNumber for SignerIdentifier [New in v23.0].
PKI_CMS_INCLUDE_ATTRS to add signed attributes (default = no signed attributes) including content-type and message-digest plus any more added below.
PKI_CMS_FORMAT_BASE64 to format the output with base64 encoding (default output is binary)
PKI_CMS_NO_OUTER to create a "naked" SignedData object with no outerContentInfo as permitted by PKCS#7 v1.6 (specialist option)
PKI_CMS_ALT_ALGID to use an alternative signature algorithm identifier (see Remarks)
PKI_CMS_BIGFILE to speed up the processing of large files (see Remarks)
PKI_PSS_SALTLEN_ZERO to set the salt length to be zero (RSASSA-PSS only, default = same length as the output of the hash function)
PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (RSASSA-PSS only, default = same as signature hash function)
PKI_CMS_PSEUDOSIG to create a create a "pseudo" SignedData object with a dummy placeholder signature (see Remarks)
PKI_CMS_ADD_SIGNER to add a new signer to an existing SignedData object [New in v23.0] (see Remarks)

If the PKI_CMS_INCLUDE_ATTRS option flag is included, optionally add any of the following:
PKI_CMS_ADD_SIGNTIME to add SigningTime to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS)
PKI_CMS_ADD_SMIMECAP to add sMIMECapabilities to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS)
PKI_CMS_ADD_SIGNINGCERT to add an ESS Signing Certificate Attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) [New in v12.4]
PKI_CMS_ADD_ALGPROTECT to add an Algorithm Identifier Protection Attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) [New in v12.4]

Returns (VBA/C)

If successful, the return value is zero; otherwise it returns a nonzero error code. Further error information may be available by calling PKI_LastError().

.NET Equivalent

Cms.MakeSigData Method ( String, String, String, String, Cms.SigAlg, Cms.SigDataOptions)
Cms.MakeSigData Method ( String, String, String, String, HashAlgorithm, Cms.SigDataOptions)

C++ (STL) Equivalent

static int dipki::Cms::MakeSigData (const std::string &outputFile, const std::string &inputFile, const std::string &certList, const std::string &privateKey, SigAlg sigAlg=SigAlg::Default, SigDataOptions opts=SigDataOptions::Default_SigDataOpt, Format format=Format::Default, bool bigFile=false)

Python Equivalent

static Cms.make_sigdata(outputfile, inputfile, certlist, prikeystr, sigalg=SigAlg.DEFAULT, opts=SigDataOpts.DEFAULT, bigfile=False)

Remarks

A SignedData CMS object with a single SignerInfo is created with the message data included by default in the eContent. The signer's certificate must be included in the certificate list. All certificates in the list will be included in the output by default. Signed attributes are not included by default but can be added by using the PKI_CMS_INCLUDE_ATTRS option flag (see below). Unsigned attributes and attribute certificates are not supported. The default signature algorithm is RSASSA-PKCS-v1_5 with SHA-1 (SHA-1 caution!). The message digest algorithm always matches the digest algorithm used in the signature.

The encapContentInfo eContentType is always id-data: other eContentTypes are not possible. Only one SignerInfo can be included at one time, but [New in v23.0] additional SignerInfos can be added by calling this function second time passing an existing SignedData object as input and setting the PKI_CMS_ADD_SIGNER (see below). [New in v23.0] The signer's public key can be referenced using either issuerAndSerialNumber (default) or subjectKeyIdentifier (use the PKI_CMS_USE_SKI option). If subjectKeyIdentifier is used then the CMSversion will be 3 and the relevant SignerInfo version will also be 3. Otherwise the CMSVersion will be 1 and the SignerInfo structure also version 1.

It is an error (NO_MATCH_ERROR) if the private key does not match any certificate in the certificate list.

[New in v12.2] A PKCS#7 certificate chain file (.p7c/.p7b) may be specified as an argument for szCertList. The signer's certificate can now exist anywhere in the certificate list (previously it had to be the first).

PKI_CMS_CERTS_ONLY: To create a PKCS#7 certificate chain (a degenerate "certs-only" signed data object), include the option flag PKI_CMS_CERTS_ONLY. The szCertList can contain references to any existing certificate files in any order, separated by semi-colons. The szFileIn and szPrivateKey parameters are ignored and can be left empty. See the second example below.

PKI_CMS_INCLUDE_ATTRS: Signed attributes are not included by default. To add signed attributes use the PKI_CMS_INCLUDE_ATTRS option flag. This will add the content-type and message-digest attributes plus any other attributes specified using a PKI_CMS_ADD_* option.

PKI_CMS_ADD_SIGNINGCERT: [New in v12.4] Include the PKI_CMS_ADD_SIGNINGCERT option to add an ESS Signing Certificate Attribute to the signed attributes. This is required for B-level compliance with CAdES-BES [CADES] and with ESS [RFC2634] and [RFC5035].

PKI_CMS_ADD_ALGPROTECT: [New in v12.4] Include the PKI_CMS_ADD_ALGPROTECT option to add an Algorithm Protection Attribute to the signed attributes. This is in accordance with [RFC6211]. If a CMS validator supports this attribute, then additional checks can be made against algorithm substitution attacks.

PKI_CMS_BIGFILE: Include the PKI_CMS_BIGFILE option to cope more efficiently with large files. This only works in binary-file-to-binary-file mode, and only for RSA signatures, but makes a significant difference in processing times. The option flags PKI_CMS_EXCLUDE_DATA, PKI_CMS_CERTS_ONLY, PKI_CMS_FORMAT_BASE64, and PKI_CMS_NO_OUTER are not permitted with this option.

PKI_CMS_ADD_SIGNER: [New in v23.0] To sign an existing SignedData object with another signature, use the PKI_CMS_ADD_SIGNER option and pass the existing SignedData object as the input data file. Pass the signer's certificate in szCertList (plus any additional certificates if required) and the signer's private key string in szPrivateKey.

PKI_PSS_SALTLEN_ZERO: [New in v12.0] Include the PKI_PSS_SALTLEN_ZERO with an RSA-PSS scheme to set the salt length parameter to be zero. This results in a deterministic signature value. The default salt length is otherwise always hLen, the length of the output of the hash function. There are no other salt length options available for this function. See RSA signature and encryption schemes.

PKI_CMS_ALT_ALGID: If the PKI_CMS_ALT_ALGID option flag is present, an alternative Signature Algorithm Identifier will be used as follows (RSAES-PKCS-v1_5 only):

Message Digest Algorithm Default Signature Algorithm Identifier Alternative ID with PKI_CMS_ALT_ALGID
SHA-1 (default, PKI_SIG_RSA_SHA1)rsaEncryption (1.2.840.113549.1.1)sha1withRSAEncryption (1.2.840.113549.1.1.5)
MD5 (with PKI_SIG_RSA_MD5)rsaEncryption (1.2.840.113549.1.1)md5withRSAEncryption (1.2.840.113549.1.1.4)
SHA-224 (with PKI_SIG_RSA_SHA224)rsaEncryption (1.2.840.113549.1.1)sha224withRSAEncryption (1.2.840.113549.1.1.14)
SHA-256 (with PKI_SIG_RSA_SHA256)rsaEncryption (1.2.840.113549.1.1)sha256withRSAEncryption (1.2.840.113549.1.1.11)
SHA-384 (with PKI_SIG_RSA_SHA384)rsaEncryption (1.2.840.113549.1.1)sha384withRSAEncryption (1.2.840.113549.1.1.12)
SHA-512 (with PKI_SIG_RSA_SHA512)rsaEncryption (1.2.840.113549.1.1)sha512withRSAEncryption (1.2.840.113549.1.1.13)

The default is to use the rsaEncryption identifier specified in Section 3.2 of [CMSALG].

PKI_CMS_PSEUDOSIG: [New in v20.2] Include the PKI_CMS_PSEUDOSIG option to create a create a "pseudo" SignedData object. The idea here is that we create an intermediate file which has the same structure as a CMS SignedData object except the signature is a dummy placeholder. We use the term "pseudo" file here to describe this intermediate file.

This pseudo file has the same digest value as the final signed object (as the digest is not calculated over the final signature). We send this digest value to a signing authority (say, Aruba), they sign it, and send back the actual signature value. This can be substituted in the intermediate pseudo file to produce the final SignedData object (.p7m file) using CMS_MakeSigDataFromSigValue with the PKI_CMS_PSEUDOSIG option. RSASSA-PKCS1V1_5 only.

Specialist Option: If the PKI_CMS_NO_OUTER option flag is present, the output will be a "naked" SignedData object without an outerContentInfo. This is not permitted by the CMS standard [CMS] but is allowed by PKCS#7 version 1.6 [PKCS7-EXT]. Some profiles (e.g. Royal Thai Customs) require this.

Example

This example duplicates example 4.2 from [SMIME-EX]. It uses Alice's RSA private key to sign the message stored in the file excontent.txt (which contains the text "This is some sample content."). The output is a binary BER-encoded CMS signedData object which includes her certificate and the data but has no signed attributes. The output file should match the file 4.2.bin from [SMIME-EX].

Dim strPriFile As String
Dim strPrivateKey As String
Dim nIntKeyLen As Long
Dim nRet As Long
Dim strInputFile As String
Dim strOutputFile As String
Dim strCertFile As String

strPriFile = "AlicePrivRSASign.pri"
strCertFile = "AliceRSASignByCarl.cer"
strInputFile = "excontent.txt"
strOutputFile = "BasicSignByAlice.bin"

' First we need to read in the private key string
' NB: This version is not encrypted, so no password needed
nIntKeyLen = RSA_ReadAnyPrivateKey("", 0, strPriFile, "", 0)
Debug.Print "nIntKeyLen = " & nIntKeyLen
If nIntKeyLen <= 0 Then
    Debug.Print pkiGetLastError()
    MsgBox "Unable to retrieve private key"
    Exit Sub
End If
' Pre-dimension the string to receive data
strPrivateKey = String(nIntKeyLen, " ")
' Read in the Private Key
nRet = RSA_ReadAnyPrivateKey(strPrivateKey, nIntKeyLen, strPriFile, "", 0)
Debug.Print "Key size=" & RSA_KeyBits(strPrivateKey) & " bits"

' Now we can sign our message
nRet = CMS_MakeSigData(strOutputFile, strInputFile, strCertFile, strPrivateKey, 0)
Debug.Print "CMS_MakeSigData returns " & nRet

In this second example, we create a PKCS#7 certficate chain file containing Carl's and Alice's X.509 certificates.

Dim nRet As Long
Dim strOutputFile As String
Dim strCertList As String

' Make a list of certs separated by semi-colons (;)
strCertList = "CarlRSASelf.cer;" & "AliceRSASignByCarl.cer"
Debug.Print "CertList=" & strCertList
strOutputFile = "SigDataCertsOnly.p7c"

' Create a certs-only .p7c chain
nRet = CMS_MakeSigData(strOutputFile, "", strCertList, "", PKI_CMS_CERTS_ONLY)
Debug.Print "CMS_MakeSigData returns " & nRet
If nRet <> 0 Then Debug.Print pkiGetLastError()

See Also

CMS_MakeSigDataFromString CMS_MakeSigDataFromSigValue CMS_MakeDetachedSig

[Contents] [Index]

[PREV: CMS_MakeEnvDataFromString...]   [Contents]   [Index]   
   [NEXT: CMS_MakeSigDataFromSigValue...]

Copyright © 2004-24 D.I. Management Services Pty Ltd. All rights reserved. Generated 2024-09-23T07:52:09Z.