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 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 bysign
orverify
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
orverify
depends on the combination of the value of thelength
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
parameterS_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
orverify
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
parameteris 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.
- Resource File (signature-template-enveloping-hmac-sha1.xml)
- JScript Code (KeyFromHMACSecret.js)
- Visual Basic Code (KeyFromHMACSecret.frm)
- C/C++ Code (KeyFromHMACSecret.cpp)
- Output for the KeyFromHMACSecret Example
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 in the upper-left corner of the page.
See Also
CreateKeyFromHMACSecretBinary Method