verify 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.]

Verifies the data referenced in an already signed XML digital signature document, using the embedded or a supplied public key.

JScript Syntax

var verifiedKey = objXMLDigitalSignature.verify(key);

Visual Basic Syntax

Set verifiedKey = objXMLDigitalSignature.verify(key)

C/C++ Syntax Using Smart Pointers

IXMLDSigKeyPtr verifiedKey = objXMLDigitalSignature->verify(key);

C/C++ Syntax

HRESULT verify(  
    IXMLDSigKey* key,  
    IXMLDSigKey** verifiedKey);

Parameters

key[in]
An IXMLDSigKey object obtained from one of the following methods: createKeyFromNode, createKeyFromHMACSecret, or createKeyFromHACSecretBinary. If NULL, this method obtains the required key information from the Signature/KeyInfo/(KeyValue|X509Data) elements.

verifiedKey[out, retval]
The IXMLDSigKey object actually used to verify. NULL if the signature and digest values are invalid and the method fails.

Return Values

S_OK
Signature verification succeeded.

S_FALSE
Signature or digest are invalid.

E_FAIL
Signature verification failed.

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

Remarks

A valid signature with legitimate digest and signature values and appropriate key information, as opposed to a signature template, must be set to the signature property before this method is called. For more information see the signature property.

To verify signatures, your code must perform the following tasks:

  1. Canonicalize <ds:SignedInfo> using the algorithm named in the <ds:CanonicalizationMethod>.

  2. Calculate the digest of canonicalized <ds:SignedInfo> using the SHA1 algorithm

  3. Verify the signature value (<ds:SignatureValue>) using the provided or embedded key and the digest obtained in the previous step.

  4. If the signature values do not match, the method returns and the verification is deemed failed and the output verifiedKey parameter is set to NULL. Otherwise it continues.

  5. Walk through the <ds:Reference> elements, perform all specified transforms, compute the digest, and compare it with the <ds:DigestValue> content of each entry.

  6. If all computed digest and signature values match their declared counterparts, the signature is deemed valid and the key used is returned as the output parameter to the caller. Otherwise, the signature is invalid and the output key object is set to NULL.

After the verify method returns successfully, you can call getVerifyingCertificate or getVerifyingCertificateContext to retrieve existing certificates and verify their validity using either CryptoAPI or CAPICOM.

If an embedded key contains a <ds:RetrievalMethod> element, an additional query of the key will be made using the method declared in this element. A valid <ds:RetrieveMethod> element must contain a valid URI attribute and may or may not contain <ds:transforms>.

Example

This example illustrates how to use the verify method to verify a signature.

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

See Also

sign Method
signature Property
createKeyFromNode Method
createKeyFromHMACSecret Method