XMLSignatureValidator  - AS3

The validity status of the cryptographic signature computed over the signature SignedInfo element.

The status is:

• valid — If signature is cryptographically valid.
• invalid — If the digest has been altered after signing.
• unknown — If the verify() method has not been called.

Note: If the digestStatus is invalid, the identityStatus and referencesStatus are not checked and will be reported as unknown.

The validity status of the signing certificate.

The status can be:

• valid — The certificate has not expired, has not failed a revocation check and chains to a trusted root certificate.
• unknown — The certificate has not expired and has not failed a revocation check, but does not chain to a trusted root certificate. A status of unknown will also be reported when the status has not been verified, either because the verify() method has not been called or because the cryptographic signature of the SignedInfo element (digestStatus) is invalid.
• invalid — The certificate has expired or fails a revocation check.

The certificates added using the addCertificate() method and the settings of the revocationCheckSetting and the useSystemTrustStore properties can change whether a certificate is considered valid.

Note: If the identityStatus is invalid, the referencesStatus is not checked and will be reported as unknown. In addition, references are not checked when the identityStatus is unknown unless the referencesValidationSetting is validOrUnknownIdentity

Related API Elements

 import flash.security.XMLSignatureValidator;
 
 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator();
 //validate a signature...
  
 var identityResult:String = verifier.identityStatus;

The isSupported property is set to true if the XMLSignatureValidator class is supported on the current platform, otherwise it is set to false.

The validity status of the data in the references in the signature SignedInfo element.

The status can be:

• valid — If all references are valid.
• invalid — If any reference is invalid.
• unknown — If not verified. References can remain unverified in the following circumstances:
  • the verify() method has not been called
  • the cryptographic signature of the SignedInfo element (digestStatus) is invalid.
  • the signing certificate (identityStatus) is invalid
  • referencesValidationSetting is validIdentity (which is the default setting) and the identityStatus of the signing certificate is unknown.
  • the referencesValidationSetting is never.

Important: External resources are not validated unless they are referenced directly in a SignedInfo element within the signature document. External resources referred to by a secondary reference are not validated. For example, if an XML signature signs a manifest element, only the integrity of the manifest element itself is verified. The files listed in the manifest are not checked.

Related API Elements

 import flash.security.XMLSignatureValidator;
 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator();
 //validate a signature...
  
 var dataResult:String = verifier.referencesStatus;

Specifies the conditions under which references are checked.

Use constants defined in the ReferencesValidationSetting class to set this property. The settings include:

• ReferencesValidationSetting.VALID_IDENTITY — Check references only if the signing certificate is valid and chains to a trusted root. This is the default setting.
• ReferencesValidationSetting.VALID_OR_UNKNOWN_IDENTITY — Check references if the signing certificate is valid, even if it does not chain to a trusted root.
• ReferencesValidationSetting.NEVER — Never check references.

Use the default, validIdentity, setting with signatures signed with a commercial certificate or when you supply your own certificate as a trust anchor with the addCertificate() method. This setting avoids the overhead of checking reference validity when the signed document will be rejected anyway.

Use the validOrUnknownIdentity setting with signatures signed with self-signed certificates. This setting allows you to validate that the signed data has not been altered, but does not provide any assurances about the identity of the signer.

Use the never setting to avoid the overhead of validating references when such validation is not important in the context of your application.

Related API Elements

 import flash.security.ReferencesValidationSetting;
 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator(); 
 verifier.referencesValidationSetting = ReferencesValidationSetting.VALID_OR_UNKNOWN_IDENTITY;

Specifies how certificate revocation is checked.

Use constants defined in the RevocationSettings class to set this property. The settings include:

• RevocationCheckSettings.NEVER — Do not check certificate revocation.
• RevocationCheckSettings.BEST_EFFORT — Check certificate revocation, if revocation information is available and the revocation status can be obtained. If revocation status cannot be positively determined, the certificate is not rejected.
• RevocationCheckSettings.REQUIRED_IF_AVAILABLE — If the certificate includes revocation information, the revocation status must be positively determined to validate the certificate.
• RevocationCheckSettings.ALWAYS_REQUIRED — Always check certificate revocation. Certificates without revocation information are rejected.

Related API Elements

The Common Name field of the signing certificate.

 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator();
 //validate a signature...
  
 var commonName:String = verifier.signerCN;

The Distinguished Name field of the signing certificate.

 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator();
 //validate a signature...
  
 var distinguishedName:String = verifier.signerDN;

An array containing the Extended Key Usages OIDs listed in the signing certificate.

Each extended key usage is reported in numeric OID form.

 import flash.security.XMLSignatureValidator;
 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator();
 //validate a signature...
  
 var extendedKeyOIDs:Array = verifier.signerExtendedKeyUsages;

An array containing the trust settings of the signing certificate.

Trust settings are derived from the system and the key usage OIDs embedded in the certificate. Constants for the strings representing the recognized trust settings are defined in the SignerTrustSettings class.

The signerTrustSettings array of an unknown or invalid certificate is empty.

Modifying the array does not change the certificate trust settings.

Related API Elements

 import flash.security.XMLSignatureValidator;
 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator();
 //validate a signature...
  
 var certificateTrustedFor:Array = verifier.signerTrustSettings;

The IURIDereferencer implementation.

An IURIDereferencer implementation must be provided before attempting to verify a signature.

Related API Elements

 import com.example.SignedMessageDereferencer; //A custom class implementing IURIDereferencer
 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator(); 
 verifier.uriDereferencer = new SignedMessageDereferencer();

Specifies that certificates in the system trust store are used for chain building.

If true, then the trust anchors in the system trust store are used as trusted roots. The system trust store is not used by default.

 var verifier:XMLSignatureValidator = new XMLSignatureValidator(); 
 verifier.useSystemTrustStore = true;

The validity status of a verified XML signature.

The XML signature is verified by validating the the cryptographic signature of the SignedInfo element, the signing certificate, and the data addressed by the references in the SignedInfo element. The validity of each of these elements is reported individually by the digestStatus, identityStatus(), and referencesStatus properties, respectively.

The validity of an XML signature can be valid, invalid, or unknown. The overall status depends on the verification status of the individual components of the signature file:

• digestStatus — The validity of the cryptographic signature computed over the SignedInfo element.
• identityStatus — The validity of the signing certificate.
• referencesStatus — The validity of the digest of the references in the signature SignedInfo element.

The signature validity reported by the validityStatus property can be:

• valid — If referencesStatus, digestStatus, and identityStatus are all valid.
• invalid — If any individual status is invalid.
• unknown — If any individual status is unknown.

Related API Elements

 import flash.security.XMLSignatureValidator;
 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator();
 //validate the signature...
  
 var validationResult:String = verifier.validityStatus;

Creates an XMLSignatureValidator object.

You must set the uriDereferencer property before calling the verify() method of the new object.

Related API Elements

 
import com.example.EnvelopedDereferencer; //Your custom IURIDereferencer implementation

//Create the object
var verifier:XMLSignatureValidator = new XMLSignatureValidator();

//Provide the IURIDerferencer
verifier.uriDereferencer = new EnvelopedDereferencer(xmlDoc);

//Set validation options
verifier.referencesValidationSetting = ReferencesValidationSetting.VALID_OR_UNKNOWN_IDENTITY;
verifier.revocationCheckSetting = RevocationCheckSettings.NEVER;
verifier.useSystemTrustStore = true;

//Add listeners to handle results
verifier.addEventListener(Event.COMPLETE, verificationComplete);
verifier.addEventListener(ErrorEvent.ERROR, verificationError);

Adds an x509 certificate for chain building.

The certificate added must be a DER-encoded x509 certificate.

If the trusted parameter is true, the certificate is considered a trust anchor.

Note: An XML signature may include certificates for building the signer's certificate chain. The XMLSignatureValidator class uses these certificates for chain building, but not as trusted roots (by default).

Parameters

 import flash.utils.ByteArray;
 
 var verifier:XMLSignatureValidator = new XMLSignatureValidator();
 var certificate:ByteArray = new ByteArray();
 
 var certFile:File = new File("certificate.cer");
 var certFileStream:FileStream = new FileStream();
 certFileStream.open(certFile, FileMode.READ);
 certFileStream.readBytes(certificate, 0, certFileStream.bytesAvailable);

 verifier.addCertificate(certificate, true);

Verifies the specified signature.

Verification is asynchronous. The XMLSignatureValidator object dispatches a complete event when verification completes successfully or an error event if verification cannot complete because of errors.

The verification process cannot be cancelled. While a verification process is under way, subsequent calls to the verify() method fail. After the current verification check is complete, you can call the verify() method again.

Note: Because the XMLSignatureValidator only implements a subset of the W3C recommendation for XML Signature Syntax and Processing, not all valid XML signatures can be verified.

Parameters

import flash.filesystem.File;
import flash.filesystem.FileStream;
import com.example.SignedMessageDereferencer; //Your IURIDereferencer implementation
 
const xmlSignatureNS:Namespace = new Namespace( "http://www.w3.org/2000/09/xmldsig#" );

var verifier:XMLSignatureValidator = new XMLSignatureValidator();
verifier.uriDereferencer = new SignedMessageDereferencer();

var signatureFile:File = new File( "path/to/XMLSignatureDocument.xml" );
var sigFileStream:FileStream = new FileStream();
sigFileStream.open( signatureFile, FileMode.READ );

var xmlDoc:XML = XML( sigFileStream.readUTFBytes(sigFileStream.bytesAvailable) );
var xmlSig:XML = XML( xmlDoc..xmlSignatureNS::Signature );

verifier.verify( xmlSig );

Dispatched when verification is complete.

A complete event does not imply that the signature is valid. Check the validityStatus property of the XMLSignatureValidator object to determine the outcome of the signature verification.

This event has the following properties:

private function verificationComplete(event:Event):void{
    var validator:XMLSignatureValidator = event.target as XMLSignatureValidator;
    trace("Digest status: " + validator.digestStatus);
    trace("Identity status: " + validator.identityStatus);
    trace("Reference status: " + validator.referencesStatus);
    trace("Signature status: " + validator.validityStatus);    
}

Related API Elements

Dispatched if verification cannot complete because of errors.

This event has the following properties:

private function verificationError(event:ErrorEvent):void{
    trace("Verification error: " + event.text);                
}