XMLVerifier Component

Properties Methods Events Config Settings Errors

The XMLVerifier component provides simplified XML signature validation capabilities.

Syntax

nsoftware.SecureBlackbox.XMLVerifier

Remarks

Use this control to validate XML-SIG signatures. XMLVerifier is capable of validating the integrity of the references covered by the signature and the integrity of the signature itself, using the certificate contained in the signature or provided from the user' code.

Note that this component only validates the cryptographic aspects of the signatures, but does not perform any chain of trust validation. As such, it is the task of your code to ensure that the signing certificate is good for its purpose and is trusted in your environment.

If you are looking to validate certificate trust in addition to the cryptographic capabilities, please consider using XAdESVerifier. XAdESVerifier provides full support for advanced signature ecosystem, including revocation and Trusted List checking, timing checks, and chain of trust validation.

Property List

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


AllSignaturesValid	The cumulative validity of all signatures.
AutoValidateSignatures	Specifies whether component should validate any present signatures when the document is opened.
Certificates	A collection of certificates included in the electronic signature.
DataBytes	Use this property to pass the external data to component in the byte array form.
DataFile	A file containing the external data covered by a detached signature.
DataStream	Standalone data covered by the signature.
DataType	Specifies the external data type.
DataURI	Specifies a detached data resource URI.
Encoding	Specifies XML encoding.
FIPSMode	Reserved.
InputBytes	Use this property to pass the input to component in byte array form.
InputFile	A signed XML file.
InputStream	A stream containing the signed XML document.
KnownCertificates	Additional certificates for chain validation.
OutputBytes	Use this property to read the output the component object has produced.
OutputFile	The file where the modified signed document will be saved.
OutputStream	A stream where to save the modified signed document.
References	References covered by the signature.
Signatures	All signatures found in the XML document.

Method List

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


AddKnownNamespace	Adds known prefix and correspondent namespace URI.
Close	Closes an opened document.
Config	Sets or retrieves a configuration setting.
DoAction	Performs an additional action.
GetInnerXML	Get the inner XML content of the selected XML element.
GetOuterXML	Get the outer XML content of the selected XML element.
GetSignedData	Returns the part of the XML document that is covered by the signature.
GetTextContent	Get the text content of the selected XML element.
Open	Opens a document for verifying or removing signatures.
Reset	Resets the component settings.
Revalidate	Revalidates a signature in accordance with current settings.
SelectInfo	Select signature information for a specific entity.
SetInnerXML	Set the inner XML content of the selected XML element.
SetTextContent	Set the text content of the selected XML element.
Unsign	Deletes a signature from the document.
Verify	Verifies a signed XML document.
VerifyDetached	Verifies a detached signature over external XML data.

Event List

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


DocumentLoaded	This event is fired when the document has been loaded into memory.
Error	Information about errors during signature verification.
Notification	This event notifies the application about an underlying control flow event.
ReferenceValidated	Marks the end of a reference validation.
ResolveReference	Asks the application to resolve a reference.
SignatureFound	Signifies the start of signature validation.
SignatureValidated	Marks the completion of the signature validation routine.

Config Settings

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


AddAllDataObjectsTimestamp	Whether to add all data objects timestamp during signing.
ClaimedRolesXML	The XML content of the claimed roles.
ClaimedRoleText	The text of the claimed role.
CommitmentTypeIndicationAllSignedDataObjects[Index]	Specifies the CommitmentTypeIndication's AllSignedDataObjects.
CommitmentTypeIndicationCount	The number of the CommitmentTypeIndication elements.
CommitmentTypeIndicationIdentifier[Index]	Specifies the CommitmentTypeIndication's CommitmentTypeId's Identifier.
CommitmentTypeIndicationIdentifierDescription[Index]	Specifies the CommitmentTypeIndication's CommitmentTypeId's Description.
CommitmentTypeIndicationIdentifierDocumentationReferences[Index]	Specifies the CommitmentTypeIndication's CommitmentTypeId's DocumentationReferences.
CommitmentTypeIndicationIdentifierQualifier[Index]	Specifies the CommitmentTypeIndication's CommitmentTypeId's IdentifierQualifier.
CommitmentTypeIndicationObjectReference[Index]	Specifies the CommitmentTypeIndication's ObjectReference.
CommitmentTypeIndicationQualifiersXML[Index]	The XML content of the CommitmentTypeIndication's Qualifiers.
DataObjectFormatCount	The number of the DataObjectFormat elements.
DataObjectFormatDescription[Index]	Specifies the DataObjectFormat's Description.
DataObjectFormatEncoding[Index]	Specifies the DataObjectFormat's Encoding.
DataObjectFormatMimeType[Index]	Specifies the DataObjectFormat's MimeType.
DataObjectFormatObjectIdentifier[Index]	Specifies the DataObjectFormat's ObjectIdentifier's Identifier.
DataObjectFormatObjectIdentifierDescription[Index]	Specifies the DataObjectFormat's ObjectIdentifier's Description.
DataObjectFormatObjectIdentifierDocumentationReferences[Index]	Specifies the DataObjectFormat's ObjectIdentifier's DocumentationReferences.
DataObjectFormatObjectIdentifierQualifier[Index]	Specifies the DataObjectFormat's ObjectIdentifier's IdentifierQualifier.
DataObjectFormatObjectReference[Index]	Specifies the DataObjectFormat's ObjectReference.
DataType	Specifies the external data type.
DetachedResourceURI	Specifies a detached resource URI.
ExclusiveCanonicalizationPrefix	Specifies the exclusive canonicalization prefix.
HMACKey	The key value for HMAC.
HMACOutputLength	Sets the length of the HMAC output.
HMACSigningUsed	Whether to use HMAC signing.
IDAttributeName	Specifies the custom name of ID attribute.
IDAttributeNamespaceURI	Specifies the custom namespace URI of ID attribute.
IgnoreTimestampFailure	Whether to ignore time-stamping failure during signing.
IncludeKey	Specifies whether to include the signing key to the signature.
IncludeKeyValue	Specifies whether the key value must be included to the signature.
IncludeKnownRevocationInfoToSignature	Whether to include custom revocation info to the signature.
InclusiveNamespacesPrefixList	Specifies the InclusiveNamespaces PrefixList.
InsertBeforeXMLElement	Defines the reference XML element for signature insertion.
KeyInfoCustomXML	The custom XML content for KeyInfo element.
KeyInfoDetails	Specifies the signing key info details to include to the signature.
KeyInfoID	Specifies the ID for KeyInfo element.
KeyName	Contains information about the key used for signing.
ManifestCount	TBD.
ManifestID[i]	TBD.
ManifestObjectIndex[i]	TBD.
ManifestXML[i]	TBD.
NormalizeNewLine	Controls whether newline combinations should be automatically normalized.
ObjectCount	TBD.
ObjectEncoding[i]	TBD.
ObjectID[i]	TBD.
ObjectMimeType[i]	TBD.
ObjectSignaturePropertiesCount	TBD.
ObjectSignaturePropertiesID[i]	TBD.
ObjectSignaturePropertiesObjectIndex[i]	TBD.
ObjectSignaturePropertiesXML[i]	TBD.
ObjectSignaturePropertyCount	TBD.
ObjectSignaturePropertyID[i]	TBD.
ObjectSignaturePropertyPropertiesIndex[i]	TBD.
ObjectSignaturePropertyTarget[i]	TBD.
ObjectSignaturePropertyXML[i]	TBD.
ObjectXML[i]	TBD.
PolicyDescription	signature policy description.
PolicyExplicitText	The explicit text of the user notice.
PolicyUNNumbers	The noticeNumbers part of the NoticeReference CAdES attribute.
PolicyUNOrganization	The organization part of the NoticeReference qualifier.
ProductionPlace	Identifies the place of the signature production.
PSSUsed	Whether to use RSASSA-PSS algorithm.
QualifyingPropertiesID	Specifies the ID for QualifyingProperties element.
QualifyingPropertiesObjectID	Specifies the ID for object with QualifyingProperties element.
QualifyingPropertiesReferenceCount	The number of the QualifyingPropertiesReference elements.
QualifyingPropertiesReferenceID[Index]	Specifies the QualifyingPropertiesReference's ID.
QualifyingPropertiesReferenceURI[Index]	Specifies the QualifyingPropertiesReference's URI.
RefsTimestampType	Specifies references timestamp type to include to the signature.
SignatureCompliance	SIgnature compliance with XMLDSig/EBICS.
SignatureID	Specifies the ID for Signature element.
SignaturePrefix	Specifies the signature prefix.
SignatureValueID	Specifies the ID for SignatureValue element.
SignedInfoID	Specifies the ID for SignedInfo element.
SignedPropertiesID	Specifies the ID for SignedProperties element.
SignedPropertiesReferenceCanonicalizationMethod	Specifies the canonicalization method used in SignedProperties reference.
SignedPropertiesReferenceHashAlgorithm	Specifies the hash algorithm used in SignedProperties reference.
SignedPropertiesReferenceID	Specifies the ID for Reference element that points to SignedProperties element.
SignedPropertiesReferenceInclusiveNamespacesPrefixList	Specifies the InclusiveNamespaces PrefixList used in SignedProperties reference.
SignedPropertiesReferenceIndex	Specifies the index of SignedProperties reference.
SignedSignaturePropertiesID	Specifies the ID for SignedSignatureProperties element.
SigningCertificatesChain	The indicator of which certificates should be/are included as the signing chain.
SigningCertificatesHashAlgorithm	Specifies the hash algorithm used for SigningCertificates.
SigPolicyDescription	signature policy description.
SigPolicyExplicitText	The explicit text of the user notice.
SigPolicyHash	The EPES policy hash.
SigPolicyHashAlgorithm	The hash algorithm that was used to generate the EPES policy hash.
SigPolicyID	The EPES policy ID.
SigPolicyNoticeNumbers	The noticeNumbers part of the NoticeReference CAdES attribute.
SigPolicyNoticeOrganization	The organization part of the NoticeReference qualifier.
SigPolicyURI	The EPES policy URI.
StripWhitespace	Controls whether excessive whitespace characters should be stripped off when loading the document.
TimestampCanonicalizationMethod	Specifies canonicalization method used in timestamp.
TimestampValidationDataDetails	Specifies timestamp validation data details to include to the signature.
UseHMACSigning	Whether to use HMAC signing.
UsePSS	Whether to use RSASSA-PSS algorithm.
ValidationDataRefsDetails	Specifies validation data references details to include to the signature.
ValidationDataRefsHashAlgorithm	Specifies the hash algorithm used in validation data references.
ValidationDataValuesDetails	Specifies validation data values details to include to the signature.
WriteBOM	Specifies whether byte-order mark should be written when saving the document.
XAdESPrefix	Specifies the XAdES prefix.
XAdESv141Prefix	Specifies the XAdES v1.4.1 prefix.
XMLFormatting	Specifies the signature XML formatting.
ASN1UseGlobalTagCache	Controls whether ASN.1 module should use a global object cache.
AssignSystemSmartCardPins	Specifies whether CSP-level PINs should be assigned to CNG keys.
CheckKeyIntegrityBeforeUse	Enables or disable private key integrity check before use.
CookieCaching	Specifies whether a cookie cache should be used for HTTP(S) transports.
Cookies	Gets or sets local cookies for the component.
DefDeriveKeyIterations	Specifies the default key derivation algorithm iteration count.
DNSLocalSuffix	The suffix to assign for TLD names.
EnableClientSideSSLFFDHE	Enables or disables finite field DHE key exchange support in TLS clients.
GlobalCookies	Gets or sets global cookies for all the HTTP transports.
HardwareCryptoUsePolicy	The hardware crypto usage policy.
HttpUserAgent	Specifies the user agent name to be used by all HTTP clients.
HttpVersion	The HTTP version to use in any inner HTTP client components created.
IgnoreExpiredMSCTLSigningCert	Whether to tolerate the expired Windows Update signing certificate.
ListDelimiter	The delimiter character for multi-element lists.
LogDestination	Specifies the debug log destination.
LogDetails	Specifies the debug log details to dump.
LogFile	Specifies the debug log filename.
LogFilters	Specifies the debug log filters.
LogFlushMode	Specifies the log flush mode.
LogLevel	Specifies the debug log level.
LogMaxEventCount	Specifies the maximum number of events to cache before further action is taken.
LogRotationMode	Specifies the log rotation mode.
MaxASN1BufferLength	Specifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepth	Specifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithm	Specifies the hash algorithm to be used to identify certificates in OCSP requests.
OldClientSideRSAFallback	Specifies whether the SSH client should use a SHA1 fallback.
PKICache	Specifies which PKI elements (certificates, CRLs, OCSP responses) should be cached.
PKICachePath	Specifies the file system path where cached PKI data is stored.
ProductVersion	Returns the version of the SecureBlackbox library.
ServerSSLDHKeyLength	Sets the size of the TLS DHE key exchange group.
StaticDNS	Specifies whether static DNS rules should be used.
StaticIPAddress[domain]	Gets or sets an IP address for the specified domain name.
StaticIPAddresses	Gets or sets all the static DNS rules.
Tag	Allows to store any custom data.
TLSSessionGroup	Specifies the group name of TLS sessions to be used for session resumption.
TLSSessionLifetime	Specifies lifetime in seconds of the cached TLS session.
TLSSessionPurgeInterval	Specifies how often the session cache should remove the expired TLS sessions.
UseCRLObjectCaching	Specifies whether reuse of loaded CRL objects is enabled.
UseInternalRandom	Switches between SecureBlackbox-own and platform PRNGs.
UseLegacyAdESValidation	Enables legacy AdES validation mode.
UseOCSPResponseObjectCaching	Specifies whether reuse of loaded OCSP response objects is enabled.
UseOwnDNSResolver	Specifies whether the client components should use own DNS resolver.
UseSharedSystemStorages	Specifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemNativeSizeCalculation	An internal CryptoAPI access tweak.
UseSystemOAEPAndPSS	Enforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandom	Enables or disables the use of the OS PRNG.
XMLRDNDescriptorName[OID]	Defines an OID mapping to descriptor names for the certificate's IssuerRDN or SubjectRDN.
XMLRDNDescriptorPriority[OID]	Specifies the priority of descriptor names associated with a specific OID.
XMLRDNDescriptorReverseOrder	Specifies whether to reverse the order of descriptors in RDN.
XMLRDNDescriptorSeparator	Specifies the separator used between descriptors in RDN.

AllSignaturesValid Property (XMLVerifier Component)

The cumulative validity of all signatures.

public bool AllSignaturesValid { get; }

Public ReadOnly Property AllSignaturesValid As Boolean

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 and not available at design time.

AutoValidateSignatures Property (XMLVerifier Component)

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

Syntax

C#
VB.NET

public bool AutoValidateSignatures { get; set; }

Public Property AutoValidateSignatures As Boolean

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 Component)

A collection of certificates included in the electronic signature.

Syntax

C#
VB.NET

public CertificateList Certificates { get; }

Public ReadOnly Property Certificates As CertificateList

Remarks

This property includes a collection of certificates of the currently selected info.

This collection is indexed from 0 to count -1.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

DataBytes Property (XMLVerifier Component)

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

Syntax

C#
VB.NET

public byte[] DataBytes { get; set; }

Public Property DataBytes As Byte()

Remarks

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

This property is not available at design time.

DataFile Property (XMLVerifier Component)

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

Syntax

C#
VB.NET

public string DataFile { get; set; }

Public Property DataFile As String

Default Value

Remarks

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

DataStream Property (XMLVerifier Component)

Standalone data covered by the signature.

Syntax

C#
VB.NET

public System.IO.Stream DataStream { get; set; }

Public Property DataStream As System.IO.Stream

Default Value

null

Remarks

When validating a detached signature, use this stream property to provide the external (detached) data.

This property is not available at design time.

DataType Property (XMLVerifier Component)

Specifies the external data type.

Syntax

C#
VB.NET

public XMLVerifierDataTypes DataType { get; set; }

enum XMLVerifierDataTypes {
  cxdtXML,
  cxdtBinary,
  cxdtBase64
}

Public Property DataType As XmlverifierDataTypes

Enum XMLVerifierDataTypes
  cxdtXML
  cxdtBinary
  cxdtBase64
End Enum

Default Value

Remarks

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

DataURI Property (XMLVerifier Component)

Specifies a detached data resource URI.

Syntax

C#
VB.NET

public string DataURI { get; set; }

Public Property DataURI As String

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 Component)

Specifies XML encoding.

Syntax

C#
VB.NET

public string Encoding { get; set; }

Public Property Encoding As String

Default Value

Remarks

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

FIPSMode Property (XMLVerifier Component)

Reserved.

Syntax

C#
VB.NET

public bool FIPSMode { get; set; }

Public Property FIPSMode As Boolean

Default Value

False

Remarks

This property is reserved for future use.

InputBytes Property (XMLVerifier Component)

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

Syntax

C#
VB.NET

public byte[] InputBytes { get; set; }

Public Property InputBytes As Byte()

Remarks

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

This property is not available at design time.

InputFile Property (XMLVerifier Component)

A signed XML file.

Syntax

C#
VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

Remarks

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

InputStream Property (XMLVerifier Component)

A stream containing the signed XML document.

Syntax

C#
VB.NET

public System.IO.Stream InputStream { get; set; }

Public Property InputStream As System.IO.Stream

Default Value

null

Remarks

Use this property to pass a signed document to the component in a stream.

This property is not available at design time.

KnownCertificates Property (XMLVerifier Component)

Additional certificates for chain validation.

Syntax

C#
VB.NET

public CertificateList KnownCertificates { get; }

Public Property KnownCertificates As CertificateList

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 component 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.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

OutputBytes Property (XMLVerifier Component)

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

Syntax

C#
VB.NET

public byte[] OutputBytes { get; }

Public ReadOnly Property OutputBytes As Byte()

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 and not available at design time.

OutputFile Property (XMLVerifier Component)

The file where the modified signed document will be saved.

Syntax

C#
VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

Remarks

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

OutputStream Property (XMLVerifier Component)

A stream where to save the modified signed document.

Syntax

C#
VB.NET

public System.IO.Stream OutputStream { get; set; }

Public Property OutputStream As System.IO.Stream

Default Value

null

Remarks

Use this property to specify a stream to write the modified signed document to.

This property is not available at design time.

References Property (XMLVerifier Component)

References covered by the signature.

Syntax

C#
VB.NET

public XMLReferenceList References { get; }

Public ReadOnly Property References As XMLReferenceList

Remarks

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

This property is read-only and not available at design time.

Please refer to the XMLReference type for a complete list of fields.

Signatures Property (XMLVerifier Component)

All signatures found in the XML document.

Syntax

C#
VB.NET

public XMLSignatureList Signatures { get; }

Public ReadOnly Property Signatures As XMLSignatureList

Remarks

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

This property is read-only and not available at design time.

Please refer to the XMLSignature type for a complete list of fields.

AddKnownNamespace Method (XMLVerifier Component)

Adds known prefix and correspondent namespace URI.

Syntax

C#
VB.NET

public void AddKnownNamespace(string prefix, string URI);

Public Sub AddKnownNamespace(ByVal Prefix As String, ByVal URI As String)

Remarks

Use this method to add a known prefix and namespace URI that are used in XPath expression within XMLElement/XMLNode property, and within TargetXMLElement and XPathPrefixList properties of the references.

Close Method (XMLVerifier Component)

Closes an opened document.

Syntax

C#
VB.NET

public void Close(bool saveChanges);

Public Sub Close(ByVal SaveChanges As Boolean)

Remarks

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

Config Method (XMLVerifier Component)

Sets or retrieves a configuration setting.

Syntax

C#
VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As String

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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 Component)

Performs an additional action.

Syntax

C#
VB.NET

public string DoAction(string actionID, string actionParams);

Public Function DoAction(ByVal ActionID As String, ByVal ActionParams As String) As String

Remarks

DoAction is a generic method available in every component. 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;....

Common ActionIDs:


Action	Parameters	Returned value	Description
ResetTrustedListCache	none	none	Clears the cached list of trusted lists.
ResetCertificateCache	none	none	Clears the cached certificates.
ResetCRLCache	none	none	Clears the cached CRLs.
ResetOCSPResponseCache	none	none	Clears the cached OCSP responses.

GetInnerXML Method (XMLVerifier Component)

Get the inner XML content of the selected XML element.

Syntax

C#
VB.NET

public string GetInnerXML(string XPath);

Public Function GetInnerXML(ByVal XPath As String) As String

Remarks

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

GetOuterXML Method (XMLVerifier Component)

Get the outer XML content of the selected XML element.

Syntax

C#
VB.NET

public string GetOuterXML(string XPath);

Public Function GetOuterXML(ByVal XPath As String) As String

Remarks

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

GetSignedData Method (XMLVerifier Component)

Returns the part of the XML document that is covered by the signature.

Syntax

C#
VB.NET

public void GetSignedData(string sigLabel, int refIndex);

Public Sub GetSignedData(ByVal SigLabel As String, ByVal RefIndex As Integer)

Remarks

Use this method to retrieve the part of the XML document or data that is covered by the SigLabel signature and referenced by RefIndex reference.

The output can be collected in one of the following ways: either by passing the destination path or stream via OutputFile and OutputStream respectively, or by reading the resulting data bytes from the OutputBytes property after the operation completes.

GetTextContent Method (XMLVerifier Component)

Get the text content of the selected XML element.

Syntax

C#
VB.NET

public string GetTextContent(string XPath);

Public Function GetTextContent(ByVal XPath As String) As String

Remarks

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

Open Method (XMLVerifier Component)

Opens a document for verifying or removing signatures.

Syntax

C#
VB.NET

public void Open();

Public Sub Open()

Remarks

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

Reset Method (XMLVerifier Component)

Resets the component settings.

Syntax

C#
VB.NET

public void Reset();

Public Sub Reset()

Remarks

Reset is a generic method available in every component.

Revalidate Method (XMLVerifier Component)

Revalidates a signature in accordance with current settings.

Syntax

C#
VB.NET

public void Revalidate(string sigLabel, bool detached);

Public Sub Revalidate(ByVal SigLabel As String, ByVal Detached As Boolean)

Remarks

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

SelectInfo Method (XMLVerifier Component)

Select signature information for a specific entity.

Syntax

C#
VB.NET

public void SelectInfo(string entityLabel, int infoType, bool clearSelection);

Public Sub SelectInfo(ByVal EntityLabel As String, ByVal InfoType As Integer, ByVal ClearSelection As Boolean)

Remarks

Use this method to select (or filter) signature-related information for a specific signature element.

Provide the unique label of the entity that you are interested in via the EntityLabel parameter. Use one of the following filters, or their combination, to specify what information you are interested in:


sitEntity	`1`	Select the current entity
sitParentEntity	`2`	Select the parent entity of the current entity
sitTimestamps	`4`	Select all timestamps covering the current entity
sitSignatures	`8`	Select all signatures covering the current entity
sitSigningChain	`16`	Select the signing chain of the current entity
sitEmbeddedCertificates	`256`	Select all certificates embedded in the current entity
sitEmbeddedCRLs	`512`	Select all CRLs embedded in the current entity
sitEmbeddedOCSPs	`1024`	Select all OCSP responses embedded in the current entity
sitEmbeddedRevInfo	`1792`	Select the whole pack of embedded revocation information (certificates, CRLs and OCSPs)
sitUsedCertificates	`4096`	Select all the certificates used to validate this entity's chain
sitUsedCRLs	`8192`	Select all the CRLs used to validate this entity's chain
sitUsedOCSPs	`16384`	Select all the OCSP responses used to validate this entity's chain
sitUsedRevInfo	`28672`	Select the whole pack of revocation information used to validate this entity's chain (certificates, CRLs, OCSP responses)
sitAttributes	`65536`	Select this entity's CMS attributes
sitReferences	`131072`	Select this entity's XML references
sitSignedParts	`262144`	Select this entity's signed parts

Following the call, the relevant pieces of information will be copied to the respective component properties (Certificates, CRLs, OCSPs). Note that you can accumulate information in the properties by making repeated calls to SelectInfo and keeping ClearSelection set to false.

This method is useful if you would like to read/display detailed information about a particular signature or timestamp.

SetInnerXML Method (XMLVerifier Component)

Set the inner XML content of the selected XML element.

Syntax

C#
VB.NET

public void SetInnerXML(string XPath, string value);

Public Sub SetInnerXML(ByVal XPath As String, ByVal Value As String)

Remarks

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

SetTextContent Method (XMLVerifier Component)

Set the text content of the selected XML element.

Syntax

C#
VB.NET

public void SetTextContent(string XPath, string value);

Public Sub SetTextContent(ByVal XPath As String, ByVal Value As String)

Remarks

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

Unsign Method (XMLVerifier Component)

Deletes a signature from the document.

Syntax

C#
VB.NET

public void Unsign(string sigLabel);

Public Sub Unsign(ByVal SigLabel As String)

Remarks

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

Verify Method (XMLVerifier Component)

Verifies a signed XML document.

Syntax

C#
VB.NET

public void Verify();

Public Sub 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 Component)

Verifies a detached signature over external XML data.

Syntax

C#
VB.NET

public void VerifyDetached();

Public Sub VerifyDetached()

Remarks

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

DocumentLoaded Event (XMLVerifier Component)

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

Syntax

C#
VB.NET

public event OnDocumentLoadedHandler OnDocumentLoaded;

public delegate void OnDocumentLoadedHandler(object sender, XMLVerifierDocumentLoadedEventArgs e);

public class XMLVerifierDocumentLoadedEventArgs : EventArgs {
  public bool Cancel { get; set; }
}

Public Event OnDocumentLoaded As OnDocumentLoadedHandler

Public Delegate Sub OnDocumentLoadedHandler(sender As Object, e As XMLVerifierDocumentLoadedEventArgs)

Public Class XMLVerifierDocumentLoadedEventArgs Inherits EventArgs
  Public Property Cancel As Boolean
End Class

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 Component)

Information about errors during signature verification.

Syntax

C#
VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, XMLVerifierErrorEventArgs e);

public class XMLVerifierErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As XMLVerifierErrorEventArgs)

Public Class XMLVerifierErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

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 Component)

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

Syntax

C#
VB.NET

public event OnNotificationHandler OnNotification;

public delegate void OnNotificationHandler(object sender, XMLVerifierNotificationEventArgs e);

public class XMLVerifierNotificationEventArgs : EventArgs {
  public string EventID { get; }
  public string EventParam { get; }
}

Public Event OnNotification As OnNotificationHandler

Public Delegate Sub OnNotificationHandler(sender As Object, e As XMLVerifierNotificationEventArgs)

Public Class XMLVerifierNotificationEventArgs Inherits EventArgs
  Public ReadOnly Property EventID As String
  Public ReadOnly Property EventParam As String
End Class

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. 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 component, the exact action it is performing, or the document being processed, one or both may be omitted.

This component can fire this event with the following EventID values:


DocumentLoaded	Notifies the application that the document has been loaded. This is a backward-compatibility-only notification. Use OnDocumentLoaded event instead.
SignaturesLoaded	Notifies the application that the component has finished loading signatures.
RetrieveQualifyingProperties	TBD
BeforeTimestamp	This event is fired before a timestamp is requested from the timestamping authority. Use the event handler to modify TSA and HTTP settings.
TimestampError	This event is only fired if the component failed to obtain a timestamp from the timestamping authority. The EventParam parameter contains extended error info.
TimestampRequest	A timestamp is requested from the custom timestamping authority. This event is only fired if TimestampServer was set to a virtual:// URI. The EventParam parameter contains the TSP request (or the plain hash, depending on the value provided to TimestampServer), in base16, that needs to be sent to the TSA. Use the event handler to send the request to the TSA. Upon receiving the response, assign it, in base16, to the TimestampResponse configuration property.

ReferenceValidated Event (XMLVerifier Component)

Marks the end of a reference validation.

Syntax

C#
VB.NET

public event OnReferenceValidatedHandler OnReferenceValidated;

public delegate void OnReferenceValidatedHandler(object sender, XMLVerifierReferenceValidatedEventArgs e);

public class XMLVerifierReferenceValidatedEventArgs : EventArgs {
  public int ReferenceIndex { get; }
  public string ID { get; }
  public string URI { get; }
  public string RefType { get; }
  public bool DigestValid { get; }
}

Public Event OnReferenceValidated As OnReferenceValidatedHandler

Public Delegate Sub OnReferenceValidatedHandler(sender As Object, e As XMLVerifierReferenceValidatedEventArgs)

Public Class XMLVerifierReferenceValidatedEventArgs Inherits EventArgs
  Public ReadOnly Property ReferenceIndex As Integer
  Public ReadOnly Property ID As String
  Public ReadOnly Property URI As String
  Public ReadOnly Property RefType As String
  Public ReadOnly Property DigestValid As Boolean
End Class

Remarks

The component 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 Component)

Asks the application to resolve a reference.

Syntax

C#
VB.NET

public event OnResolveReferenceHandler OnResolveReference;

public delegate void OnResolveReferenceHandler(object sender, XMLVerifierResolveReferenceEventArgs e);

public class XMLVerifierResolveReferenceEventArgs : EventArgs {
  public int ReferenceIndex { get; }
  public string URI { get; }
}

Public Event OnResolveReference As OnResolveReferenceHandler

Public Delegate Sub OnResolveReferenceHandler(sender As Object, e As XMLVerifierResolveReferenceEventArgs)

Public Class XMLVerifierResolveReferenceEventArgs Inherits EventArgs
  Public ReadOnly Property ReferenceIndex As Integer
  Public ReadOnly Property URI As String
End Class

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 Component)

Signifies the start of signature validation.

Syntax

C#
VB.NET

public event OnSignatureFoundHandler OnSignatureFound;

public delegate void OnSignatureFoundHandler(object sender, XMLVerifierSignatureFoundEventArgs e);

public class XMLVerifierSignatureFoundEventArgs : EventArgs {
  public int Index { get; }
  public string EntityLabel { get; }
  public string IssuerRDN { get; }
  public byte[] SerialNumber { get; }
  public byte[] SubjectKeyID { get; }
  public bool CertFound { get; }
  public bool ValidateSignature { get; set; }
  public bool ValidateChain { get; set; }
}

Public Event OnSignatureFound As OnSignatureFoundHandler

Public Delegate Sub OnSignatureFoundHandler(sender As Object, e As XMLVerifierSignatureFoundEventArgs)

Public Class XMLVerifierSignatureFoundEventArgs Inherits EventArgs
  Public ReadOnly Property Index As Integer
  Public ReadOnly Property EntityLabel As String
  Public ReadOnly Property IssuerRDN As String
  Public ReadOnly Property SerialNumber As Byte()
  Public ReadOnly Property SubjectKeyID As Byte()
  Public ReadOnly Property CertFound As Boolean
  Public Property ValidateSignature As Boolean
  Public Property ValidateChain As Boolean
End Class

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 component 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 SignatureValidationResult and ChainValidationResult properties respectively.

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

SignatureValidated Event (XMLVerifier Component)

Marks the completion of the signature validation routine.

Syntax

C#
VB.NET

public event OnSignatureValidatedHandler OnSignatureValidated;

public delegate void OnSignatureValidatedHandler(object sender, XMLVerifierSignatureValidatedEventArgs e);

public class XMLVerifierSignatureValidatedEventArgs : EventArgs {
  public int Index { get; }
  public string EntityLabel { get; }
  public string IssuerRDN { get; }
  public byte[] SerialNumber { get; }
  public byte[] SubjectKeyID { get; }
  public int ValidationResult { get; }
  public bool Cancel { get; set; }
}

Public Event OnSignatureValidated As OnSignatureValidatedHandler

Public Delegate Sub OnSignatureValidatedHandler(sender As Object, e As XMLVerifierSignatureValidatedEventArgs)

Public Class XMLVerifierSignatureValidatedEventArgs Inherits EventArgs
  Public ReadOnly Property Index As Integer
  Public ReadOnly Property EntityLabel As String
  Public ReadOnly Property IssuerRDN As String
  Public ReadOnly Property SerialNumber As Byte()
  Public ReadOnly Property SubjectKeyID As Byte()
  Public ReadOnly Property ValidationResult As Integer
  Public Property Cancel As Boolean
End Class

Remarks

This event is fired upon the completion of the signature validation routine, and reports the respective validation result.

Use the IssuerRDN, SerialNumber, and/or SubjectKeyID parameters to identify the signing certificate.

ValidationResult is set to 0 if the validation has been successful, or to a non-zero value in case of a validation failure.


svtValid	`0`	The signature is valid
svtUnknown	`1`	Signature validity is unknown
svtCorrupted	`2`	The signature is corrupted
svtSignerNotFound	`3`	Failed to acquire the signing certificate. The signature cannot be validated.
svtFailure	`4`	General failure
svtReferenceCorrupted	`5`	Reference corrupted (XML-based signatures only)

Certificate Type

Encapsulates an individual X.509 certificate.

Remarks

This type keeps and provides access to X.509 certificate details.

The following fields are available:

Fields

Bytes
byte[] (read-only)
Default: ""

Returns the raw certificate data in DER format.

CA
bool
Default: False

Indicates whether the certificate has a CA capability. For the certificate to be considered a CA, it must have its Basic Constraints extension set with the CA indicator enabled.

Set this field when generating a new certificate to have its Basic Constraints extension generated automatically.

CAKeyID
byte[] (read-only)
Default: ""

A unique identifier (fingerprint) of the CA certificate's cryptographic key.

Authority Key Identifier is a certificate extension which allows identification of certificates belonging to the same issuer, but with different public keys. It is a de-facto standard to include this extension in all certificates to facilitate chain building.

This setting cannot be set when generating a certificate as it always derives from another certificate property. CertificateManager generates this setting automatically if enough information is available to it: for self-signed certificates, this value is copied from the SubjectKeyID setting, and for lower-level certificates, from the parent certificate's subject key ID extension.

CertType
CertTypes (read-only)
Default: 0

Returns the type of the entity contained in the Certificate object.

A Certificate object can contain two types of cryptographic objects: a ready-to-use X.509 certificate, or a certificate request ("an unsigned certificate"). Certificate requests can be upgraded to full certificates by signing them with a CA certificate.

Use the CertificateManager component to load or create new certificate and certificate requests objects.

CRLDistributionPoints
string
Default: ""

Contains a list of locations of CRL distribution points used to check this certificate's validity. The list is taken from the respective certificate extension.

Use this field when generating a certificate to provide a list of CRL endpoints that should be made part of the new certificate.

The endpoints are provided as a list of CRLF-separated URLs. Note that this differs from the behaviour used in earlier product versions, where the "|" character was used as the location separator.

Curve
string
Default: ""

Specifies the elliptic curve associated with the certificate's public key. This setting only applies to certificates containing EC keys.


SB_EC_SECP112R1	`SECP112R1`
SB_EC_SECP112R2	`SECP112R2`
SB_EC_SECP128R1	`SECP128R1`
SB_EC_SECP128R2	`SECP128R2`
SB_EC_SECP160K1	`SECP160K1`
SB_EC_SECP160R1	`SECP160R1`
SB_EC_SECP160R2	`SECP160R2`
SB_EC_SECP192K1	`SECP192K1`
SB_EC_SECP192R1	`SECP192R1`
SB_EC_SECP224K1	`SECP224K1`
SB_EC_SECP224R1	`SECP224R1`
SB_EC_SECP256K1	`SECP256K1`
SB_EC_SECP256R1	`SECP256R1`
SB_EC_SECP384R1	`SECP384R1`
SB_EC_SECP521R1	`SECP521R1`
SB_EC_SECT113R1	`SECT113R1`
SB_EC_SECT113R2	`SECT113R2`
SB_EC_SECT131R1	`SECT131R1`
SB_EC_SECT131R2	`SECT131R2`
SB_EC_SECT163K1	`SECT163K1`
SB_EC_SECT163R1	`SECT163R1`
SB_EC_SECT163R2	`SECT163R2`
SB_EC_SECT193R1	`SECT193R1`
SB_EC_SECT193R2	`SECT193R2`
SB_EC_SECT233K1	`SECT233K1`
SB_EC_SECT233R1	`SECT233R1`
SB_EC_SECT239K1	`SECT239K1`
SB_EC_SECT283K1	`SECT283K1`
SB_EC_SECT283R1	`SECT283R1`
SB_EC_SECT409K1	`SECT409K1`
SB_EC_SECT409R1	`SECT409R1`
SB_EC_SECT571K1	`SECT571K1`
SB_EC_SECT571R1	`SECT571R1`
SB_EC_PRIME192V1	`PRIME192V1`
SB_EC_PRIME192V2	`PRIME192V2`
SB_EC_PRIME192V3	`PRIME192V3`
SB_EC_PRIME239V1	`PRIME239V1`
SB_EC_PRIME239V2	`PRIME239V2`
SB_EC_PRIME239V3	`PRIME239V3`
SB_EC_PRIME256V1	`PRIME256V1`
SB_EC_C2PNB163V1	`C2PNB163V1`
SB_EC_C2PNB163V2	`C2PNB163V2`
SB_EC_C2PNB163V3	`C2PNB163V3`
SB_EC_C2PNB176W1	`C2PNB176W1`
SB_EC_C2TNB191V1	`C2TNB191V1`
SB_EC_C2TNB191V2	`C2TNB191V2`
SB_EC_C2TNB191V3	`C2TNB191V3`
SB_EC_C2ONB191V4	`C2ONB191V4`
SB_EC_C2ONB191V5	`C2ONB191V5`
SB_EC_C2PNB208W1	`C2PNB208W1`
SB_EC_C2TNB239V1	`C2TNB239V1`
SB_EC_C2TNB239V2	`C2TNB239V2`
SB_EC_C2TNB239V3	`C2TNB239V3`
SB_EC_C2ONB239V4	`C2ONB239V4`
SB_EC_C2ONB239V5	`C2ONB239V5`
SB_EC_C2PNB272W1	`C2PNB272W1`
SB_EC_C2PNB304W1	`C2PNB304W1`
SB_EC_C2TNB359V1	`C2TNB359V1`
SB_EC_C2PNB368W1	`C2PNB368W1`
SB_EC_C2TNB431R1	`C2TNB431R1`
SB_EC_NISTP192	`NISTP192`
SB_EC_NISTP224	`NISTP224`
SB_EC_NISTP256	`NISTP256`
SB_EC_NISTP384	`NISTP384`
SB_EC_NISTP521	`NISTP521`
SB_EC_NISTB163	`NISTB163`
SB_EC_NISTB233	`NISTB233`
SB_EC_NISTB283	`NISTB283`
SB_EC_NISTB409	`NISTB409`
SB_EC_NISTB571	`NISTB571`
SB_EC_NISTK163	`NISTK163`
SB_EC_NISTK233	`NISTK233`
SB_EC_NISTK283	`NISTK283`
SB_EC_NISTK409	`NISTK409`
SB_EC_NISTK571	`NISTK571`
SB_EC_GOSTCPTEST	`GOSTCPTEST`
SB_EC_GOSTCPA	`GOSTCPA`
SB_EC_GOSTCPB	`GOSTCPB`
SB_EC_GOSTCPC	`GOSTCPC`
SB_EC_GOSTCPXCHA	`GOSTCPXCHA`
SB_EC_GOSTCPXCHB	`GOSTCPXCHB`
SB_EC_BRAINPOOLP160R1	`BRAINPOOLP160R1`
SB_EC_BRAINPOOLP160T1	`BRAINPOOLP160T1`
SB_EC_BRAINPOOLP192R1	`BRAINPOOLP192R1`
SB_EC_BRAINPOOLP192T1	`BRAINPOOLP192T1`
SB_EC_BRAINPOOLP224R1	`BRAINPOOLP224R1`
SB_EC_BRAINPOOLP224T1	`BRAINPOOLP224T1`
SB_EC_BRAINPOOLP256R1	`BRAINPOOLP256R1`
SB_EC_BRAINPOOLP256T1	`BRAINPOOLP256T1`
SB_EC_BRAINPOOLP320R1	`BRAINPOOLP320R1`
SB_EC_BRAINPOOLP320T1	`BRAINPOOLP320T1`
SB_EC_BRAINPOOLP384R1	`BRAINPOOLP384R1`
SB_EC_BRAINPOOLP384T1	`BRAINPOOLP384T1`
SB_EC_BRAINPOOLP512R1	`BRAINPOOLP512R1`
SB_EC_BRAINPOOLP512T1	`BRAINPOOLP512T1`
SB_EC_CURVE25519	`CURVE25519`
SB_EC_CURVE448	`CURVE448`

Fingerprint
string (read-only)
Default: ""

Contains the fingerprint (a hash imprint) of this certificate.

While there is no formal standard defining what a fingerprint is, a SHA1 hash of the certificate's DER-encoded body is typically used.

FriendlyName
string (read-only)
Default: ""

Contains an associated alias (friendly name) of the certificate. The friendly name is not a property of a certificate: it is maintained by the certificate media rather than being included in its DER representation. Windows certificate stores are one example of media that does support friendly names.

HashAlgorithm
string
Default: ""

Provides means to set the hash algorithm to be used in the subsequent operation on the certificate (such as generation or key signing). It is not a property of a certificate; use SigAlgorithm to find out the hash algorithm that is part of the certificate signature.


SB_HASH_ALGORITHM_SHA1	`SHA1`
SB_HASH_ALGORITHM_SHA224	`SHA224`
SB_HASH_ALGORITHM_SHA256	`SHA256`
SB_HASH_ALGORITHM_SHA384	`SHA384`
SB_HASH_ALGORITHM_SHA512	`SHA512`
SB_HASH_ALGORITHM_MD2	`MD2`
SB_HASH_ALGORITHM_MD4	`MD4`
SB_HASH_ALGORITHM_MD5	`MD5`
SB_HASH_ALGORITHM_RIPEMD160	`RIPEMD160`
SB_HASH_ALGORITHM_CRC32	`CRC32`
SB_HASH_ALGORITHM_SSL3	`SSL3`
SB_HASH_ALGORITHM_GOST_R3411_1994	`GOST1994`
SB_HASH_ALGORITHM_WHIRLPOOL	`WHIRLPOOL`
SB_HASH_ALGORITHM_POLY1305	`POLY1305`
SB_HASH_ALGORITHM_SHA3_224	`SHA3_224`
SB_HASH_ALGORITHM_SHA3_256	`SHA3_256`
SB_HASH_ALGORITHM_SHA3_384	`SHA3_384`
SB_HASH_ALGORITHM_SHA3_512	`SHA3_512`
SB_HASH_ALGORITHM_BLAKE2S_128	`BLAKE2S_128`
SB_HASH_ALGORITHM_BLAKE2S_160	`BLAKE2S_160`
SB_HASH_ALGORITHM_BLAKE2S_224	`BLAKE2S_224`
SB_HASH_ALGORITHM_BLAKE2S_256	`BLAKE2S_256`
SB_HASH_ALGORITHM_BLAKE2B_160	`BLAKE2B_160`
SB_HASH_ALGORITHM_BLAKE2B_256	`BLAKE2B_256`
SB_HASH_ALGORITHM_BLAKE2B_384	`BLAKE2B_384`
SB_HASH_ALGORITHM_BLAKE2B_512	`BLAKE2B_512`
SB_HASH_ALGORITHM_SHAKE_128	`SHAKE_128`
SB_HASH_ALGORITHM_SHAKE_256	`SHAKE_256`
SB_HASH_ALGORITHM_SHAKE_128_LEN	`SHAKE_128_LEN`
SB_HASH_ALGORITHM_SHAKE_256_LEN	`SHAKE_256_LEN`

Issuer
string (read-only)
Default: ""

The common name of the certificate issuer (CA), typically a company name. This is part of a larger set of credentials available via IssuerRDN.

IssuerRDN
string
Default: ""

A list of Property=Value pairs that uniquely identify the certificate issuer.

Example: /C=US/O=Nationwide CA/CN=Web Certification Authority

KeyAlgorithm
string
Default: "0"

Specifies the public key algorithm of this certificate.


SB_CERT_ALGORITHM_ID_RSA_ENCRYPTION	`rsaEncryption`
SB_CERT_ALGORITHM_MD2_RSA_ENCRYPTION	`md2withRSAEncryption`
SB_CERT_ALGORITHM_MD5_RSA_ENCRYPTION	`md5withRSAEncryption`
SB_CERT_ALGORITHM_SHA1_RSA_ENCRYPTION	`sha1withRSAEncryption`
SB_CERT_ALGORITHM_ID_DSA	`id-dsa`
SB_CERT_ALGORITHM_ID_DSA_SHA1	`id-dsa-with-sha1`
SB_CERT_ALGORITHM_DH_PUBLIC	`dhpublicnumber`
SB_CERT_ALGORITHM_SHA224_RSA_ENCRYPTION	`sha224WithRSAEncryption`
SB_CERT_ALGORITHM_SHA256_RSA_ENCRYPTION	`sha256WithRSAEncryption`
SB_CERT_ALGORITHM_SHA384_RSA_ENCRYPTION	`sha384WithRSAEncryption`
SB_CERT_ALGORITHM_SHA512_RSA_ENCRYPTION	`sha512WithRSAEncryption`
SB_CERT_ALGORITHM_ID_RSAPSS	`id-RSASSA-PSS`
SB_CERT_ALGORITHM_ID_RSAOAEP	`id-RSAES-OAEP`
SB_CERT_ALGORITHM_RSASIGNATURE_RIPEMD160	`ripemd160withRSA`
SB_CERT_ALGORITHM_ID_ELGAMAL	`elGamal`
SB_CERT_ALGORITHM_SHA1_ECDSA	`ecdsa-with-SHA1`
SB_CERT_ALGORITHM_RECOMMENDED_ECDSA	`ecdsa-recommended`
SB_CERT_ALGORITHM_SHA224_ECDSA	`ecdsa-with-SHA224`
SB_CERT_ALGORITHM_SHA256_ECDSA	`ecdsa-with-SHA256`
SB_CERT_ALGORITHM_SHA384_ECDSA	`ecdsa-with-SHA384`
SB_CERT_ALGORITHM_SHA512_ECDSA	`ecdsa-with-SHA512`
SB_CERT_ALGORITHM_EC	`id-ecPublicKey`
SB_CERT_ALGORITHM_SPECIFIED_ECDSA	`ecdsa-specified`
SB_CERT_ALGORITHM_GOST_R3410_1994	`id-GostR3410-94`
SB_CERT_ALGORITHM_GOST_R3410_2001	`id-GostR3410-2001`
SB_CERT_ALGORITHM_GOST_R3411_WITH_R3410_1994	`id-GostR3411-94-with-GostR3410-94`
SB_CERT_ALGORITHM_GOST_R3411_WITH_R3410_2001	`id-GostR3411-94-with-GostR3410-2001`
SB_CERT_ALGORITHM_SHA1_ECDSA_PLAIN	`ecdsa-plain-SHA1`
SB_CERT_ALGORITHM_SHA224_ECDSA_PLAIN	`ecdsa-plain-SHA224`
SB_CERT_ALGORITHM_SHA256_ECDSA_PLAIN	`ecdsa-plain-SHA256`
SB_CERT_ALGORITHM_SHA384_ECDSA_PLAIN	`ecdsa-plain-SHA384`
SB_CERT_ALGORITHM_SHA512_ECDSA_PLAIN	`ecdsa-plain-SHA512`
SB_CERT_ALGORITHM_RIPEMD160_ECDSA_PLAIN	`ecdsa-plain-RIPEMD160`
SB_CERT_ALGORITHM_WHIRLPOOL_RSA_ENCRYPTION	`whirlpoolWithRSAEncryption`
SB_CERT_ALGORITHM_ID_DSA_SHA224	`id-dsa-with-sha224`
SB_CERT_ALGORITHM_ID_DSA_SHA256	`id-dsa-with-sha256`
SB_CERT_ALGORITHM_SHA3_224_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-sha3-224`
SB_CERT_ALGORITHM_SHA3_256_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-sha3-256`
SB_CERT_ALGORITHM_SHA3_384_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-sha3-384`
SB_CERT_ALGORITHM_SHA3_512_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-sha3-512`
SB_CERT_ALGORITHM_SHA3_224_ECDSA	`id-ecdsa-with-sha3-224`
SB_CERT_ALGORITHM_SHA3_256_ECDSA	`id-ecdsa-with-sha3-256`
SB_CERT_ALGORITHM_SHA3_384_ECDSA	`id-ecdsa-with-sha3-384`
SB_CERT_ALGORITHM_SHA3_512_ECDSA	`id-ecdsa-with-sha3-512`
SB_CERT_ALGORITHM_SHA3_224_ECDSA_PLAIN	`id-ecdsa-plain-with-sha3-224`
SB_CERT_ALGORITHM_SHA3_256_ECDSA_PLAIN	`id-ecdsa-plain-with-sha3-256`
SB_CERT_ALGORITHM_SHA3_384_ECDSA_PLAIN	`id-ecdsa-plain-with-sha3-384`
SB_CERT_ALGORITHM_SHA3_512_ECDSA_PLAIN	`id-ecdsa-plain-with-sha3-512`
SB_CERT_ALGORITHM_ID_DSA_SHA3_224	`id-dsa-with-sha3-224`
SB_CERT_ALGORITHM_ID_DSA_SHA3_256	`id-dsa-with-sha3-256`
SB_CERT_ALGORITHM_BLAKE2S_128_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-blake2s128`
SB_CERT_ALGORITHM_BLAKE2S_160_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-blake2s160`
SB_CERT_ALGORITHM_BLAKE2S_224_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-blake2s224`
SB_CERT_ALGORITHM_BLAKE2S_256_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-blake2s256`
SB_CERT_ALGORITHM_BLAKE2B_160_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-blake2b160`
SB_CERT_ALGORITHM_BLAKE2B_256_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-blake2b256`
SB_CERT_ALGORITHM_BLAKE2B_384_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-blake2b384`
SB_CERT_ALGORITHM_BLAKE2B_512_RSA_ENCRYPTION	`id-rsassa-pkcs1-v1_5-with-blake2b512`
SB_CERT_ALGORITHM_BLAKE2S_128_ECDSA	`id-ecdsa-with-blake2s128`
SB_CERT_ALGORITHM_BLAKE2S_160_ECDSA	`id-ecdsa-with-blake2s160`
SB_CERT_ALGORITHM_BLAKE2S_224_ECDSA	`id-ecdsa-with-blake2s224`
SB_CERT_ALGORITHM_BLAKE2S_256_ECDSA	`id-ecdsa-with-blake2s256`
SB_CERT_ALGORITHM_BLAKE2B_160_ECDSA	`id-ecdsa-with-blake2b160`
SB_CERT_ALGORITHM_BLAKE2B_256_ECDSA	`id-ecdsa-with-blake2b256`
SB_CERT_ALGORITHM_BLAKE2B_384_ECDSA	`id-ecdsa-with-blake2b384`
SB_CERT_ALGORITHM_BLAKE2B_512_ECDSA	`id-ecdsa-with-blake2b512`
SB_CERT_ALGORITHM_BLAKE2S_128_ECDSA_PLAIN	`id-ecdsa-plain-with-blake2s128`
SB_CERT_ALGORITHM_BLAKE2S_160_ECDSA_PLAIN	`id-ecdsa-plain-with-blake2s160`
SB_CERT_ALGORITHM_BLAKE2S_224_ECDSA_PLAIN	`id-ecdsa-plain-with-blake2s224`
SB_CERT_ALGORITHM_BLAKE2S_256_ECDSA_PLAIN	`id-ecdsa-plain-with-blake2s256`
SB_CERT_ALGORITHM_BLAKE2B_160_ECDSA_PLAIN	`id-ecdsa-plain-with-blake2b160`
SB_CERT_ALGORITHM_BLAKE2B_256_ECDSA_PLAIN	`id-ecdsa-plain-with-blake2b256`
SB_CERT_ALGORITHM_BLAKE2B_384_ECDSA_PLAIN	`id-ecdsa-plain-with-blake2b384`
SB_CERT_ALGORITHM_BLAKE2B_512_ECDSA_PLAIN	`id-ecdsa-plain-with-blake2b512`
SB_CERT_ALGORITHM_ID_DSA_BLAKE2S_224	`id-dsa-with-blake2s224`
SB_CERT_ALGORITHM_ID_DSA_BLAKE2S_256	`id-dsa-with-blake2s256`
SB_CERT_ALGORITHM_EDDSA_ED25519	`id-Ed25519`
SB_CERT_ALGORITHM_EDDSA_ED448	`id-Ed448`
SB_CERT_ALGORITHM_EDDSA_ED25519_PH	`id-Ed25519ph`
SB_CERT_ALGORITHM_EDDSA_ED448_PH	`id-Ed448ph`
SB_CERT_ALGORITHM_EDDSA	`id-EdDSA`
SB_CERT_ALGORITHM_EDDSA_SIGNATURE	`id-EdDSA-sig`

Use the KeyBits, Curve, and PublicKeyBytes fields to get more details about the key the certificate contains.

KeyBits
int (read-only)
Default: 0

Returns the length of the public key in bits.

This value indicates the length of the principal cryptographic parameter of the key, such as the length of the RSA modulus or ECDSA field. The key data returned by the PublicKeyBytes or PrivateKeyBytes field would typically contain auxiliary values, and therefore be longer.

KeyFingerprint
string (read-only)
Default: ""

Returns a SHA1 fingerprint of the public key contained in the certificate.

Note that the key fingerprint is different from the certificate fingerprint accessible via the Fingerprint field. The key fingeprint uniquely identifies the public key, and so can be the same for multiple certificates containing the same key.

KeyUsage
int
Default: 0

Indicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set.

This value is a bit mask of the following values:


ckuUnknown	`0x00000`	Unknown key usage
ckuDigitalSignature	`0x00001`	Digital signature
ckuNonRepudiation	`0x00002`	Non-repudiation
ckuKeyEncipherment	`0x00004`	Key encipherment
ckuDataEncipherment	`0x00008`	Data encipherment
ckuKeyAgreement	`0x00010`	Key agreement
ckuKeyCertSign	`0x00020`	Certificate signing
ckuCRLSign	`0x00040`	Revocation signing
ckuEncipherOnly	`0x00080`	Encipher only
ckuDecipherOnly	`0x00100`	Decipher only
ckuServerAuthentication	`0x00200`	Server authentication
ckuClientAuthentication	`0x00400`	Client authentication
ckuCodeSigning	`0x00800`	Code signing
ckuEmailProtection	`0x01000`	Email protection
ckuTimeStamping	`0x02000`	Timestamping
ckuOCSPSigning	`0x04000`	OCSP signing
ckuSmartCardLogon	`0x08000`	Smartcard logon
ckuKeyPurposeClientAuth	`0x10000`	Kerberos - client authentication
ckuKeyPurposeKDC	`0x20000`	Kerberos - KDC

Set this field before generating the certificate to propagate the key usage flags to the new certificate.

KeyValid
bool (read-only)
Default: False

Returns True if the certificate's key is cryptographically valid, and False otherwise.

OCSPLocations
string
Default: ""

Locations of OCSP services that can be used to check this certificate's validity in real time, as recorded by the CA.

Set this field before calling the certificate manager's Generate method to propagate it to the new certificate.

The OCSP locations are provided as a list of CRLF-separated URLs. Note that this differs from the behaviour used in earlier product versions, where the "|" character was used as the location separator.

OCSPNoCheck
bool
Default: False

Accessor to the value of the certificate's ocsp-no-check extension.

Origin
int (read-only)
Default: 0

Returns the location that the certificate was taken or loaded from.

PolicyIDs
string
Default: ""

Contains identifiers (OIDs) of the applicable certificate policies.

The Certificate Policies extension identifies a sequence of policies under which the certificate has been issued, and which regulate its usage.

Set this field when generating a certificate to propagate the policies information to the new certificate.

The policies are provided as a list of CRLF-separated entries. Note that this differs from the behaviour used in earlier product versions, where the "|" character was used as the policy element separator.

PrivateKeyBytes
byte[] (read-only)
Default: ""

Returns the certificate's private key in DER-encoded format. It is normal for this field to be empty if the private key is non-exportable, which, for example, is typical for certificates originating from hardware security devices.

PrivateKeyExists
bool (read-only)
Default: False

Indicates whether the certificate has a usable private key associated with it. If it is set to True, the certificate can be used for private key operations, such as signing or decryption.

This field is independent from PrivateKeyBytes, and can be set to True even if the former is empty. This would imply that the private key is non-exportable, but still can be used for cryptographic operations.

PrivateKeyExtractable
bool (read-only)
Default: False

Indicates whether the private key is extractable (exportable).

PublicKeyBytes
byte[] (read-only)
Default: ""

Contains the certificate's public key in DER format.

This typically would contain an ASN.1-encoded public key value. The exact format depends on the type of the public key contained in the certificate.

Qualified
bool (read-only)
Default: False

Indicates whether the certificate is qualified.

This property is set to True if the certificate is confirmed by a Trusted List to be qualified.

QualifiedStatements
QualifiedStatementsTypes
Default: 0

Returns a simplified qualified status of the certificate.

Qualifiers
string (read-only)
Default: ""

A list of qualifiers.

Contains a comma-separated list of qualifier aliases for the certificate, for example QCP-n-qscd,QCWithSSCD.

SelfSigned
bool (read-only)
Default: False

Indicates whether the certificate is self-signed (root) or signed by an external CA.

SerialNumber
byte[]
Default: ""

Returns the certificate's serial number.

The serial number is a binary string that uniquely identifies a certificate among others issued by the same CA. According to the X.509 standard, the (issuer, serial number) pair should be globally unique to facilitate chain building.

SigAlgorithm
string (read-only)
Default: ""

Indicates the algorithm that was used by the CA to sign this certificate.

A signature algorithm typically combines hash and public key algorithms together, such as sha256WithRSAEncryption or ecdsa-with-SHA256.

Source
PKISources (read-only)
Default: 0

Returns the source (location or disposition) of a cryptographic primitive entity, such as a certificate, CRL, or OCSP response.

Subject
string (read-only)
Default: ""

The common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name. This is part of a larger set of credentials available via SubjectRDN.

SubjectAlternativeName
string
Default: ""

Returns or sets the value of the Subject Alternative Name extension of the certificate.

Subject alternative names are used to provide additional names that are impractical to store in the main SubjectRDN field. For example, it is often used to store all the domain names that a TLS certificate is authorized to protect.

The alternative names are provided as a list of CRLF-separated entries. Note that this differs from the behaviour used in earlier product versions, where the "|" character was used as the element separator.

SubjectKeyID
byte[]
Default: ""

Contains a unique identifier of the certificate's cryptographic key.

Subject Key Identifier is a certificate extension which allows a specific public key to be associated with a certificate holder. Typically, subject key identifiers of CA certificates are recorded as respective CA key identifiers in the subordinate certificates that they issue, which facilitates chain building.

The SubjectKeyID and CAKeyID fields of self-signed certificates typically contain identical values, as in that specific case, the issuer and the subject are the same entity.

SubjectRDN
string
Default: ""

A list of Property=Value pairs that uniquely identify the certificate holder (subject).

Depending on the purpose of the certificate and the policies of the CA that issued it, the values included in the subject record may differ drastically and contain business or personal names, web URLs, email addresses, and other data.

Example: /C=US/O=Oranges and Apples, Inc./OU=Accounts Receivable/1.2.3.4.5=Value with unknown OID/CN=Margaret Watkins.

Valid
bool (read-only)
Default: False

Indicates whether or not the signature over the certificate or the request is valid and matches the public key contained in the CA certificate/request.

ValidFrom
string
Default: ""

The time point at which the certificate becomes valid, in UTC.

ValidTo
string
Default: ""

The time point at which the certificate expires, in UTC.

Constructors

C#
VB.NET

public Certificate(byte[] bytes, int startIndex, int count, string password);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

C#
VB.NET

public Certificate(byte[] certBytes, int certStartIndex, int certCount, byte[] keyBytes, int keyStartIndex, int keyCount, string password);

Public Certificate(ByVal CertBytes As Byte(), ByVal CertStartIndex As Integer, ByVal CertCount As Integer, ByVal KeyBytes As Byte(), ByVal KeyStartIndex As Integer, ByVal KeyCount As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer.

CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the starting position and number of bytes to be read from the buffer, respectively.

KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively.

Password is a password encrypting the certificate.

C#
VB.NET

public Certificate(byte[] bytes, int startIndex, int count);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

C#
VB.NET

public Certificate(string path, string password);

Public Certificate(ByVal Path As String, ByVal Password As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

C#
VB.NET

public Certificate(string certPath, string keyPath, string password);

Public Certificate(ByVal CertPath As String, ByVal KeyPath As String, ByVal Password As String)

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

C#
VB.NET

public Certificate(string path);

Public Certificate(ByVal Path As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

C#
VB.NET

public Certificate(System.IO.Stream stream);

Public Certificate(ByVal Stream As System.IO.Stream)

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

C#
VB.NET

public Certificate(System.IO.Stream stream, string password);

Public Certificate(ByVal Stream As System.IO.Stream, ByVal Password As String)

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

C#
VB.NET

public Certificate(System.IO.Stream certStream, System.IO.Stream keyStream, string password);

Public Certificate(ByVal CertStream As System.IO.Stream, ByVal KeyStream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

C#
VB.NET

public Certificate();

Public Certificate()

Creates a new object with default field values.

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.

The following fields are available:

Fields

AutoGenerateElementId
bool
Default: False

Specifies whether the identifier (ID) attribute for a referenced (target) element should be auto-generated during signing. Used when the referenced element doesn't have an ID and CustomElementId and URI properties are empty.

CanonicalizationMethod
XMLCanonicalizationMethods
Default: 0

Use this property to specify the canonicalization method for the transform of the reference. Use cxcmNone value to not to include canonicalization transform in transform chain. See XML-Signature Syntax and Processing specification for details.


cxcmNone	`0`
cxcmCanon	`1`
cxcmCanonComment	`2`
cxcmExclCanon	`3`
cxcmExclCanonComment	`4`
cxcmMinCanon	`5`
cxcmCanon_v1_1	`6`
cxcmCanonComment_v1_1	`7`

CustomElementId
string
Default: ""

Specifies a custom identifier (ID) attribute for a referenced (target) element that will be set on signing. Used when the referenced element doesn't have an ID and URI property is empty.

DataObjectDescription
string
Default: ""

This property contains textual information related to the referenced data object, which is found in the corresponding DataObjectFormat's Description element.

DataObjectEncoding
string
Default: ""

This property contains an indication of the encoding format of the referenced data object, which is found in the corresponding DataObjectFormat's Encoding element.

DataObjectIdentifier
string
Default: ""

This property contains an identifier indicating the type of the referenced data object, which is found in the corresponding DataObjectFormat's ObjectIdentifier element.

DataObjectMimeType
string
Default: ""

This property contains an indication of the MIME type of the referenced data object, which is found in the corresponding DataObjectFormat's MimeType element.

DigestValue
byte[]
Default: ""

Use this property to get or set the value of the digest calculated over the referenced data.

This field is optional and should be set only if you don't provide the actual data via TargetData or URI. If the data is set, then you don't need to set DigestValue since it will be calculated automatically.

HasDataObjectFormat
bool
Default: False

Specifies whether corresponding XAdES DataObjectFormat element is created for the current reference.

Check this property to find out if the reference has an associated DataObjectFormat element.

HashAlgorithm
string
Default: "SHA256"

Specifies the hash algorithm to be used.

Supported values:


SB_HASH_ALGORITHM_MD5	`MD5`
SB_HASH_ALGORITHM_SHA1	`SHA1`
SB_HASH_ALGORITHM_SHA224	`SHA224`
SB_HASH_ALGORITHM_SHA256	`SHA256`
SB_HASH_ALGORITHM_SHA384	`SHA384`
SB_HASH_ALGORITHM_SHA512	`SHA512`
SB_HASH_ALGORITHM_RIPEMD160	`RIPEMD160`
SB_HASH_ALGORITHM_GOST_R3411_1994	`GOST1994`
SB_HASH_ALGORITHM_WHIRLPOOL	`WHIRLPOOL`
SB_HASH_ALGORITHM_SHA3_256	`SHA3_256`
SB_HASH_ALGORITHM_SHA3_384	`SHA3_384`
SB_HASH_ALGORITHM_SHA3_512	`SHA3_512`

HasURI
bool
Default: True

Specifies whether the URI is set (even when it is empty).

ID
string
Default: ""

A user-defined identifier (ID) attribute of this Reference element.

InclusiveNamespacesPrefixList
string
Default: ""

Use this property to specify InclusiveNamespaces PrefixList for exclusive canonicalization transform of the reference. See XML-Signature Syntax and Processing specification for details.

ReferenceType
string
Default: ""

The Reference's type attribute as defined in XMLDSIG specification.

TargetData
byte[]
Default: ""

Contains the referenced external data when the digest value is not explicitly specified.

This field is optional and should only be set if you reference the external data via URI, and you don't provide the digest value explicitly via DigestValue.

TargetType
XMLReferenceTargetTypes
Default: 0

The reference's target type to use.

Use this property to specify the reference's target type to use when forming the signature.

TargetXMLElement
string
Default: ""

This property specifies the referenced XML element. Used when the URI property is not set. In this case, the URI value is generated based on the ID of the referenced (target) XML element. If the URI property is set, this property is ignored until the ResolveReference event.

Supported values are:


""	an empty string indicates the Document element.
"#id"	indicates an XML element with specified Id.
XPointer expression	indicates an XML element selected using XPointer expression. Use the AddKnownNamespace method to specify Prefixes and NamespaceURIs For example: "/root/data[1]" - indicates the second "data" element under the document element with a name "root" "//ns1:data" - indicates a data element. "ns1" prefix should be defined via AddKnownNamespace method.
Node name	indicates an XML element selected using its NodeName. For example: "data" - indicates an XML element with node name "data".

URI
string
Default: ""

Use this property to get or set the URL which references the data. If the data is external, the application must set either TargetData or DigestValue. If TargetData is set, the digest is calculated automatically unless it is explicitly set by the application via DigestValue.

UseBase64Transform
bool
Default: False

Specifies whether Base64 transform is included in transform chain.

UseEnvelopedSignatureTransform
bool
Default: False

Specifies whether enveloped signature transform is included in transform chain.

UseXPathFilter2Transform
bool
Default: False

Specifies whether XPath Filter 2.0 transform is included in transform chain.

UseXPathTransform
bool
Default: False

Specifies whether XPath transform is included in transform chain.

ValidationResult
bool (read-only)
Default: False

The outcome of the cryptographic reference validation.

XPathExpression
string
Default: ""

Use this property to specify XPath expression for XPath transform of the reference.

XPathFilter2Expressions
string
Default: ""

Use this property to specify XPointer expression(s) for XPath Filter 2.0 transform of the reference.

XPathFilter2Filters
string
Default: ""

Use this property to specify XPointer filter(s) for XPath Filter 2.0 transform of the reference. The prefix list is comma-separated.

Supported values:


"intersect"	Intersect filter computes the intersection of the selected subtrees with the filter node-set.
"subtract"	Subtract filter computes the subtraction of the selected subtrees with the filter node-set.
"union"	Union filter computes the union of the selected subtrees with the filter node-set.

XPathFilter2PrefixList
string
Default: ""

Use this property to specify a prefix list for XPath Filter 2.0 transform of the reference. The prefix list is space-separated. Namespace URIs that are used are taken from XPathNamespaces property.

XPathPrefixList
string
Default: ""

Use this property to specify a prefix list for XPath transform of the reference. The prefix list is space-separated. Namespace URIs that are used are taken from XPathNamespaces property.

Constructors

C#
VB.NET

public XMLReference();

Public XMLReference()

Creates a new XML reference element.

C#
VB.NET

public XMLReference(string ID);

Public XMLReference(ByVal ID As String)

Creates a new XML reference element from its ID .

C#
VB.NET

public XMLReference(string ID, string URI);

Public XMLReference(ByVal ID As String, ByVal URI As String)

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. component stores on of them.

The following fields are available:

CanonicalizationMethod

SignatureValidationResult

SubjectKeyID

SubjectRDN

XMLElement

Fields

CanonicalizationMethod
XMLCanonicalizationMethods
Default: 0

The XML canonicalization method that was used for signing.

Supported canonicalization methods:


cxcmNone	`0`
cxcmCanon	`1`
cxcmCanonComment	`2`
cxcmExclCanon	`3`
cxcmExclCanonComment	`4`
cxcmMinCanon	`5`
cxcmCanon_v1_1	`6`
cxcmCanonComment_v1_1	`7`

CompatibilityErrors
int (read-only)
Default: 0

Returns compatibility errors encountered during validation.

Use this property to get specific compatibility errors encountered during validation. Unlike chain validation details, compatibility errors indicate violations by the signature of the assumed signature level/profile. For example, BES signatures are required to contain the signing time attribute. A prospective BES signature without such attribute will invoke a compatibility error.

EntityLabel
string (read-only)
Default: ""

Use this property to get the signature entity label.

This property returns a string label that uniquely identifies the signature. The label can be used to establish the signature target in the SignatureFound event or to select the signing chain via the SelectInfo method.

HashAlgorithm
string
Default: "Unknown"

The hash algorithm used for signing.


SB_HASH_ALGORITHM_MD5	`MD5`
SB_HASH_ALGORITHM_SHA1	`SHA1`
SB_HASH_ALGORITHM_SHA224	`SHA224`
SB_HASH_ALGORITHM_SHA256	`SHA256`
SB_HASH_ALGORITHM_SHA384	`SHA384`
SB_HASH_ALGORITHM_SHA512	`SHA512`
SB_HASH_ALGORITHM_RIPEMD160	`RIPEMD160`
SB_HASH_ALGORITHM_GOST_R3411_1994	`GOST1994`
SB_HASH_ALGORITHM_WHIRLPOOL	`WHIRLPOOL`
SB_HASH_ALGORITHM_SHA3_256	`SHA3_256`
SB_HASH_ALGORITHM_SHA3_384	`SHA3_384`
SB_HASH_ALGORITHM_SHA3_512	`SHA3_512`

IssuerRDN
string (read-only)
Default: ""

The Relative Distinguished Name of the signing certificate's issuer.

A collection of information, in the form of [OID, Value] pairs, about the company that issued the signing certificate.

ParentEntity
string
Default: ""

Use this property to get the parent signature label.

This property contains the unique entity label of the current signature's parent object - typically a higher-level signature or a timestamp.

SerialNumber
byte[] (read-only)
Default: ""

The serial number of the signing certificate.

SignatureBytes
byte[] (read-only)
Default: ""

Returns the binary representation of the XML signature.

SignatureType
XMLSignatureTypes
Default: 4

The signature type to employ when signing the document.

This property specifies the signature type to be used when signing the document.

Supported values:


cxstDetached	`1`	Specifies whether a detached signature should be produced. I.e., a signature which is kept separately from the signed document.
cxstEnveloping	`2`	Specifies whether an enveloping signature should be produced.
cxstEnveloped	`4`	Specifies whether an enveloped signature should be produced.

SignatureValidationResult
SignatureValidities (read-only)
Default: 0

The outcome of the cryptographic signature validation.

The following signature validity values are supported:


svtValid	`0`	The signature is valid
svtUnknown	`1`	Signature validity is unknown
svtCorrupted	`2`	The signature is corrupted
svtSignerNotFound	`3`	Failed to acquire the signing certificate. The signature cannot be validated.
svtFailure	`4`	General failure
svtReferenceCorrupted	`5`	Reference corrupted (XML-based signatures only)

SubjectKeyID
byte[] (read-only)
Default: ""

Contains the subject key identifier of the signing certificate.

Subject Key Identifier is a (non-critical) X.509 certificate extension which allows the identification of certificates containing a particular public key. In SecureBlackbox, the unique identifier is represented by a SHA-1 hash of the bit string of the subject public key.

SubjectRDN
string (read-only)
Default: ""

Contains information about the person owning the signing certificate. Only certificates with given subject information will be enumerated during the search operation. Information is stored in the form of [Object Identifier, Value] pairs.

XMLElement
string
Default: ""

Specifies the XML element where to save the signature or containing the signature.

This property specifies the XML element where to save the electronic signature or that contains the signature to be validated.

Supported values are:


""	an empty string indicates the Document element
"#id"	indicates an XML element with specified Id
XPath expression	indicates an XML element selected using XPath expression. Use AddKnownNamespace method to specify Prefixes and NamespaceURIs For example: "/root/data[1]" - indicates the second "data" element under the document element with a name "root" "//ns1:data" - indicates a data element. "ns1" prefix should be defined via AddKnownNamespace method.
Node name	indicates an XML element selected using its NodeName. For example: "data" - indicates an XML element with node name "data".

Constructors

C#
VB.NET

public XMLSignature();

Public XMLSignature()

Creates a new XML signature object.

Config Settings (XMLVerifier Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

XMLVerifier Config Settings

AddAllDataObjectsTimestamp: Whether to add all data objects timestamp during signing.

If this property is set to True, the all data objects timestamp (xades:AllDataObjectsTimeStamp element) will be added.

ClaimedRolesXML: The XML content of the claimed roles.

Use this property to get/specify the XML content of the claimed roles element.

ClaimedRoleText: The text of the claimed role.

Use this property to get/specify the text of the first claimed role.

CommitmentTypeIndicationAllSignedDataObjects[Index]: Specifies the CommitmentTypeIndication's AllSignedDataObjects.

This property contains if the CommitmentTypeIndication's AllSignedDataObjects element is present that indicates that all the signed data objects share the same commitment. Index value could be omitted for the first CommitmentTypeIndication element.

CommitmentTypeIndicationCount: The number of the CommitmentTypeIndication elements.

Returns the number of the xades:CommitmentTypeIndication elements available.

CommitmentTypeIndicationIdentifier[Index]: Specifies the CommitmentTypeIndication's CommitmentTypeId's Identifier.

This property contains an identifier indicating the type of commitment made by the signer in the CommitmentTypeIndication's CommitmentTypeId's Identifier element. Index value could be omitted for the first CommitmentTypeIndication element.

CommitmentTypeIndicationIdentifierDescription[Index]: Specifies the CommitmentTypeIndication's CommitmentTypeId's Description.

This property contains an identifier's description indicating the type of commitment made by the signer in the CommitmentTypeIndication's CommitmentTypeId's Description element. Index value could be omitted for the first CommitmentTypeIndication element.

CommitmentTypeIndicationIdentifierDocumentationReferences[Index]: Specifies the CommitmentTypeIndication's CommitmentTypeId's DocumentationReferences.

This property contains an identifier's documentation references indicating the type of commitment made by the signer in the CommitmentTypeIndication's CommitmentTypeId's DocumentationReferences element. Index value could be omitted for the first CommitmentTypeIndication element.

CommitmentTypeIndicationIdentifierQualifier[Index]: Specifies the CommitmentTypeIndication's CommitmentTypeId's IdentifierQualifier.

This property contains an identifier qualifier indicating the type of commitment made by the signer in the CommitmentTypeIndication's CommitmentTypeId's IdentifierQualifier element. Index value could be omitted for the first CommitmentTypeIndication element.

CommitmentTypeIndicationObjectReference[Index]: Specifies the CommitmentTypeIndication's ObjectReference.

This property contains the CommitmentTypeIndication's ObjectReference elements that refer to one or several ds:Reference elements of the ds:SignedInfo corresponding with one data object qualified by this property. Index value could be omitted for the first CommitmentTypeIndication element.

CommitmentTypeIndicationQualifiersXML[Index]: The XML content of the CommitmentTypeIndication's Qualifiers.

This property contains the CommitmentTypeIndication's Qualifiers elements XML content. Index value could be omitted for the first CommitmentTypeIndication element.

DataObjectFormatCount: The number of the DataObjectFormat elements.

Returns the number of the xades:DataObjectFormat elements available.

DataObjectFormatDescription[Index]: Specifies the DataObjectFormat's Description.

This property contains textual information related to the signed data object in the DataObjectFormat's Description element. Index value could be omitted for the first DataObjectFormat element.

DataObjectFormatEncoding[Index]: Specifies the DataObjectFormat's Encoding.

This property contains an indication of the encoding format of the signed data object in the DataObjectFormat's Encoding element. Index value could be omitted for the first DataObjectFormat element.

DataObjectFormatMimeType[Index]: Specifies the DataObjectFormat's MimeType.

This property contains an indication of the MIME type of the signed data object in the DataObjectFormat's MimeType element. Index value could be omitted for the first DataObjectFormat element.

DataObjectFormatObjectIdentifier[Index]: Specifies the DataObjectFormat's ObjectIdentifier's Identifier.

This property contains an identifier indicating the type of the signed data object in the DataObjectFormat's ObjectIdentifier's Identifier element. Index value could be omitted for the first DataObjectFormat element.

DataObjectFormatObjectIdentifierDescription[Index]: Specifies the DataObjectFormat's ObjectIdentifier's Description.

This property contains an identifier's description indicating the type of the signed data object in the DataObjectFormat's ObjectIdentifier's Description element. Index value could be omitted for the first DataObjectFormat element.

DataObjectFormatObjectIdentifierDocumentationReferences[Index]: Specifies the DataObjectFormat's ObjectIdentifier's DocumentationReferences.

This property contains an identifier's documentation references indicating the type of the signed data object in the DataObjectFormat's ObjectIdentifier's DocumentationReferences element. Index value could be omitted for the first DataObjectFormat element.

DataObjectFormatObjectIdentifierQualifier[Index]: Specifies the DataObjectFormat's ObjectIdentifier's IdentifierQualifier.

This property contains an identifier qualifier indicating the type of the signed data object in the DataObjectFormat's ObjectIdentifier's IdentifierQualifier element. Index value could be omitted for the first DataObjectFormat element.

DataObjectFormatObjectReference[Index]: Specifies the DataObjectFormat's ObjectReference.

This property contains the DataObjectFormat's ObjectReference element that reference the ds:Reference element of the ds:Signature corresponding with the data object qualified by this property.

For example, if the corresponding ds:Reference element has an Id "reference-id-1", then you should set this property to "#reference-id-1" value.

Index value could be omitted for the first DataObjectFormat element.

DataType: Specifies the external data type.

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

The following data types are supported:


"" or "XML"		an XML document (by default).
"data"		a binary data.

DetachedResourceURI: Specifies a detached resource URI.

Specifies a URI of the provided data, usually the data filename if stored along with a detached signature.

ExclusiveCanonicalizationPrefix: Specifies the exclusive canonicalization prefix.

Specifies the prefix for the ec:InclusiveNamespaces element for the exclusive canonicalization.

Default value is "ec". In this case "ec:" prefix will be used.

Special values:


"#default" or ""	indicates that the prefix will be omitted.
"#auto"	indicates that the prefix will be auto-detected based on the parent nodes.

HMACKey: The key value for HMAC.

Use this property to set the HMAC key. The component uses base16 (hex) encoding for this configuration value.

HMACOutputLength: Sets the length of the HMAC output.

Use this property to configure the length of the HMAC output, in bytes.

HMACSigningUsed: Whether to use HMAC signing.

Set this property to true to make the component perform signing using HMAC method, rather than asymmetric cryptography. TBD

IDAttributeName: Specifies the custom name of ID attribute.

This property contains the custom name of identifier (ID) attribute. Used to identify the target XML element when reference URI has "#id_name" value or when ID attribute should be auto-generated for a target XML element.

IDAttributeNamespaceURI: Specifies the custom namespace URI of ID attribute.

This property contains the custom namespace URI of identifier (ID) attribute. Used to identify the target XML element when reference URI has "#id_name" value or when ID attribute should be auto-generated for a target XML element.

IgnoreTimestampFailure: Whether to ignore time-stamping failure during signing.

If this property is set to True, any failure during time-stamping process will be ignored.

IncludeKey: Specifies whether to include the signing key to the signature.

Set this property to True to include the public part of the signing key to the signature.

IncludeKeyValue: Specifies whether the key value must be included to the signature.

Set this property to True if the key value (its public part) should be included to the signature.

IncludeKnownRevocationInfoToSignature: Whether to include custom revocation info to the signature.

This property specifies whether revocation pieces provided via KnownCertificates, KnownCRLs, and KnownOCSPs properties should be included into the signature. This property lets you include custom validation elements to the signature in addition to the ones comprising the signing chain.

InclusiveNamespacesPrefixList: Specifies the InclusiveNamespaces PrefixList.

Use this property to read/specify InclusiveNamespaces PrefixList for exclusive canonicalization transform of SignedInfo element. See XML-Signature Syntax and Processing specification for details.

InsertBeforeXMLElement: Defines the reference XML element for signature insertion.

Use this property to specify XML element before which the signature should be inserted, but it must be under the element specified by the XMLElement field.

Supported values are:


""	an empty string indicates the Document element
"#id"	indicates an XML element with specified Id
XPath expression	indicates an XML element selected using XPath expression. Use AddKnownNamespace method to specify Prefixes and NamespaceURIs For example: "/root/data[1]" - indicates the second "data" element under the document element with a name "root" "//ns1:data" - indicates a data element. "ns1" prefix should be defined via AddKnownNamespace method.
Node name	indicates an XML element selected using its NodeName. For example: "data" - indicates an XML element with node name "data".

KeyInfoCustomXML: The custom XML content for KeyInfo element.

Use this property to specify the custom XML content of the ds:KeyInfo element.

The empty elements in the custom XML content act as a placeholder for auto-generated elements.

For example to change the order of ds:KeyValue and ds:X509Data auto-generated elements use the value: "<X509Data/><KeyValue/>"

KeyInfoDetails: Specifies the signing key info details to include to the signature.

Contains a comma-separated list of values that specifies which signing key info details to include to the signature.

Supported values are:


certificate		Base64-encoded [X509v3] certificate is placed to the signature
issuerserial		X.509 issuer distinguished name/serial number pair are placed to the signature
subjectname		X.509 subject distinguished name is placed to the signature
ski		Base64 encoded plain (i.e. non-DER-encoded) value of a X509 V.3 SubjectKeyIdentifier extension is placed to the signature
crl		Base64-encoded certificate revocation list (CRL) is placed to the signature

KeyInfoID: Specifies the ID for KeyInfo element.

This property contains the identifier (ID) attribute of the ds:KeyInfo element.

KeyName: Contains information about the key used for signing.

The KeyName element contains a string value (with significant whitespaces) which may be used by the signer to communicate a key identifier to the recipient. Typically, the KeyName element contains an identifier related to the key pair used to sign the message, but it may contain other protocol-related information that indirectly identifies a key pair. Common uses of the KeyName include simple string names for keys, a key index, a distinguished name (DN), an email address, etc.

ManifestCount: TBD.

TBD

ManifestID[i]: TBD.

TBD

ManifestObjectIndex[i]: TBD.

TBD

ManifestXML[i]: TBD.

TBD

NormalizeNewLine: Controls whether newline combinations should be automatically normalized.

If set to true (the default value), the component will normalize any non-compliant newline characters to match those appropriate for the operating system.

ObjectCount: TBD.

TBD

ObjectEncoding[i]: TBD.

TBD

ObjectID[i]: TBD.

TBD

ObjectMimeType[i]: TBD.

TBD

ObjectSignaturePropertiesCount: TBD.

TBD

ObjectSignaturePropertiesID[i]: TBD.

TBD

ObjectSignaturePropertiesObjectIndex[i]: TBD.

TBD

ObjectSignaturePropertiesXML[i]: TBD.

TBD

ObjectSignaturePropertyCount: TBD.

TBD

ObjectSignaturePropertyID[i]: TBD.

TBD

ObjectSignaturePropertyPropertiesIndex[i]: TBD.

TBD

ObjectSignaturePropertyTarget[i]: TBD.

TBD

ObjectSignaturePropertyXML[i]: TBD.

TBD

ObjectXML[i]: TBD.

TBD

PolicyDescription: signature policy description.

This property specifies the Description of the signature policy.

PolicyExplicitText: The explicit text of the user notice.

Use this property to specify the explicit text of the user notice to be displayed when the signature is verified.

PolicyUNNumbers: The noticeNumbers part of the NoticeReference CAdES attribute.

Defines the "noticeNumbers" part of the NoticeReference signature policy qualifier for CAdES-EPES.

PolicyUNOrganization: The organization part of the NoticeReference qualifier.

Defines the "organization" part of the NoticeReference signature policy qualifier for CAdES-EPES.

ProductionPlace: Identifies the place of the signature production.

The signature production place in JSON format that was included or to be included into the signature.

Sample value: '{"addressCountry": "UK", "addressLocality": "London", "postalCode": "N1 7GU", "streetAddress": "20-22 Wenlock Road"}'

PSSUsed: Whether to use RSASSA-PSS algorithm.

Although the RSASSA-PSS algorithm provides better security than a classic RSA scheme (PKCS#1-1.5), please take into account that RSASSA-PSS is a relatively new algorithm which may not be understood by older implementations. This is an alias for UsePSS.

QualifyingPropertiesID: Specifies the ID for QualifyingProperties element.

This property contains the identifier (ID) attribute of the xades:QualifyingProperties element.

QualifyingPropertiesObjectID: Specifies the ID for object with QualifyingProperties element.

This property contains the identifier (ID) attribute of the ds:Object element that contains xades:QualifyingProperties element.

QualifyingPropertiesReferenceCount: The number of the QualifyingPropertiesReference elements.

Returns the number of the xades:QualifyingPropertiesReference elements available.

QualifyingPropertiesReferenceID[Index]: Specifies the QualifyingPropertiesReference's ID.

This property contains an identifier (ID) attribute of the xades:QualifyingPropertiesReference element. Index value could be omitted for the first QualifyingPropertiesReference element.

QualifyingPropertiesReferenceURI[Index]: Specifies the QualifyingPropertiesReference's URI.

This property contains an URI attribute of the xades:QualifyingPropertiesReference element. Index value could be omitted for the first QualifyingPropertiesReference element.

RefsTimestampType: Specifies references timestamp type to include to the signature.

Contains a comma-separated list of values that specifies which references timestamp type to include to the signature when signature upgraded to XAdES-X or XAdES-E-X form.

Supported values are:


SigAndRefs		SigAndRefs timestamp
RefsOnly		RefsOnly timestamp

SignatureCompliance: SIgnature compliance with XMLDSig/EBICS.

Specifies whether the signature is compliant with W3C's XMLDSig, or with EBICS (Electronic Banking Internet Communication Standard).

Supported values are:


""		The same as "XML-DSig".
XML-DSig		The W3C's XMLDSig-compliant signature (by default).
EBICS		Electronic Banking Internet Communication Standard (EBICS) compliant signature. On signing the version is autodetected based on the document element.
EBICS_H3		Electronic Banking Internet Communication Standard (EBICS) compliant signature. The version is H3.
EBICS_H4		Electronic Banking Internet Communication Standard (EBICS) compliant signature. The version is H4.
EBICS_H5		Electronic Banking Internet Communication Standard (EBICS) compliant signature. The version is H5.

SignatureID: Specifies the ID for Signature element.

This property contains the identifier (ID) attribute of the ds:Signature element.

SignaturePrefix: Specifies the signature prefix.

Specifies the prefix for the Signature elements.

Default value is "ds". In this case "ds:" prefix will be used.

Special values:


"#default" or ""	indicates that the prefix will be omitted.
"#auto"	indicates that the prefix will be auto-detected based on the parent nodes.

SignatureValueID: Specifies the ID for SignatureValue element.

This property contains the identifier (ID) attribute of the ds:SignatureValue element.

SignedInfoID: Specifies the ID for SignedInfo element.

This property contains the identifier (ID) attribute of the ds:SignedInfo element.

SignedPropertiesID: Specifies the ID for SignedProperties element.

This property contains the identifier (ID) attribute of the xades:SignedProperties element.

SignedPropertiesReferenceCanonicalizationMethod: Specifies the canonicalization method used in SignedProperties reference.

Use this property to specify the canonicalization method for the canonicalization transform of the ds:Reference element that points to xades:SignedProperties element. Use cxcmNone value to not to include canonicalization transform in transform chain.


cxcmNone	`0`
cxcmCanon	`1`
cxcmCanonComment	`2`
cxcmExclCanon	`3`
cxcmExclCanonComment	`4`
cxcmMinCanon	`5`
cxcmCanon_v1_1	`6`
cxcmCanonComment_v1_1	`7`

SignedPropertiesReferenceHashAlgorithm: Specifies the hash algorithm used in SignedProperties reference.

Use this property to specify the hash algorithm to be used for the ds:Reference element that points to xades:SignedProperties element.

Supported values:


SB_HASH_ALGORITHM_MD5	`MD5`
SB_HASH_ALGORITHM_SHA1	`SHA1`
SB_HASH_ALGORITHM_SHA224	`SHA224`
SB_HASH_ALGORITHM_SHA256	`SHA256`
SB_HASH_ALGORITHM_SHA384	`SHA384`
SB_HASH_ALGORITHM_SHA512	`SHA512`
SB_HASH_ALGORITHM_RIPEMD160	`RIPEMD160`
SB_HASH_ALGORITHM_GOST_R3411_1994	`GOST1994`
SB_HASH_ALGORITHM_WHIRLPOOL	`WHIRLPOOL`
SB_HASH_ALGORITHM_SHA3_256	`SHA3_256`
SB_HASH_ALGORITHM_SHA3_384	`SHA3_384`
SB_HASH_ALGORITHM_SHA3_512	`SHA3_512`

The default value is empty string, in this case, the hash algorithm specified in HashAlgorithm property is used.

SignedPropertiesReferenceID: Specifies the ID for Reference element that points to SignedProperties element.

This property contains the identifier (ID) attribute of the ds:Reference element that points to xades:SignedProperties element.

SignedPropertiesReferenceInclusiveNamespacesPrefixList: Specifies the InclusiveNamespaces PrefixList used in SignedProperties reference.

Use this property to specify InclusiveNamespaces PrefixList for exclusive canonicalization transform of the ds:Reference element that points to xades:SignedProperties element.

SignedPropertiesReferenceIndex: Specifies the index of SignedProperties reference.

Use this property to specify the reference's index for the ds:Reference element that points to xades:SignedProperties element.

SignedSignaturePropertiesID: Specifies the ID for SignedSignatureProperties element.

This property contains the identifier (ID) attribute of the xades:SignedSignatureProperties element.

SigningCertificatesChain: The indicator of which certificates should be/are included as the signing chain.

Use this property to check or set the indices of the signing chain included in the signature. The none and all placeholders are supported.

SigningCertificatesHashAlgorithm: Specifies the hash algorithm used for SigningCertificates.

Use this property to specify the hash algorithm to be used for xades:SigningCertificates element.

Supported values:


SB_HASH_ALGORITHM_MD5	`MD5`
SB_HASH_ALGORITHM_SHA1	`SHA1`
SB_HASH_ALGORITHM_SHA224	`SHA224`
SB_HASH_ALGORITHM_SHA256	`SHA256`
SB_HASH_ALGORITHM_SHA384	`SHA384`
SB_HASH_ALGORITHM_SHA512	`SHA512`
SB_HASH_ALGORITHM_RIPEMD160	`RIPEMD160`
SB_HASH_ALGORITHM_GOST_R3411_1994	`GOST1994`
SB_HASH_ALGORITHM_WHIRLPOOL	`WHIRLPOOL`
SB_HASH_ALGORITHM_SHA3_256	`SHA3_256`
SB_HASH_ALGORITHM_SHA3_384	`SHA3_384`
SB_HASH_ALGORITHM_SHA3_512	`SHA3_512`

The default value is empty string, in this case, the hash algorithm specified in HashAlgorithm property is used.

SigPolicyDescription: signature policy description.

This property specifies the Description of the signature policy (an alias for PolicyDescription).

SigPolicyExplicitText: The explicit text of the user notice.

Use this property to specify the explicit text of the user notice to be displayed when the signature is verified (an alias for PolicyExplicitText);

SigPolicyHash: The EPES policy hash.

Use this configuration setting to provide the EPES policy hash.

SigPolicyHashAlgorithm: The hash algorithm that was used to generate the EPES policy hash.

Use this setting to provide the hash algorithm that was used to generate the policy hash.

SigPolicyID: The EPES policy ID.

The EPES signature policy identifier, in dotted OID format (1.2.3.4.5).

SigPolicyNoticeNumbers: The noticeNumbers part of the NoticeReference CAdES attribute.

Defines the "noticeNumbers" part of the NoticeReference signature policy qualifier for CAdES-EPES (an alias for PolicyUNNumbers).

SigPolicyNoticeOrganization: The organization part of the NoticeReference qualifier.

Defines the "organization" part of the NoticeReference signature policy qualifier for CAdES-EPES (an alias for PolicyUNOrganization).

SigPolicyURI: The EPES policy URI.

Assign the EPES policy URI to this setting.

StripWhitespace: Controls whether excessive whitespace characters should be stripped off when loading the document.

Set this property to true to have the component eliminate excessive whitespace from the document on loading.

TimestampCanonicalizationMethod: Specifies canonicalization method used in timestamp.

Use this property to specify the canonicalization method used in timestamp.


cxcmNone	`0`
cxcmCanon	`1`
cxcmCanonComment	`2`
cxcmExclCanon	`3`
cxcmExclCanonComment	`4`
cxcmMinCanon	`5`
cxcmCanon_v1_1	`6`
cxcmCanonComment_v1_1	`7`

TimestampValidationDataDetails: Specifies timestamp validation data details to include to the signature.

Contains a comma-separated list of values that specifies which validation data values details to include to the signature when xades:TimeStampValidationData element added.

Supported values are:


certificate		Base64-encoded [X509v3] certificates
crl		Base64-encoded certificate revocation lists (CRL)
ocsp		OCSP responses

UseHMACSigning: Whether to use HMAC signing.

Set this property to true to make the component perform signing using HMAC method, rather than asymmetric cryptography.

UsePSS: Whether to use RSASSA-PSS algorithm.

ValidationDataRefsDetails: Specifies validation data references details to include to the signature.

Contains a comma-separated list of values that specifies which validation data references details to include to the signature when signature upgraded to XAdES-C or XAdES-E-C form.

Supported values are:


certificate		References to X.509 certificates
crl		References to certificate revocation lists (CRL)
ocsp		References to OCSP responses

ValidationDataRefsHashAlgorithm: Specifies the hash algorithm used in validation data references.

Use this property to specify the hash algorithm used to compute hashes for validation data references.

Supported values:


SB_HASH_ALGORITHM_MD5	`MD5`
SB_HASH_ALGORITHM_SHA1	`SHA1`
SB_HASH_ALGORITHM_SHA224	`SHA224`
SB_HASH_ALGORITHM_SHA256	`SHA256`
SB_HASH_ALGORITHM_SHA384	`SHA384`
SB_HASH_ALGORITHM_SHA512	`SHA512`
SB_HASH_ALGORITHM_RIPEMD160	`RIPEMD160`
SB_HASH_ALGORITHM_GOST_R3411_1994	`GOST1994`
SB_HASH_ALGORITHM_WHIRLPOOL	`WHIRLPOOL`
SB_HASH_ALGORITHM_SHA3_256	`SHA3_256`
SB_HASH_ALGORITHM_SHA3_384	`SHA3_384`
SB_HASH_ALGORITHM_SHA3_512	`SHA3_512`

The default value is empty string, in this case, the hash algorithm specified in HashAlgorithm property is used.

ValidationDataValuesDetails: Specifies validation data values details to include to the signature.

Contains a comma-separated list of values that specifies which validation data values details to include to the signature when signature upgraded to XAdES-X-L or XAdES-E-X-L form.

Supported values are:


certificate		Base64-encoded [X509v3] certificates
crl		Base64-encoded certificate revocation lists (CRL)
ocsp		OCSP responses

WriteBOM: Specifies whether byte-order mark should be written when saving the document.

Set this property to False to disable writing byte-order mark (BOM) when saving the XML document in Unicode encoding.

XAdESPrefix: Specifies the XAdES prefix.

Specifies the prefix for the XAdES elements.

Default value is "xades". In this case "xades:" prefix will be used.

Special values:


"#default" or ""	indicates that the prefix will be omitted.
"#auto"	indicates that the prefix will be auto-detected based on the parent nodes.

XAdESv141Prefix: Specifies the XAdES v1.4.1 prefix.

Specifies the prefix for the XAdES v1.4.1 elements.

Default value is "xadesv141". In this case "xadesv141:" prefix will be used.

Special values:


"#default" or ""	indicates that the prefix will be omitted.
"#auto"	indicates that the prefix will be auto-detected based on the parent nodes.

XMLFormatting: Specifies the signature XML formatting.

Use this property to specify how the signature should be formatted.

Supported values:


"" or "none"		no formatting (by default).
"auto"		enables auto-formatting, equivalent to: "indent: 1; indent-char: tab; base64-max-length: 64; starting-level: node"

Custom values, contains a list of value pairs ("name:value") separated by comma or semicolon:


indent		specifies indentation level (default is 1)
indent-char		specifies indentation character: "space" or "tab" (default)
base64-max-length		specifies max length of base64 encoded data, such as signature value, certificate data and etc. (default is 64)
starting-level		specifies starting indentation level: non-negative integer or "node" - detected based on parent node, or "root" - detected based on number of parent nodes to a document element (default is "node").
indent-before-main		specifies if whitespace characters should be inserted before a main (ds:Signature) element: "auto" (default), "yes" or "no"

For more preciese formatting use OnFormatText and OnFormatElement events.

Base Config Settings

ASN1UseGlobalTagCache: Controls whether ASN.1 module should use a global object cache.

This is a performance setting. It is unlikely that you will ever need to adjust it.

AssignSystemSmartCardPins: Specifies whether CSP-level PINs should be assigned to CNG keys.

This is a low-level tweak for certain cryptographic providers. It is unlikely that you will ever need to adjust it.

CheckKeyIntegrityBeforeUse: Enables or disable private key integrity check before use.

This global property enables or disables private key material check before each signing operation. This slows down performance a bit, but prevents a selection of attacks on RSA keys where keys with unknown origins are used.

You can switch this property off to improve performance if your project only uses known, good private keys.

CookieCaching: Specifies whether a cookie cache should be used for HTTP(S) transports.

Set this property to enable or disable cookies caching for the component.

Supported values are:


off		No caching (default)
local		Local caching
global		Global caching

Cookies: Gets or sets local cookies for the component.

Use this property to get cookies from the internal cookie storage of the component and/or restore them back between application sessions.

DefDeriveKeyIterations: Specifies the default key derivation algorithm iteration count.

This global property sets the default number of iterations for all supported key derivation algorithms. Note that you can provide the required number of iterations by using properties of the relevant key generation component; this global setting is used in scenarios where specific iteration count is not or cannot be provided.

DNSLocalSuffix: The suffix to assign for TLD names.

Use this global setting to adjust the default suffix to assign to top-level domain names. The default is .local.

EnableClientSideSSLFFDHE: Enables or disables finite field DHE key exchange support in TLS clients.

This global property enables or disables support for finite field DHE key exchange methods in TLS clients. FF DHE is a slower algorithm if compared to EC DHE; enabling it may result in slower connections.

This setting only applies to sessions negotiated with TLS version 1.3.

GlobalCookies: Gets or sets global cookies for all the HTTP transports.

Use this property to get cookies from the GLOBAL cookie storage or restore them back between application sessions. These cookies will be used by all the components that have its CookieCaching property set to "global".

HardwareCryptoUsePolicy: The hardware crypto usage policy.

This global setting controls the hardware cryptography usage policy: auto, enable, or disable.

HttpUserAgent: Specifies the user agent name to be used by all HTTP clients.

This global setting defines the User-Agent field of the HTTP request provides information about the software that initiates the request. This value will be used by all the HTTP clients including the ones used internally in other components.

HttpVersion: The HTTP version to use in any inner HTTP client components created.

Set this property to 1.0 or 1.1 to indicate the HTTP version that any internal HTTP clients should use.

IgnoreExpiredMSCTLSigningCert: Whether to tolerate the expired Windows Update signing certificate.

It is not uncommon for Microsoft Windows Update Certificate Trust List to be signed with an expired Microsoft certificate. Setting this global property to true makes SBB ignore the expired factor and take the Trust List into account.

ListDelimiter: The delimiter character for multi-element lists.

Allows to set the delimiter for any multi-entry values returned by the component as a string object, such as file lists. For most of the components, this property is set to a newline sequence.

LogDestination: Specifies the debug log destination.

Contains a comma-separated list of values that specifies where debug log should be dumped.

Supported values are:


file		File
console		Console
systemlog		System Log (supported for Android only)
debugger		Debugger (supported for VCL for Windows and .Net)

LogDetails: Specifies the debug log details to dump.

Contains a comma-separated list of values that specifies which debug log details to dump.

Supported values are:


time		Current time
level		Level
package		Package name
module		Module name
class		Class name
method		Method name
threadid		Thread Id
contenttype		Content type
content		Content
all		All details

LogFile: Specifies the debug log filename.

Use this property to provide a path to the log file.

LogFilters: Specifies the debug log filters.

Contains a comma-separated list of value pairs ("name:value") that describe filters.

Supported filter names are:


exclude-package		Exclude a package specified in the value
exclude-module		Exclude a module specified in the value
exclude-class		Exclude a class specified in the value
exclude-method		Exclude a method specified in the value
include-package		Include a package specified in the value
include-module		Include a module specified in the value
include-class		Include a class specified in the value
include-method		Include a method specified in the value

LogFlushMode: Specifies the log flush mode.

Use this property to set the log flush mode. The following values are defined:


none		No flush (caching only)
immediate		Immediate flush (real-time logging)
maxcount		Flush cached entries upon reaching LogMaxEventCount entries in the cache.

LogLevel: Specifies the debug log level.

Use this property to provide the desired debug log level.

Supported values are:


none		None (by default)
fatal		Severe errors that cause premature termination.
error		Other runtime errors or unexpected conditions.
warning		Use of deprecated APIs, poor use of API, 'almost' errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong".
info		Interesting runtime events (startup/shutdown).
debug		Detailed information on flow of through the system.
trace		More detailed information.

LogMaxEventCount: Specifies the maximum number of events to cache before further action is taken.

Use this property to specify the log event number threshold. This threshold may have different effects, depending on the rotation setting and/or the flush mode.

The default value of this setting is 100.

LogRotationMode: Specifies the log rotation mode.

Use this property to set the log rotation mode. The following values are defined:


none		No rotation
deleteolder		Delete older entries from the cache upon reaching LogMaxEventCount
keepolder		Keep older entries in the cache upon reaching LogMaxEventCount (newer entries are discarded)

MaxASN1BufferLength: Specifies the maximal allowed length for ASN.1 primitive tag data.

This global property limits the maximal allowed length for ASN.1 tag data for non-content-carrying structures, such as certificates, CRLs, or timestamps. It does not affect structures that can carry content, such as CMS/CAdES messages. This is a security property aiming at preventing DoS attacks.

MaxASN1TreeDepth: Specifies the maximal depth for processed ASN.1 trees.

This global property limits the maximal depth of ASN.1 trees that the component can handle without throwing an error. This is a security property aiming at preventing DoS attacks.

OCSPHashAlgorithm: Specifies the hash algorithm to be used to identify certificates in OCSP requests.

This global setting defines the hash algorithm to use in OCSP requests during chain validation. Some OCSP responders can only use older algorithms, in which case setting this property to SHA1 may be helpful.

OldClientSideRSAFallback: Specifies whether the SSH client should use a SHA1 fallback.

Tells the SSH client to use a legacy ssh-rsa authentication even if the server indicates support for newer algorithms, such as rsa-sha-256. This is a backward-compatibility tweak.

PKICache: Specifies which PKI elements (certificates, CRLs, OCSP responses) should be cached.

The PKICache setting specifies which Public Key Infrastructure (PKI) elements should be cached to optimize performance and reduce retrieval times. It supports comma-separated values to indicate the specific types of PKI data that should be cached.

Supported Values:


certificate	Enables caching of certificates.
crl	Enables caching of Certificate Revocation Lists (CRLs).
ocsp	Enables caching of OCSP (Online Certificate Status Protocol) responses.

Example (default value): PKICache=certificate,crl,ocsp In this example, the component caches certificates, CRLs, and OCSP responses.

PKICachePath: Specifies the file system path where cached PKI data is stored.

The PKICachePath setting defines the file system path where cached PKI data (e.g., certificates, CRLs, OCSP responses and Trusted Lists) will be stored. This allows the system to persistently save and retrieve PKI cache data, even across application restarts.

The default value is an empty string - no cached PKI data is stored on disk.

Example: PKICachePath=C:\Temp\cache In this example, the cached PKI data is stored in the C:\Temp\cache directory.

ProductVersion: Returns the version of the SecureBlackbox library.

This property returns the long version string of the SecureBlackbox library being used (major.minor.build.revision).

ServerSSLDHKeyLength: Sets the size of the TLS DHE key exchange group.

Use this property to adjust the length, in bits, of the DHE prime to be used by the TLS server.

StaticDNS: Specifies whether static DNS rules should be used.

Set this property to enable or disable static DNS rules for the component. Works only if UseOwnDNSResolver is set to true.

Supported values are:


none		No static DNS rules (default)
local		Local static DNS rules
global		Global static DNS rules

StaticIPAddress[domain]: Gets or sets an IP address for the specified domain name.

Use this property to get or set an IP address for the specified domain name in the internal (of the component) or global DNS rules storage depending on the StaticDNS value. The type of the IP address (IPv4 or IPv6) is determined automatically. If both addresses are available, they are devided by the | (pipe) character.

StaticIPAddresses: Gets or sets all the static DNS rules.

Use this property to get static DNS rules from the current rules storage or restore them back between application sessions. If StaticDNS of the component is set to "local", the property returns/restores the rules from/to the internal storage of the component. If StaticDNS of the component is set to "global", the property returns/restores the rules from/to the GLOBAL storage. The rules list is returned and accepted in JSON format.

Tag: Allows to store any custom data.

Use this config property to store any custom data.

TLSSessionGroup: Specifies the group name of TLS sessions to be used for session resumption.

Use this property to limit the search of chached TLS sessions to the specified group. Sessions from other groups will be ignored. By default, all sessions are cached with an empty group name and available to all the components.

TLSSessionLifetime: Specifies lifetime in seconds of the cached TLS session.

Use this property to specify how much time the TLS session should be kept in the session cache. After this time, the session expires and will be automatically removed from the cache. Default value is 300 seconds (5 minutes).

TLSSessionPurgeInterval: Specifies how often the session cache should remove the expired TLS sessions.

Use this property to specify the time interval of purging the expired TLS sessions from the session cache. Default value is 60 seconds (1 minute).

UseCRLObjectCaching: Specifies whether reuse of loaded CRL objects is enabled.

This setting enables or disables the caching of CRL objects. When set to true (the default value), the system checks if a CRL object is already loaded in memory before attempting to load a new instance. If the object is found, the existing instance is reused, and its reference count is incremented to track its usage. When the reference count reaches zero, indicating that no references to the object remain, the system will free the object from memory. This setting enhances performance by minimizing unnecessary object instantiation and promotes efficient memory management, particularly in scenarios where CRL objects are frequently used.

UseInternalRandom: Switches between SecureBlackbox-own and platform PRNGs.

Allows to switch between internal/native PRNG implementation and the one provided by the platform.

UseLegacyAdESValidation: Enables legacy AdES validation mode.

Use this setting to switch the AdES component to the validation approach that was used in SBB 2020/SBB 2022 (less attention to temporal details).

UseOCSPResponseObjectCaching: Specifies whether reuse of loaded OCSP response objects is enabled.

This setting enables or disables the caching of OCSP response objects. When set to true (the default value), the system checks if a OCSP response object is already loaded in memory before attempting to load a new instance. If the object is found, the existing instance is reused, and its reference count is incremented to track its usage. When the reference count reaches zero, indicating that no references to the object remain, the system will free the object from memory. This setting enhances performance by minimizing unnecessary object instantiation and promotes efficient memory management, particularly in scenarios where OCSP response objects are frequently used.

UseOwnDNSResolver: Specifies whether the client components should use own DNS resolver.

Set this global property to false to force all the client components to use the DNS resolver provided by the target OS instead of using own one.

UseSharedSystemStorages: Specifies whether the validation engine should use a global per-process copy of the system certificate stores.

Set this global property to false to make each validation run use its own copy of system certificate stores.

UseSystemNativeSizeCalculation: An internal CryptoAPI access tweak.

This is an internal setting. Please do not use it unless instructed by the support team.

UseSystemOAEPAndPSS: Enforces or disables the use of system-driven RSA OAEP and PSS computations.

This global setting defines who is responsible for performing RSA-OAEP and RSA-PSS computations where the private key is stored in a Windows system store and is exportable. If set to true, SBB will delegate the computations to Windows via a CryptoAPI call. Otherwise, it will export the key material and perform the computations using its own OAEP/PSS implementation.

This setting only applies to certificates originating from a Windows system store.

UseSystemRandom: Enables or disables the use of the OS PRNG.

Use this global property to enable or disable the use of operating system-driven pseudorandom number generation.

XMLRDNDescriptorName[OID]: Defines an OID mapping to descriptor names for the certificate's IssuerRDN or SubjectRDN.

This property defines custom mappings between Object Identifiers (OIDs) and descriptor names. This mapping specifies how the certificate's issuer and subject information (ds:IssuerRDN and ds:SubjectRDN elements respectively) are represented in XML signatures.

The property accepts comma-separated values where the first descriptor name is used when the OID is mapped, and subsequent values act as aliases for parsing.

Syntax: Config("XMLRDNDescriptorName[OID]=PrimaryName,Alias1,Alias2");

Where:

OID: The Object Identifier from the certificate's IssuerRDN or SubjectRDN that you want to map.

PrimaryName: The main descriptor name used in the XML signature when the OID is encountered.

Alias1, Alias2, ...: Optional alternative names recognized during parsing.

Usage Examples:

Map OID 2.5.4.5 to SERIALNUMBER: Config("XMLRDNDescriptorName[2.5.4.5]=SERIALNUMBER");

Map OID 1.2.840.113549.1.9.1 to E, with aliases EMAIL and EMAILADDRESS: Config("XMLRDNDescriptorName[1.2.840.113549.1.9.1]=E,EMAIL,EMAILADDRESS");

XMLRDNDescriptorPriority[OID]: Specifies the priority of descriptor names associated with a specific OID.

This property specifies the priority of descriptor names associated with a specific OID that allows to reorder descriptors in the ds:IssuerRDN and ds:SubjectRDN elements during signing.

XMLRDNDescriptorReverseOrder: Specifies whether to reverse the order of descriptors in RDN.

Specifies whether to reverse the order of descriptors in the ds:IssuerRDN and ds:SubjectRDN elements during XML signing. By default, this property is set to true (as specified in RFC 2253, 2.1).

XMLRDNDescriptorSeparator: Specifies the separator used between descriptors in RDN.

Specifies the separator used between descriptors in the ds:IssuerRDN and ds:SubjectRDN elements during XML signing. By default, this property is set to ", " value.

Trappable Errors (XMLVerifier Component)

XMLVerifier Errors

1048577	Invalid parameter (`SB_ERROR_INVALID_PARAMETER`)
1048578	Invalid configuration (`SB_ERROR_INVALID_SETUP`)
1048579	Invalid state (`SB_ERROR_INVALID_STATE`)
1048580	Invalid value (`SB_ERROR_INVALID_VALUE`)
1048581	Private key not found (`SB_ERROR_NO_PRIVATE_KEY`)
1048582	Cancelled by the user (`SB_ERROR_CANCELLED_BY_USER`)
1048583	The file was not found (`SB_ERROR_NO_SUCH_FILE`)
1048584	Unsupported feature or operation (`SB_ERROR_UNSUPPORTED_FEATURE`)
1048585	General error (`SB_ERROR_GENERAL_ERROR`)
39845889	The input file does not exist (`SB_ERROR_XML_INPUTFILE_NOT_EXISTS`)
39845890	Data file does not exist (`SB_ERROR_XML_DATAFILE_NOT_EXISTS`)
39845892	Unsupported hash algorithm (`SB_ERROR_XML_UNSUPPORTED_HASH_ALGORITHM`)
39845893	Unsupported key type (`SB_ERROR_XML_UNSUPPORTED_KEY_TYPE`)
39845895	Unsupported encryption algorithm (`SB_ERROR_XML_INVALID_ENCRYPTION_METHOD`)
39845896	XML element not found (`SB_ERROR_XML_NOT_FOUND`)
39845897	XML element has no ID (`SB_ERROR_XML_NO_ELEMENT_ID`)