xmlsecurity/README.md

   1 # Document Signing
   2
   3 ## Introduction
   4
   5 This code provides dialogs, and infrastructure wrapping `libxmlsec` and
   6 `gpgme` that implements document signing.
   7
   8 For signing a document, a personal key pair is used, which consists of a
   9 private key and a public key, which is added to the document in addition
  10 to the digital signature of the document, when signing it.
  11
  12 The document signing can be done both for the source ODF/OOXML files and
  13 the exported PDF files. It is also possible to sign existing PDF files.
  14
  15 ## Module Contents
  16
  17  * `doc`: OpenDocument workflow legacy information with some illustrations to have an idea of the workflow, for starters check `doc/OpenDocumentSignatures-Workflow.odt`.
  18  * `inc`: Headers to a subset of source files inside the module, parts like `source/framework` have headers inside the folder.
  19  * `qa`: Unit tests for signing and shell scripts for certificates creation for testing.
  20  * `test_docs`: Documents & certificates used for testing.
  21  * `source`: More on that below.
  22  * `uiconfig`: User interface configuration for different dialogs, it is recommended to navigate from relevant source file to the .ui file linked in the class which will be under `uiconfig/ui`.
  23  * `util`: UNO passive registration config for GPG/ NSS.
  24
  25 ## Source Primary Contents
  26
  27  * `component`: Main implementation of `DocumentDigitalSignatures` where the interaction with security environment and certificates occur.
  28  * `dialogs`: Certificate & Signatures management dialogs.
  29    * `certificatechooser`: Dialog that allows you to find and choose certificates or signatures for encryption.
  30    * `certificateviewer`: More detailed information about each certificate.
  31    * `digitalsignaturesdialog`: Main window for signatures of the documents and the start point of signing document.
  32  * `framework`: Various elements for verifying signatures and running security engine.
  33  * `gpg`: The implementation of encrypting with GPG and security environment initialization.
  34  * `helper`: Some helper classes that include signatures manager and the helpers for PDF signing, UriBinding, and XML signatures. It also include helper tools for XSecurityEnvironment.
  35  * `xmlsec`: XML, NSS, MSCrypt encryption/ signing tools, more on the low-level side of actual implementation of algorithms.
  36
  37
  38 ## PDF Testing
  39
  40 To test the signed PDFs, one can use the `pdfverify` in this way:
  41
  42     ./bin/run pdfverify $PWD/xmlsecurity/qa/unit/pdfsigning/data/2good.pdf
  43
  44 The file parameter should be an absolute path.
  45
  46 This is the output of `pdfverify` for `2good.pdf`:
  47
  48 ```
  49 verifying signatures
  50 found 2 signatures
  51 signature #0: digest match? 1
  52 signature #0: partial? 0
  53 signature #1: digest match? 1
  54 signature #1: partial? 0
  55 ```
  56
  57 ## References
  58 * [Adobe: Digital Signatures in a PDF](https://www.adobe.com/devnet-docs/etk_deprecated/tools/DigSig/Acrobat\_DigitalSignatures_in_PDF.pdf)
  59 * [Adobe: Acrobat DC Digital Signatures - Supported Standards](https://www.adobe.com/devnet-docs/acrobatetk/tools/DigSigDC/standards.html)