CMS_MakeSigData

Creates a CMS object of type SignedData from an input data file ready for sending as part of an S/MIME email.

VB6/VBA Syntax

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

Parameters

strFileOut

[in] String with name of output file to be created.

strFileIn

[in] String with name of file containing message data to be signed.

strCertList

[in] String containing the filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons(;)

strPrivateKey

[in] String containing the private key data for the sender.

nOptions

[in] Long Option flags. Select one of:
PKI_HASH_SHA1 (0) to use the SHA-1 algorithm (default)
PKI_HASH_MD5 to use the MD5 algorithm
PKI_HASH_SHA256 to use the SHA-256 algorithm
PKI_HASH_SHA384 to use the SHA-384 algorithm
PKI_HASH_SHA512 to use the SHA-512 algorithm
PKI_HASH_SHA224 to use the SHA-224 algorithm
and optionally add any of
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 [New in v2.8]
PKI_CMS_INCLUDE_ATTRS to include the two signed attributes content-type and message-digest
PKI_CMS_ADD_SIGNTIME to add SigningTime to the signed attributes
PKI_CMS_ADD_SMIMECAP to add sMIMECapabilities to the signed attributes
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
PKI_CMS_ALT_ALGID to use an alternative signature algorithm identifier (see Remarks)

C/C++ Syntax

Returns (VB6/C)

Long: 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.Options )
Cms.MakeSigData Method ( String, String, String, String, HashAlgorithm, Cms.SigDataOptions )

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 the first certificate in the certificate list and is included in the output by default. Any other certificates in the list will be included. Signed attributes are not included by default but can be added by using the PKI_CMS_INCLUDE_ATTRS option flag. The only other signed attributes supported are SigningTime and sMIMECapabilities; the PKI_CMS_INCLUDE_ATTRS option flag must be present for these optional signed attributes to be added. Unsigned attributes and attribute certificates are not supported. Only one message digest algorithm is used in each object. SHA-1 is used by default. Alternative hash digest algorithms can be used instead by using the appropriate PKI_HASH_ option flag. Only one SignerInfo can be included. The CMSVersion is always 1 and the SignerInfo structure is always version 1. The encapContentInfo eContentType is always id-data. The signer's public key can only be referenced by using issuerAndSerialNumber for SignerIdentifier as required by S/MIME v3, so the signer's certificate is always required whether or not the certificate itself is included in the final output.

New in Version 2.8: 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].

If the PKI_CMS_ALT_ALGID option flag is present, an alternative Signature Algorithm Identifier will be used as follows:

This alternative identifier has been added to conform to the PKI requirements of the Royal Thai Customs Department. The default is to use the identifier specified in [CMSALG].

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

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 = "C:\Test\AlicePrivRSASign.pri"
strCertFile = "C:\Test\AliceRSASignByCarl.cer"
strInputFile = "C:\Test\excontent.txt"
strOutputFile = "C:\Test\BasicSignByAlice.bin"

' First we need to read in the private key string
' NB: This version is not encrypted
nIntKeyLen = RSA_ReadPrivateKeyInfo("", 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_ReadPrivateKeyInfo(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]