SecureBlackbox 2020 Node.js Edition

Questions / Feedback?

DCAuth Class

Properties   Methods   Events   Configuration Settings   Errors  

The DCAuth class represents the private key side of the SecureBlackbox distributed cryptography protocol.

Syntax

secureblackbox.dcauth()

Remarks

The purpose of DCAuth is to sign async requests produced by SignAsyncBegin calls. For each incoming async request containing a document hash, DCAuth produces the corresponding async response containing a signature over that hash.

Protocol Overview


The distributed cryptography protocol involves two principal parties. The signing party, represented by classes such as PDFSigner, XAdESSigner, or OfficeSigner, pre-signs documents (such as PDF files), and encapsulates their hashes into what is called an async request. It then communicates the async request to the private key side, where the DCAuth class extracts the hash and signs it with a local private key. DCAuth then encapsulates the signature into an async response, which is sent back to the signing party. The signing party completes the signing operation by extracting the signature from the async response and embedding it into the pre-signed document.

The protocol supports a variety of uses. The scheme above describes the most typical of them, where the signing party is represented by a web application, and the private key side is represented by a workstation. In that particular scenario DC provides a mechanism for the web app to sign documents residing on the web server with private keys residing on the users workstations, perhaps in non-exportable form (e.g. a USB dongle). Other uses include creation of a signing server for a team of driver developers, or an automated signing gateway for outgoing official documents.

In the webapp-to-browser setting the DCAuth control would normally be used within a web server running on the users workstation. That web server would accept async requests from the web page running in the browser, use DCAuth to generate the matching async response, and feed that response back to the web page. The web page will then submit it back to the web server.

Configuring and Using DCAuth

To process an async request, you need to set up a DCAuth object first, and then call its ProcessRequest method:

  • Set the KeyId and KeySecret properties so they match the credentials used by the signing party - e.g. those of PDFSigner object:
          DCAuth.KeyId = "mykeyid";
          DCAuth.KeySecret = "mykeysecret123";
        

    These two properties are used to verify the integrity of the incoming async requests. Keep them safe.

  • Provide the signing certificate:
          DCAuth.SigningCertificate = "C:\Certs\SigningCert.pfx";
          DCAuth.CertPassword = "password789";
        

    Alternatively, use StorageId to provide a certificate residing elsewhere, such as a PKCS#11 device.

  • Assign the async request to the Input property:
          DCAuth.Input = Request;
        

    Make sure to provide the request in its original XML format. Some technologies and SecureBlackbox code samples may apply additional encoding when conveying async requests from their origin to the DCAuth endpoint. Please double check that you assign the request without any encodings applied. An async request is a properly formed XML document with the root element of SecureBlackboxAsyncState.

  • Call the ProcessRequest method:
          DCAuth.ProcessRequest;
        

    This method performs the actual signing of the hash. Make sure your code is prepared for potential signing errors.

  • If the ProcessRequest call has succeeded, grab the async response from the Output property:
          Result = DCAuth.Output;
        
Please see the demo folder for more in-depth code examples of this class.

Property List


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

CertPasswordSpecifies the signing certificate password.
ExternalCryptoCustomParamsCustom parameters to be passed to the signing service (uninterpreted).
ExternalCryptoDataAdditional data to be included in the async state and mirrored back by the requestor.
ExternalCryptoExternalHashCalculationSpecifies whether the message hash is to be calculated at the external endpoint.
ExternalCryptoHashAlgorithmSpecifies the request's signature hash algorithm.
ExternalCryptoKeyIDThe ID of the pre-shared key used for DC request authentication.
ExternalCryptoKeySecretThe pre-shared key used for DC request authentication.
ExternalCryptoMethodSpecifies the asynchronous signing method.
ExternalCryptoModeSpecifies the external cryptography mode.
ExternalCryptoPublicKeyAlgorithmProvide public key algorithm here if the certificate is not available on the pre-signing stage.
InputContains the signing request to process.
InputEncodingSpecifies request encoding.
KeyIdSpecifies the KeyID of the pre-shared authentication key.
KeySecretThe pre-shared authentication key.
OutputContains the output of the request processing.
OutputEncodingSpecifies response encoding.
ProfileSpecifies a pre-defined profile to apply when creating the signature.
SigningCertificateSpecifies the signing certificate.
StorageIdSpecifies the signing certificate residing in an alternative location.

Method List


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

ConfigSets or retrieves a configuration setting.
ProcessRequestProcesses the request.

Event List


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

CustomParametersReceivedPasses custom request parameters to the application.
ErrorReports information about errors during request processing or signing.
ExternalSignHandles remote or external signing initiated by the SignExternal method or other source.
KeySecretNeededRequests the key secret from the application.
NotificationThis event notifies the application about an underlying control flow event.
ParameterReceivedPasses a standard request parameter to the user code.
PasswordNeededRequests a password from the application.
SelectCertRequests certificate selection criteria from the application.
SignRequestThis event signifies the processing of an atomic signing request.
SignRequestCompletedThis event signifies completion of the processing of an atomic signing request.

Configuration Settings


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

DataURL(obsolete) The DataURL parameter to pass to the signer.
GoURL(obsolete) The GoURL parameter to pass to the signer.
RequireDefinedSignCert(obsolete) The RequireDefinedSignCert parameter to pass to the signer.
SchemeParamsThe algorithm scheme parameters to employ.
SessionID(obsolete) The SessionID parameter to pass to the signer.
TokenNameThe TokenName parameter to pass to the signer.
TokensLibraries(obsolete) The TokensLibraries parameter to pass to the signer.
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 class (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 classes 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 Node.js Edition - Version 20.0 [Build 8165]