createKeyFromHMACSecret Method

Article
10/27/2016

[This feature was implemented for MSXML 5.0 for Microsoft Office Applications. XML digital signatures are not supported in MXSML 6.0 and later.]

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 Syntax

var objKey = objXMLDigitalSignature.createKeyFromHMACSecret(  
      secret,   
      length  
);

Visual Basic Syntax

Set objKey = objXMLDigitalSignature.createKeyFromHMACSecret(  
      secret, _  
      length  _  
)

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 for Microsoft Office Applications and later

Share via