XMLVerifier Module

Properties   Methods   Events   Config Settings   Errors  

The XMLVerifier module verifies signed XML files.

Syntax

SecureBlackbox.Xmlverifier

Remarks

Use this control to validate XML-SIG signatures. Note that this component only validates the signatures, but not the signing chains. To validate the signing chains, use XAdESVerifier.

Property List

The following is the full list of the properties of the module with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the module with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the module with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the module with short descriptions. Click on the links for further details.

AllSignaturesValid Property (XMLVerifier Module)

The cumulative validity of all signatures.

Syntax

• Swift
• Objective-C

public var allSignaturesValid: Bool {
  get {...}
}

@property (nonatomic,readonly,assign,getter=allSignaturesValid) BOOL allSignaturesValid;

- (BOOL)allSignaturesValid;

Default Value

False

Remarks

Use this property to check if all the signatures found in the message or document are valid.

This property is read-only.

AutoValidateSignatures Property (XMLVerifier Module)

Specifies whether module should validate any present signatures when the document is opened.

Syntax

• Swift
• Objective-C

public var autoValidateSignatures: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=autoValidateSignatures,setter=setAutoValidateSignatures:) BOOL autoValidateSignatures;

- (BOOL)autoValidateSignatures;
- (void)setAutoValidateSignatures :(BOOL)newAutoValidateSignatures;

Default Value

True

Remarks

This setting is switched on by default. You can choose to set this property to false in order to validate the signatures manually on a later stage using the Revalidate method.

Certificates Property (XMLVerifier Module)

A collection of certificates included in the electronic signature.

Syntax

• Swift
• Objective-C

public var certificates: Array<Certificate> {
  get {...}
}

@property (nonatomic,readonly,assign,getter=certCount) int certCount;

- (int)certCount;

- (NSData*)certBytes:(int)certIndex;

- (BOOL)certCA:(int)certIndex;

- (NSData*)certCAKeyID:(int)certIndex;

- (NSString*)certCRLDistributionPoints:(int)certIndex;

- (NSString*)certCurve:(int)certIndex;

- (NSData*)certFingerprint:(int)certIndex;

- (NSString*)certFriendlyName:(int)certIndex;

- (long long)certHandle:(int)certIndex;

- (NSString*)certHashAlgorithm:(int)certIndex;

- (NSString*)certIssuer:(int)certIndex;

- (NSString*)certIssuerRDN:(int)certIndex;

- (NSString*)certKeyAlgorithm:(int)certIndex;

- (int)certKeyBits:(int)certIndex;

- (NSData*)certKeyFingerprint:(int)certIndex;

- (int)certKeyUsage:(int)certIndex;

- (BOOL)certKeyValid:(int)certIndex;

- (NSString*)certOCSPLocations:(int)certIndex;

- (NSString*)certPolicyIDs:(int)certIndex;

- (NSData*)certPublicKeyBytes:(int)certIndex;

- (BOOL)certSelfSigned:(int)certIndex;

- (NSData*)certSerialNumber:(int)certIndex;

- (NSString*)certSigAlgorithm:(int)certIndex;

- (NSString*)certSubject:(int)certIndex;

- (NSData*)certSubjectKeyID:(int)certIndex;

- (NSString*)certSubjectRDN:(int)certIndex;

- (NSString*)certValidFrom:(int)certIndex;

- (NSString*)certValidTo:(int)certIndex;

Default Value

""

Remarks

Use this property to access all certificates included into the signature(s) by its creator.

DataBytes Property (XMLVerifier Module)

Use this property to pass the external data to module in the byte array form.

Syntax

• Swift
• Objective-C

public var dataBytes: Data {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=dataBytes,setter=setDataBytes:) NSData* dataBytes;

- (NSData*)dataBytes;
- (void)setDataBytes :(NSData*)newDataBytes;

Remarks

Assign a byte array containing the external data to be processed to this property.

DataFile Property (XMLVerifier Module)

A file containing the external data covered by a detached signature.

Syntax

• Swift
• Objective-C

public var dataFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=dataFile,setter=setDataFile:) NSString* dataFile;

- (NSString*)dataFile;
- (void)setDataFile :(NSString*)newDataFile;

Default Value

""

Remarks

In the case of a detached signature, use this property to provide the external data to the class from a file. Alternatively, provide the data via DataStream.

DataType Property (XMLVerifier Module)

Specifies the external data type.

Syntax

• Swift
• Objective-C

public var dataType: XmlverifierDataTypes {
  get {...}
  set {...}
}

public enum XmlverifierDataTypes: Int32 {
  case cxdtXML = 0
  case cxdtBinary = 1
  case cxdtBase64 = 2
}

@property (nonatomic,readwrite,assign,getter=dataType,setter=setDataType:) int dataType;

- (int)dataType;
- (void)setDataType :(int)newDataType;

Default Value

0

Remarks

Use this property to specify the type of the external data (either DataFile, DataStream or DataBytes properties) for class.

DataURI Property (XMLVerifier Module)

Specifies a detached data resource URI.

Syntax

• Swift
• Objective-C

public var dataURI: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=dataURI,setter=setDataURI:) NSString* dataURI;

- (NSString*)dataURI;
- (void)setDataURI :(NSString*)newDataURI;

Default Value

""

Remarks

Specifies a URI used for data being signed, usually the data filename if stored along with a detached signature.

Encoding Property (XMLVerifier Module)

Specifies XML encoding.

Syntax

• Swift
• Objective-C

public var encoding: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=encoding,setter=setEncoding:) NSString* encoding;

- (NSString*)encoding;
- (void)setEncoding :(NSString*)newEncoding;

Default Value

""

Remarks

Use this property to specify the encoding to apply to the XML documents.

FIPSMode Property (XMLVerifier Module)

Reserved.

Syntax

• Swift
• Objective-C

public var fipsMode: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=FIPSMode,setter=setFIPSMode:) BOOL FIPSMode;

- (BOOL)FIPSMode;
- (void)setFIPSMode :(BOOL)newFIPSMode;

Default Value

False

Remarks

This property is reserved for future use.

InputBytes Property (XMLVerifier Module)

Use this property to pass the input to module in byte array form.

Syntax

• Swift
• Objective-C

public var inputBytes: Data {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputBytes,setter=setInputBytes:) NSData* inputBytes;

- (NSData*)inputBytes;
- (void)setInputBytes :(NSData*)newInputBytes;

Remarks

Assign a byte array containing the data to be processed to this property.

InputFile Property (XMLVerifier Module)

A signed XML file.

Syntax

• Swift
• Objective-C

public var inputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputFile,setter=setInputFile:) NSString* inputFile;

- (NSString*)inputFile;
- (void)setInputFile :(NSString*)newInputFile;

Default Value

""

Remarks

Provide a path to the signed XML document in this property.

KnownCertificates Property (XMLVerifier Module)

Additional certificates for chain validation.

Syntax

• Swift
• Objective-C

public var knownCertificates: Array<Certificate> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=knownCertCount,setter=setKnownCertCount:) int knownCertCount;

- (int)knownCertCount;
- (void)setKnownCertCount :(int)newKnownCertCount;

- (NSData*)knownCertBytes:(int)knownCertIndex;

- (long long)knownCertHandle:(int)knownCertIndex;
- (void)setKnownCertHandle:(int)knownCertIndex :(long long)newKnownCertHandle;

Default Value

""

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the class manually.

The purpose of the certificates to be added to this collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

OutputBytes Property (XMLVerifier Module)

Use this property to read the output the module object has produced.

Syntax

• Swift
• Objective-C

public var outputBytes: Data {
  get {...}
}

@property (nonatomic,readonly,assign,getter=outputBytes) NSData* outputBytes;

- (NSData*)outputBytes;

Remarks

Read the contents of this property after the operation has completed to read the produced output. This property will only be set if the OutputFile and OutputStream properties had not been assigned.

This property is read-only.

OutputFile Property (XMLVerifier Module)

The file where the modified signed document will be saved.

Syntax

• Swift
• Objective-C

public var outputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=outputFile,setter=setOutputFile:) NSString* outputFile;

- (NSString*)outputFile;
- (void)setOutputFile :(NSString*)newOutputFile;

Default Value

""

Remarks

Provide the full path to the file where the modified signed document should be saved.

References Property (XMLVerifier Module)

References covered by the signature.

Syntax

• Swift
• Objective-C

public var references: Array<XMLReference> {
  get {...}
}

@property (nonatomic,readonly,assign,getter=referenceCount) int referenceCount;

- (int)referenceCount;

- (BOOL)referenceAutoGenerateElementId:(int)referenceIndex;

- (int)referenceCanonicalizationMethod:(int)referenceIndex;

- (NSString*)referenceCustomElementId:(int)referenceIndex;

- (NSData*)referenceDigestValue:(int)referenceIndex;

- (long long)referenceHandle:(int)referenceIndex;

- (NSString*)referenceHashAlgorithm:(int)referenceIndex;

- (BOOL)referenceHasURI:(int)referenceIndex;

- (NSString*)referenceID:(int)referenceIndex;

- (NSString*)referenceInclusiveNamespacesPrefixList:(int)referenceIndex;

- (NSString*)referenceReferenceType:(int)referenceIndex;

- (int)referenceSignatureIndex:(int)referenceIndex;

- (NSData*)referenceTargetData:(int)referenceIndex;

- (int)referenceTargetType:(int)referenceIndex;

- (NSString*)referenceTargetXMLElement:(int)referenceIndex;

- (NSString*)referenceURI:(int)referenceIndex;

- (BOOL)referenceUseBase64Transform:(int)referenceIndex;

- (BOOL)referenceUseEnvelopedSignatureTransform:(int)referenceIndex;

- (BOOL)referenceUseXPathFilter2Transform:(int)referenceIndex;

- (BOOL)referenceUseXPathTransform:(int)referenceIndex;

- (NSString*)referenceXPathExpression:(int)referenceIndex;

- (NSString*)referenceXPathFilter2Expressions:(int)referenceIndex;

- (NSString*)referenceXPathFilter2Filters:(int)referenceIndex;

- (NSString*)referenceXPathFilter2PrefixList:(int)referenceIndex;

- (NSString*)referenceXPathPrefixList:(int)referenceIndex;

Default Value

""

Remarks

Use this property to get the references to the data covered by the signature.

Signatures Property (XMLVerifier Module)

All signatures found in the XML document.

Syntax

• Swift
• Objective-C

public var signatures: Array<XMLSignature> {
  get {...}
}

@property (nonatomic,readonly,assign,getter=signatureCount) int signatureCount;

- (int)signatureCount;

- (int)signatureCanonicalizationMethod:(int)signatureIndex;

- (int)signatureCertificateIndex:(int)signatureIndex;

- (long long)signatureHandle:(int)signatureIndex;

- (NSString*)signatureHashAlgorithm:(int)signatureIndex;

- (NSString*)signatureIssuerRDN:(int)signatureIndex;

- (NSData*)signatureSerialNumber:(int)signatureIndex;

- (NSData*)signatureSignatureBytes:(int)signatureIndex;

- (int)signatureSignatureType:(int)signatureIndex;

- (int)signatureSignatureValidationResult:(int)signatureIndex;

- (NSData*)signatureSubjectKeyID:(int)signatureIndex;

- (NSString*)signatureSubjectRDN:(int)signatureIndex;

- (NSString*)signatureXMLElement:(int)signatureIndex;

Default Value

""

Remarks

This property contains a list of all signatures made over the XML document.

XPathNamespaces Property (XMLVerifier Module)

Specifies namespaces for the XPath expression.

Syntax

• Swift
• Objective-C

public var xPathNamespaces: Array<XMLNamespace> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=namespaceCount,setter=setNamespaceCount:) int namespaceCount;

- (int)namespaceCount;
- (void)setNamespaceCount :(int)newNamespaceCount;

- (NSString*)namespacePrefix:(int)namespaceIndex;
- (void)setNamespacePrefix:(int)namespaceIndex :(NSString*)newNamespacePrefix;

- (NSString*)namespaceURI:(int)namespaceIndex;
- (void)setNamespaceURI:(int)namespaceIndex :(NSString*)newNamespaceURI;

Default Value

""

Remarks

This property contains a list of prefixes and namespaceURIs that are used in XPath expression with TargetXMLElement property of the references.

Close Method (XMLVerifier Module)

Closes an opened document.

Syntax

• Swift
• Objective-C

public func close(saveChanges: Bool) throws -> Void

- (void)close:(BOOL)saveChanges;

Remarks

Use this method to close a previously opened document. Set SaveChanges to true to apply any changes made.

Config Method (XMLVerifier Module)

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config:(NSString*)configurationString;

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DoAction Method (XMLVerifier Module)

Performs an additional action.

Syntax

• Swift
• Objective-C

public func doAction(actionID: String, actionParams: String) throws -> String

- (NSString*)doAction:(NSString*)actionID :(NSString*)actionParams;

Remarks

DoAction is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

GetInnerXML Method (XMLVerifier Module)

Get the inner XML content of the selected XML element.

Syntax

• Swift
• Objective-C

public func getInnerXML(xPath: String) throws -> String

- (NSString*)getInnerXML:(NSString*)XPath;

Remarks

Call this method to get the inner XML content of the selected XML element.

GetOuterXML Method (XMLVerifier Module)

Get the outer XML content of the selected XML element.

Syntax

• Swift
• Objective-C

public func getOuterXML(xPath: String) throws -> String

- (NSString*)getOuterXML:(NSString*)XPath;

Remarks

Call this method to get the outer XML content of the selected XML element.

GetTextContent Method (XMLVerifier Module)

Get the text content of the selected XML element.

Syntax

• Swift
• Objective-C

public func getTextContent(xPath: String) throws -> String

- (NSString*)getTextContent:(NSString*)XPath;

Remarks

Call this method to get the text content of the selected XML element.

Open Method (XMLVerifier Module)

Opens a document for verifying or removing signatures.

Syntax

• Swift
• Objective-C

public func open() throws -> Void

- (void)open;

Remarks

Use this method to open a document for verifying or removing signatures. When finished, call Close to complete or discard the operation.

Revalidate Method (XMLVerifier Module)

Revalidates a signature in accordance with current settings.

Syntax

• Swift
• Objective-C

public func revalidate(index: Int32, detached: Bool) throws -> Void

- (void)revalidate:(int)index :(BOOL)detached;

Remarks

Use this method to re-validate a signature in the opened XML document.

SetInnerXML Method (XMLVerifier Module)

Set the inner XML content of the selected XML element.

Syntax

• Swift
• Objective-C

public func setInnerXML(xPath: String, value: String) throws -> Void

- (void)setInnerXML:(NSString*)XPath :(NSString*)value;

Remarks

Call this method to set the inner XML content of the selected XML element.

SetTextContent Method (XMLVerifier Module)

Set the text content of the selected XML element.

Syntax

• Swift
• Objective-C

public func setTextContent(xPath: String, value: String) throws -> Void

- (void)setTextContent:(NSString*)XPath :(NSString*)value;

Remarks

Call this method to set the text content of the selected XML element.

Unsign Method (XMLVerifier Module)

Deletes a signature from the document.

Syntax

• Swift
• Objective-C

public func unsign(sigIndex: Int32) throws -> Void

- (void)unsign:(int)sigIndex;

Remarks

Use this method to delete an existing signature from the document. Use SigIndex parameter to specify the signature to be removed.

Verify Method (XMLVerifier Module)

Verifies a signed XML document.

Syntax

• Swift
• Objective-C

public func verify() throws -> Void

- (void)verify;

Remarks

Call this method to verify the signature embedded in the document. Pass the document via InputStream or InputFile property. Use VerifyDetached to verify the external data in case of a detached signature.

VerifyDetached Method (XMLVerifier Module)

Verifies a detached signature over external XML data.

Syntax

• Swift
• Objective-C

public func verifyDetached() throws -> Void

- (void)verifyDetached;

Remarks

Call this method to verify a signature over external (detached) data provided via DataStream or DataFile.

DocumentLoaded Event (XMLVerifier Module)

This event is fired when the document has been loaded into memory.

Syntax

• Swift
• Objective-C

func onDocumentLoaded(cancel: inout Bool)

- (void)onDocumentLoaded:(int*)cancel;

Remarks

The handler for this event is a good place to check document properties, which may be useful when preparing the signature, for example, the document format.

Set Cancel to true to terminate document processing on this stage.

Error Event (XMLVerifier Module)

Information about errors during signature verification.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError:(int)errorCode :(NSString*)description;

Remarks

The event is fired in case of exceptional conditions during verification.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to XML.

Notification Event (XMLVerifier Module)

This event notifies the application about an underlying control flow event.

Syntax

• Swift
• Objective-C

func onNotification(eventID: String, eventParam: String)

- (void)onNotification:(NSString*)eventID :(NSString*)eventParam;

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the class, the exact action it is performing, or the document being processed, one or both may be omitted.

ReferenceValidated Event (XMLVerifier Module)

Marks the end of a reference validation.

Syntax

• Swift
• Objective-C

func onReferenceValidated(referenceIndex: Int32, id: String, uri: String, refType: String, digestValid: Bool)

- (void)onReferenceValidated:(int)referenceIndex :(NSString*)ID :(NSString*)URI :(NSString*)refType :(BOOL)digestValid;

Remarks

The class fires this event to report completion of a reference validation. A reference is a building block of a signature as it binds signature coverage to a particular piece of the document.

ResolveReference Event (XMLVerifier Module)

Asks the application to resolve a reference.

Syntax

• Swift
• Objective-C

func onResolveReference(referenceIndex: Int32, uri: String)

- (void)onResolveReference:(int)referenceIndex :(NSString*)URI;

Remarks

This event is fired when the control could not automatically resolve a reference and requires custom treatment.

URI contains a reference to the data.

ReferenceIndex specifies the index of the reference to process.

Based on the reference's URI the event handler should set either TargetXMLElement or TargetData property of the reference.

SignatureFound Event (XMLVerifier Module)

Signifies the start of signature validation.

Syntax

• Swift
• Objective-C

func onSignatureFound(index: Int32, issuerRDN: String, serialNumber: Data, subjectKeyID: Data, certFound: Bool, validateSignature: inout Bool, validateChain: inout Bool)

- (void)onSignatureFound:(int)index :(NSString*)issuerRDN :(NSData*)serialNumber :(NSData*)subjectKeyID :(BOOL)certFound :(int*)validateSignature :(int*)validateChain;

Remarks

This event tells the application that signature validation is about to start, and provides the details about the signer's certificate via its IssuerRDN, SerialNumber, and SubjectKeyID parameters. It fires for every signature located in the verified document or message.

The CertFound parameter is set to True if the class has found the needed certificate in one of the known locations, and to False otherwise, in which case you must provide it manually via the KnownCertificates property.

Signature validation consists of two independent stages: cryptographic signature validation and chain validation. Separate validation results are reported for each, with the and properties respectively.

Use the ValidateSignature and ValidateChain parameters to tell the verifier which stages to include in the validation.

SignatureValidated Event (XMLVerifier Module)

Reports the signature validation result.

Syntax

• Swift
• Objective-C

func onSignatureValidated(sigIndex: Int32, issuerRDN: String, serialNumber: Data, subjectKeyID: Data, validationResult: Int32)

- (void)onSignatureValidated:(int)sigIndex :(NSString*)issuerRDN :(NSData*)serialNumber :(NSData*)subjectKeyID :(int)validationResult;

Remarks

This event is fired when the complete XML signature validation process is finished. IssuerRDN returns the name of the signature issuer, SerialNumber identifies the signing certificate, SubjectKeyID contains the key identifier (SecureBlackbox uses SHA-1 hash algorithm output as key identifiers). Finally, ValidationResult specifies whether signature is valid or not:

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

public init(stream: )

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

public init()

Creates a new object with default field values.

XMLNamespace Type

Represents an XML namespace map for XPath expressions.

Remarks

This class defines the correspondence between Prefixes and namespace URIs.

Fields

Constructors

public init()

Creates a new XML namespace object.

XMLReference Type

Represents an XML reference element.

Remarks

XMLReference specifies the digest algorithm and digest value, and, optionally: an identifier of the object being signed, the type of the object, and/or a list of transforms to be applied prior to digesting.

Fields

Constructors

public init()

Creates a new XML reference element.

public init(iD: )

Creates a new XML reference element from its ID .

public init(iD: , uRI: )

Creates a new XML reference element from its ID and URI reference to the external data.

XMLSignature Type

The component is a container for an XML signature.

Remarks

XML document may include any number of XML signatures. class stores on of them.

Fields

Constructors

public init()

Creates a new XML signature object.

Config Settings (XMLVerifier Module)

XMLVerifier Config Settings

Base Config Settings

Trappable Errors (XMLVerifier Module)

XMLVerifier Errors