SecureBlackbox 2020 macOS Edition

Questions / Feedback?

XAdESSigner Module

Properties   Methods   Events   Configuration Settings   Errors  

The XAdESSigner component creates XAdES-compliant signature files.

Syntax

nsoftware.SecureBlackbox.Xadessigner

Remarks

XAdESSigner can sign XML documents in accordance with XAdES standard. Originally developed and adopted in the European Union, XAdES has quickly become a recognized international standard for signing XML documents. XAdES provides a convenient framework for creating short-lived and long-term signatures over any kind of XML documents, and is now used by governments, healthcare providers, banks, and independent service providers all across the globe.

Standards and technologies supported

XAdESSigner offers the following signing capabilities:

  • Create and upgrade XAdES signatures in accordance with the most recent XAdES specification (ETSI EN 319 132). Earlier versions are also supported.
  • All profiles are supported (BES, EPES, T, C, X, XL, A, including the Extended variants).
  • Timestamping using external TSAs.
  • All industry-standard cryptographic algorithms (RSA, ECDSA, SHA256-512, and many others).

Configuring the signature parameters

Configuring XAdESSigner to make it produce a signature of the right type is the main task you would need to perform in your code. Normally the service or software you will be communicating your XML documents to will provide you with the list of requirements that your signatures should match.

Typically, those will dictate the following key aspects of the signatures:

  • The signature Form, sometimes referred to as Level (such BES, T, XL, A, or Extended-XLong). This can be adjusted with the XAdESForm property.
  • Whether the signature should be detached, enveloped, or enveloping: adjust via SignatureType property.
  • When creating a timestamped signature (such as T or A), provide the address of your online TSA service via TimestampServer property.
  • When creating long-term signatures that include the signing chain and validation material, tune up validation parameters via RevocationCheck, OfflineMode, and IgnoreChainValidationErrors properties.

In some circumstances you will also need to adjust the following lower-level settings:

  • Choose a specific XAdES version between 1.4.1, 1.3.2, 1.2.2, and 1.1.1, and assign it to XAdESVersion property.
  • Specify the needed canonicalization method using the CanonicalizationMethod property.
  • Provide the hash algorithm via the HashAlgorithm property.

Signing certificates

XAdESSigner can use certificates residing on different media. Besides generic certificates stored in PFX or PEM files (A1), it can operate with non-exportable certificates residing on hardware media (A3) or in the cloud.

Non-exportable certificates can be accessed transparently via a Windows CSP or a PKCS#11 driver, if supplied by the certificate issuer. Proprietary interfaces can be plugged in with the external signing feature (see below).

You can use CertificateManager and CertificateStorage components to access the signing certificate. Assign the certificate to SigningCertificate property, and optionally provide the remainder of its chain via SigningChain property.

Note: If signing with a non-exportable key (such as residing on a hardware device or in the cloud), please make sure you keep the original CertificateStorage object open until the signing is completed. This is because the storage component provides a 'bridge' to the private key. If the storage is closed prematurely, this bridge is destroyed, and the private key can't be used.

You don't need to provide a signing certificate or chain when timestamping and upgrading signatures, since this type of operation does not involve the signing private key.

Signing the document

Now that you have set up all signature properties and attached the signing certificate, it is time to proceed to signing. You can provide the input document in one of the following forms: as a file (assign the path to InputFile property), as a stream (assign to InputStream property), or as a byte array (assign to InputBytes). Similarly, the output can be collected in one of the same forms, either by passing the destination path or stream via OutputFile and OutputStream respectively, or by reading the resulting document bytes from the OutputBytes property after the signing completes.

Having set up the input and output (unless using OutputBytes, which should be read later), call the component's Sign method. This will initiate the signing process. Depending on the settings, the signing may be as straightforward as calculating the document hash and signing it with the private key (e.g. in XAdES-BES variant), or it may involve advanced chain validation routines (XAdES-XL or -A). During the latter the component may contact a number of external revocation information sources (CRL and OCSP servers) to establish the validity of the signing certificate.

If a TSA server was provided via the TimestampServer property, the component will contact it too to timestamp the new signature.

During the signing XAdESSigner may fire events to let your code know of certain conditions. It may fire TLSCertValidate if one of the HTTP endpoints involved in the operation (which may be a CRL, OCSP, or TSA service) works over TLS and needs its certificate to be validated. It may also fire FormatElement and FormatText to let your code apply custom formatting to XML document elements. If XAdESSigner fails to resolve one of the references in the signature, it will fire ResolveReference to let your code help with resolving it.

When the signing operation completes, the output file, stream, or byte array will contain the signature of the requested kind. Note that while nveloped and enveloping signatures contain the signed content within them, detached signatures assume that you supply the original content separately.

Apart from signing, XAdESSigner can perform operations on signatures of other kinds. Use Upgrade method to upgrade an existing XAdES signature to a higher level (e.g. BES to XL). Use Timestamp to add a generic or validation timestamp to an existing signature.

External signing and DCAuth

XAdESSigner, like many other components offered by the product, supports two methods of signing with external keys. These methods are fully independent of each other: you can choose the one that suits your usage scenario best.

Synchronous method: ExternalSign

This is a simpler method that basically lets you infiltrate into the heart of the signing routine by taking care of the hash signing operation. The component does the rest of the job (hash calculation, preparation of signature objects, CRL/OCSP retrieval).

To initiate this method, call SignExternal instead of Sign. When the hash is ready, it will be passed back to your code with ExternalSign event. Your event handler needs to sign the hash with the private key and return the created signature back to the component - which will embed it into the document.

You don't need your signing certificate to contain an associated private key when using this method. The certificate itself (its public copy) may be needed though, as it is often included in the hash calculation.

This method is synchronous, meaning SignExternal provides you the results immediately upon its completion.

Asynchronous method: DCAuth

DCAuth is a SecureBlackbox-own know-how technology. This protocol was designed to allow sharing of private keys across environments, allowing the signer and the private key to reside on different systems. It works in the following way:

  • The signing party - such as XAdESSigner - initiates the operation using SignAsyncBegin call. This produces two outcomes: a pre-signed document (a document with a blank signature placeholder), and a request state (an object containing a hash that needs to be signed). At this point the XAdESSigner instance can be released, and the process itself terminated (which may be useful when run as part of a web page).
  • The request state is passed to the private key holder party. The private key holder passes the request state to a DCAuth object, which parses the request state, extracts the hash, and signs it. The output of DCAuth processing is another object, response state, which contains the signature. The private key holder then sends the response state back to the signing party.
  • The signing party re-creates the controls, and passes the response state, together with the pre-signed version of the document, to the signer's SignAsyncEnd method. SignAsyncEnd extracts the signature from the response state and incorporates it into the pre-signed document.

This method is asynchronous in that sense that, from the signing party's viewpoint, it splits the signing operation into the pre-signing and completion stages which can be performed independently from each other and in different execution contexts. This makes this method particularly helpful for use in web pages and other scenarios where the signing key is not available in real time.

Fine-grained chain validation setup

Chain validation is a sophisticated, multi-faceted procedure that involves a lot of variables. Depending on the configuration of your operating environment, the specifics of the PKI framework being used, and the validation policy you need to follow, you may want to tune up your chain validation parameters so they fit them best. Below is given a summary of such parameters.

  • RevocationCheck property lets you choose between and/or prioritize revocation origins. OCSP sources are often preferred to CRL because of their real-time capability and the smaller size of validation tokens they produce.
  • OfflineMode is a master switch that stops class from looking for any validation tokens online. If this property is switched on, the component will only use KnownCertificates, TrustedCertificates, KnownCRLs, and KnownOCSPs collections to look for the missing validation material.
  • IgnoreChainValidationErrors makes the component ignore any major validation issues it encounters (such us an untrusted chain or missing CRL). This option is handy for debugging and for creating signatures in the environments where the signing certificate is not trusted.
  • KnownCertificates, KnownCRLs, and KnownOCSPs let you provide your own validation material. This may be useful when working in OfflineMode, where the signer has no access to the validation sources, or where the validation material has already been collected.
  • TrustedCertificates lets you provide a list of trust anchors, either as a complement to the system's or as an alternative for it.
  • BlockedCertificates lets you provide a list of blocked/distrusted certificates. Any CA certificate contained in it will be deemed untrusted/invalid.

The following parameters are not directly related to chain validation, but may have an implicit effect on it.

  • Proxy, SocketSettings, and TLSSettings let you tune up the connectivity and TLS options in accordance with local preferences.
  • TLSClientChain lets you provide the client certificate and its chain for TLS client authentication.
  • Subscribe to TLSCertValidate to validate any TLS certificates of the services involved in chain validation.

The results of the chain validation procedure, upon its completion, are published in the following properties:

  • ChainValidationResult contains the primary result of the chain validation routine: valid, valid but untrusted, invalid, or undefined.
  • ChainValidationDetails provides the details of the factors that contributed to the chain validation result, such as an outdated certificate, a missing CRL, or a missing CA certificate.
  • ValidationLog contains the detailed chain validation log. The log can often be very helpful in nailing down various validation issues.

Property List


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

BlockedCertificatesThe certificates that must be rejected as trust anchors.
CanonicalizationMethodSpecifies XML canonicalization method to use.
ChainValidationDetailsThe details of a certificate chain validation outcome.
ChainValidationResultThe general outcome of a certificate chain validation routine. Use ChainValidationDetails to get information about the reasons that contributed to the validation result.
ClaimedSigningTimeThe signing time from the signer's computer.
EnableXAdESSpecifies if an advanced signature (XAdES) will be produced.
EncodingSpecifies XML encoding.
ExternalCryptoProvides access to external signing and DC parameters.
HashAlgorithmSpecifies the hash algorithm to be used.
IgnoreChainValidationErrorsMakes the component tolerant to chain validation errors.
InputBytesUse this property to pass the input to component in the byte array form.
InputFileThe XML document to sign.
KnownCertificatesAdditional certificates for chain validation.
KnownCRLsAdditional CRLs for chain validation.
KnownOCSPsAdditional OCSP responses for chain validation.
OfflineModeSwitches the component to the offline mode.
OutputBytesUse this property to read the output the component object has produced.
OutputFileSpecifies the file where the signed document will be saved.
ProfileSpecifies a pre-defined profile to apply when creating the signature.
ProxyThe proxy server settings.
ReferencesA list of references to the data to be signed.
RevocationCheckSpecifies the kind(s) of revocation check to perform.
SignatureTypeThe signature type to employ when signing the document.
SigningCertificateThe certificate to be used for signing.
SigningChainThe signing certificate chain.
SocketSettingsManages network connection settings.
TimestampServerThe address of the timestamping server.
TLSClientChainThe TLS client certificate chain.
TLSServerChainThe TLS server's certificate chain.
TLSSettingsManages TLS layer settings.
TrustedCertificatesA list of trusted certificates for chain validation.
ValidationLogContains the complete log of the certificate validation routine.
XAdESFormSpecifies which form of XAdES should be produced.
XAdESVersionSpecifies XAdES version.
XMLElementSpecifies the XML element where to save the signature data.
XPathNamespacesSpecifies namespaces for the XPath expression.

Method List


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

AddDataReferenceCreates a new XML reference to the specified data.
AddReferenceCreates a new XML reference to the specified XML element.
ConfigSets or retrieves a configuration setting.
ExtractAsyncDataExtracts user data from the DC signing service response.
SignSigns an XML document.
SignAsyncBeginInitiates the asynchronous signing operation.
SignAsyncEndCompletes the asynchronous signing operation.
SignExternalSigns the document using an external signing facility.
TimestampUse this method to add timestamp.
UpgradeUpgrades existing XAdES signature to a new form.

Event List


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

ErrorInformation about errors during signing.
ExternalSignHandles remote or external signing initiated by the SignExternal method or other source.
FormatElementReports the XML element that is currently being processed.
FormatTextReports XML text that is currently being processed.
NotificationThis event notifies the application about an underlying control flow event.
ResolveReferenceAsks the application to resolve a reference.
StoreCertificateThis event is fired when a certificate should be stored along with a signature.
StoreCRLThis event is fired when a CRL should be stored along with a signature.
StoreOCSPResponseThis event is fired when a OCSP Response should be stored along with a signature.
TLSCertValidateThis event is fired upon receipt of the TLS server's certificate, allowing the user to control its acceptance.

Configuration Settings


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

ClaimedRoleTextThe text of the claimed role.
ClaimedRoleXMLThe XML content of the claimed roles.
CommitmentTypeIndicationAllSignedDataObjects[Index]Specifies the CommitmentTypeIndication's AllSignedDataObjects.
CommitmentTypeIndicationCountThe 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.
DataObjectFormatCountThe 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.
DetachedResourceURISpecifies a detached resource URI.
EnvelopingObjectEncodingSpecifies the enveloping object encoding.
EnvelopingObjectIDSpecifies the enveloping object identifier.
EnvelopingObjectMimeTypeSpecifies the enveloping object MIME type.
ExclusiveCanonicalizationPrefixSpecifies the exclusive canonicalization prefix.
ForceCompleteChainValidationWhether to check the CA certificates when the signing certificate is invalid.
ForceCompleteChainValidationForTrustedWhether to continue with the full validation up to the root CA certificate for mid-level trust anchors.
GracePeriodSpecifies a grace period to apply during revocation information checks.
HMACKeyThe key value for HMAC.
HMACOutputLengthTBD.
IDAttributeNameSpecifies the custom name of ID attribute.
IDAttributeNamespaceURISpecifies the custom namespace URI of ID attribute.
IgnoreOCSPNoCheckExtensionWhether OCSP NoCheck extension should be ignored.
IgnoreSystemTrustWhether trusted Windows Certificate Stores should be treated as trusted.
IgnoreTimestampFailureWhether to ignore time-stamping failure during signing.
ImplicitlyTrustSelfSignedCertificatesWhether to trust self-signed certificates.
IncludeKeySpecifies whether to include the signing key to the signature.
IncludeKeyValueSpecifies whether the key value must be included to the signature.
IncludeKnownRevocationInfoToSignatureWhether to include custom revocation info to the signature.
InclusiveNamespacesPrefixListSpecifies the InclusiveNamespaces PrefixList.
InputTypeSpecifies the Input type.
KeyInfoCustomXMLThe custom XML content for KeyInfo element.
KeyInfoDetailsSpecifies the signing key info details to include to the signature.
KeyInfoIDSpecifies the ID for KeyInfo element.
KeyNameContains information about the key used for signing.
ManifestCountThe number of the manifest elements.
ManifestID[Index]The ID of the manifest element.
ManifestObjectIndex[Index]The object element index to which the manifest element belongs.
ManifestXML[Index]The XML content of the manifest element.
ObjectCountThe number of the object elements.
ObjectEncoding[Index]The Encoding of the object element.
ObjectID[Index]The ID of the object element.
ObjectMimeType[Index]The MIME type of the object element.
ObjectXML[Index]The XML content of the object element.
ProductionPlaceIdentifies the place of the signature production.
PromoteLongOCSPResponsesWhether long OCSP responses are requested.
QualifyingPropertiesIDSpecifies the ID for QualifyingProperties element.
RefsTimestampTypeSpecifies references timestamp type to include to the signature.
SignatureComplianceSpecifies the signature compliance mode.
SignatureIDSpecifies the ID for Signature element.
SignaturePrefixSpecifies the signature prefix.
SignaturePropertiesCountThe number of the signature properties elements.
SignaturePropertiesID[Index]The ID of the signature properties element.
SignaturePropertiesObjectIndex[Index]The object element index to which the signature properties element belongs.
SignaturePropertiesXML[Index]The XML content of the signature properties element.
SignaturePropertyCountThe number of the signature property elements.
SignaturePropertyID[Index]The ID of the signature properties element.
SignaturePropertyPropertiesIndex[Index]The signature properties element index to which the signature property element belongs.
SignaturePropertyTarget[Index]The Target of the signature properties element.
SignaturePropertyXML[Index]The XML content of the signature property element.
SignatureValueContains the SignatureValue.
SignatureValueIDSpecifies the ID for SignatureValue element.
SignedInfoIDSpecifies the ID for SignedInfo element.
SignedPropertiesIDSpecifies the ID for SignedProperties element.
SignedPropertiesReferenceCanonicalizationMethodSpecifies the canonicalization method used in SignedProperties reference.
SignedPropertiesReferenceHashAlgorithmSpecifies the hash algorithm used in SignedProperties reference.
SignedPropertiesReferenceIDSpecifies the ID for Reference element that points to SignedProperties element.
SignedPropertiesReferenceInclusiveNamespacesPrefixListSpecifies the InclusiveNamespaces PrefixList used in SignedProperties reference.
SignedPropertiesReferenceIndexSpecifies the index of SignedProperties reference.
SignedSignaturePropertiesIDSpecifies the ID for SignedSignatureProperties element.
SigningCertificatesHashAlgorithmSpecifies the hash algorithm used for SigningCertificates.
SigPolicyDescriptionsignature policy description.
SigPolicyExplicitTextThe explicit text of the user notice.
SigPolicyHashThe hash value of the signature policy.
SigPolicyHashAlgorithmSpecifies the hash algorithm used to compute the signature policy hash.
SigPolicyIDIdentifies the signature policy.
SigPolicyNoticeNumbersContains user notice numbers.
SigPolicyNoticeOrganizationThe organization part of the NoticeReference qualifier.
SigPolicyURISignature policy URI.
TempPathLocation where the temporary files are stored.
TimestampCanonicalizationMethodSpecifies canonicalization method used in timestamp.
TimestampValidationDataDetailsSpecifies timestamp validation data details to include to the signature.
TLSChainValidationDetailsContains the advanced details of the TLS server certificate validation.
TLSChainValidationResultContains the result of the TLS server certificate validation.
TLSClientAuthRequestedIndicates whether the TLS server requests client authentication.
TLSValidationLogContains the log of the TLS server certificate validation.
TolerateMinorChainIssuesWhether to tolerate minor chain issues.
TspHashAlgorithmSets a specific hash algorithm for use with the timestamping service.
UseHMACSigningWhether to use HMAC signing.
UseMicrosoftCTLEnables or disables automatic use of Microsoft online certificate trust list.
UsePSSWhether to use RSASSA-PSS algorithm.
UseSystemCertificatesEnables or disables the use of the system certificates.
UseValidationCacheEnables or disable the use of the product-wide certificate chain validation cache.
ValidationDataRefsDetailsSpecifies validation data references details to include to the signature.
ValidationDataRefsHashAlgorithmSpecifies the hash algorithm used in validation data references.
ValidationDataValuesDetailsSpecifies validation data values details to include to the signature.
WriteBOMSpecifies whether byte-order mark should be written when saving the document.
XAdESPrefixSpecifies the XAdES prefix.
XAdESv141PrefixSpecifies the XAdES v1.4.1 prefix.
XMLFormattingSpecifies the signature XML formatting.
CheckKeyIntegrityBeforeUseEnables or disable private key integrity check before use.
CookieCachingSpecifies whether a cookie cache should be used for HTTP(S) transports.
CookiesGets or sets local cookies for the component (supported for HTTPClient, RESTClient and SOAPClient only).
DefDeriveKeyIterationsSpecifies the default key derivation algorithm iteration count.
EnableClientSideSSLFFDHEEnables or disables finite field DHE key exchange support in TLS clients.
GlobalCookiesGets or sets global cookies for all the HTTP transports.
HttpUserAgentSpecifies the user agent name to be used by all HTTP clients.
LogDestinationSpecifies the debug log destination.
LogDetailsSpecifies the debug log details to dump.
LogFileSpecifies the debug log filename.
LogFiltersSpecifies the debug log filters.
LogFlushModeSpecifies the log flush mode.
LogLevelSpecifies the debug log level.
LogMaxEventCountSpecifies the maximum number of events to cache before further action is taken.
LogRotationModeSpecifies the log rotation mode.
MaxASN1BufferLengthSpecifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepthSpecifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithmSpecifies the hash algorithm to be used to identify certificates in OCSP requests.
UseOwnDNSResolverSpecifies whether the client components should use own DNS resolver.
UseSharedSystemStoragesSpecifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemOAEPAndPSSEnforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandomEnables or disables the use of the OS PRNG.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 macOS Edition - Version 20.0 [Build 8165]