DCAuth Class

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

class 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 process_request 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 storage_id 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 process_request method:
  

        DCAuth.ProcessRequest;
      

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

• If the process_request call has succeeded, grab the async response from the output property:
  

        Result = DCAuth.Output;