Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - Digital Signatures

createKeyFromHMACSecret Method

[This feature was first implemented for MSXML 5.0.]

This method generates a symmetric key based on a Base64-encoded value of an HMAC secret. The resultant key can be used in sign and verify.

[JScript]

JScript Syntax

var objKey = objXMLDigitalSignature.createKeyFromHMACSecret(
      secret, 
      length
);
[Visual Basic]

Visual Basic Syntax

Set objKey = objXMLDigitalSignature.createKeyFromHMACSecret(
      secret, _
      length  _
)
[C/C++]

C/C++ Syntax Using Smart Pointers

IXMLDSigKeyPtr objKey=objXMLDigitalSignature->createKeyFromHMACSecret(
      (BSTR)secret,
      (LONG)length 
);

C/C++ Syntax

HRESULT  createKeyFromHMACSecret(
    BSTR secret,
    LONG length,
    IXMLDSigKey** objKey);

Parameters

secret [in]
A Base64 encoded HMAC secret value.
length [in]
Number of bits used to represent the HMAC secret value for signing or verification. The value of this parameter corresponds to the content of the <ds:HMACOutputLength> element in <ds:Signature>. It can be a positive number in multiples of eight (8), but no greater than 128, or a negative one (-1). The positive value is used by sign or verify as the bit length of the secret. For -1, the default length defined in CryptoAPI or the content of <ds:HMACOutputLength> element is used instead.

The actual length used in sign or verify depends on the combination of the value of the length parameter and the content of <ds:HMACOutputLength> element in the signature template or document. The following table shows the possible combinations, the length used to verify, and the values returned.

length value <ds:HMACOutputLength> content Actual length used in sign or verify Return code from createKeyFromHAMCSecret Return value from sign or verify
8*n, where n=1, 2, ..., 16 Any value The value of the length parameter S_OK Regular return value
-1 8*n, where n=1, 2, ..., 16 The value of <ds:HMACOutputLength> S_OK Regular return value
-1 Any value The sign or verify method will fail. S_OK E_FAIL
-1 Absent CryptoAPI default length (128) S_OK Regular return value
Any value Any value No key will be created. The objKey parameter is returned as NULL. E_INVALIDARG E_INVALIDARG

objKey [out, retval]
In C/C++, this is a reference to the resultant key object implementing the IXMLDSigKey interface. In Visual Basic, scripting languages, and C/C++ with smart pointers, this is the key object itself.

Return Values

The method returns the standard HRESULT values defined in CryptoAPI, including the following:

S_OK
The value returned if successful.
E_FAIL
The value returned if there was insufficient information, if the method call was not authorize, etc.
E_ACCESSDENIED
The value returned if the user does not have access to the security item.
E_INVALIDARG
An invalid argument was used as input.

Remarks

The HMAC secret value is shared by the signer and the signature verifier, and is not to be transmitted with the signature document.

The key generated by this method does not have any corresponding certificate. When this key is used in signing, the <ds:KeyInfo> element and its children will be purged.

When the length parameter value is -1, it is important that the <ds:HMACOutputLength> element contains a positive number that is multiple of eight (8). An empty content or zero value would mean that the signature information will not be used.

Example

This examples illustrates how to sign and verify a document using an HMAC secret value, "secret". The Base64 encoding of this value is "c2VjcmV0", and is used by the createKeyFromHMACSecret method to generate a key for both signing and verifying a piece of data. The data for this example is the text string "Hello, World!".

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 and later

To view reference information for Visual Basic, C/C++, or Script only, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

CreateKeyFromHMACSecretBinary Method