sign Method

  • Article

 

[This sample code uses features that were implemented in MSXML 5.0 for Microsoft Office Applications. XML digital signatures are not supported in MXSML 6.0 and later.]

Signs the document referenced in the <ds:Signature> element that has been assigned to the signature property of this IXMDigitalSignature object. The key object supplied must contain a private key and can be generated from one of the following methods:

  • createKeyFromCSP

  • createKeyFromCertContext

  • createKeyFromHMACSecret

  • createKeyFromHMACSecretBinary

  • createKeyFromNode

JScript Syntax

var oSignedKey = objXMLDigitalSignature.sign(oKey, fwWriteKeyInfo);

Visual Basic Syntax

Set oSignedKey = objXMLDigitalSignature.sign
(oKey, fwWriteKeyInfo)

C/C++ Syntax Using Smart Pointers

IXMLDSigKeyPtr oSignedKey =  
 objXMLDigitalSignature->sign(oKey, fwWriteKeyInfo);

C/C++ Syntax

HRESULT sign(  
    IXMLDSigKey* oKey,  
    XMLDSIG_WRITEKEYINFO fwWriteKeyInfo,  
    IXMLDSigKey** oSignedKey);

Parameters

oKey
A key object implementing the IXMLDSigKey interface. This object cannot be NULL.

fwWriteKeyInfo
A flag to specify how the key information should be handled in the resultant signature object. Possible values are discussed in XMLDSIG_WRITEKEYINFO enum.

oSignedKey[out, retval]
The IXMLDSigKey object used in signing. The return parameter is NULL if the method failed. Otherwise it is the same object passed in the oKey parameter.

Return Values

S_OK
The value returned if the method call was successful.

E_FAIL
The value returned if the implementation failed to get the data for CryptoAPI.

E_ACCESSDENIED
The value returned if the method is called in a non-trusted context or the caller lacks a sufficient permission to access the supplied key.

In addition, the method passes the failure codes from CryptoAPI that are not covered by S_FALSE or NULL.

Remarks

Signing using this method amounts to performing the following tasks:

  1. Calculate digest values for the document referenced in every <ds:Reference> element under <ds:SignedInfo>:

    1. Resolve the URI attribute of the <ds:Reference> element. If the URI attribute is absent, data set by IXMLDigitalSignature::setReferenceData is used.

    2. Perform the transformations specified in the optional <ds:transforms> child element.

    3. Calculate the digest of the referenced data using the algorithm named in the <ds:DigestMethod> child element in the signature template and output the hash value as the text value of the <ds:DigestValue> child element.

  2. Fill in the <ds:SignatureMethod> element with the name of the algorithm determined by the signing key. For HMAC, <ds:HMACOutputLength> is created, if absent, and its content is set according to the value of the length parameter of the createKeyFromHMACSecret or createKeyFromHMACSecretBinary method.

  3. Canonicalize the content of the <ds:SignedInfo> element using the algorithm named in the <ds:CanonicalizationMethod> element.

  4. Calculate the digest of the canonicalized <ds:SignedInfo> to produce the signature hash.

  5. Sign the signature hash using the private key provided and saves this signed signature as the text value of the <ds:SignatureValue> element.

  6. Save the information of the key and certificates to the <ds:KeyInfo> element according the value of fWriteKeyInfo parameter passed to the sign method.

  7. Return the key in the oSignedKey parameter if signing succeeded. Otherwise return NULL.

From this we see how a signature template might be set up. For more information on how to set up the signature template, see the discussions given in the signature Property topic.

Note

The sign method is the only method that can change the <ds:Signature> element specified by the signature property.

Note

You cannot sign any data in a non-trusted context, such as a script embedded in an HTML page. Doing so will result in an error.

Example

The following example illustrates how the sign method is used to sign data with XML digital signature. It uses a simple signature template (signature_template.sign.rsa.xml) as the input. The template has three empty sub elements: <ds:DigestValue>, <ds:SignatureValue>, and <ds:KeyInfo>. The first two will be filled in after sign returns. The last one will be filled in when sign is called with fwWriteKeyInfo=KEYVALUE. It is left intact if fwWriteKeyInfo=NOKEYINFO and all the existing content is cleared if fwWriteKeyInfo=PURGE. When fwWriteKeyInfo=CERTIFICATES, a <X509Data> element is inserted when the certificate of the key used is available.

We've provided source files for the sample in three languages: JScript, Visual Basic, and C++. The output is the same in each language.

Applies to

IXMLDigitalSignature | IXMLDigitalSignatureEx

Versioning

MSXML 5.0 for Microsoft Office Applications and later