← FlexAPI Documentation / API Calls / CertifyDocument

CertifyDocument

The CertifyDocument method locks down a PDF document and adds a time reference to it, showing that the document existed in its signed form at a certain time. It does so by applying a covering signature to the document. It is often used when a PDF simply needs to be locked down and time-stamped, without going through a signing transaction.

On this page

Before you call

  • Do not send a Demo element. It is required on SubmitDocument only; sending it here is a schema error. CustInfo needs credentials only, with no Workgroup.
  • Send an unsigned PDF. The certifying signature must be the first digital signature on the document, so a PDF that already carries any digital signature will be rejected. Certify it before it goes anywhere else.
  • Choose SubsequentChanges deliberately. It defaults to NO_CHANGES. If a later step fills a form field or adds an annotation, use FORM_FILLING or FORM_FILLING_AND_ANNOTATIONS, or that step will invalidate the signature.
  • Replace your stored copy with the response. The returned Form is the certified PDF. Decode the Base64, check the byte count against Length, and store it as the document of record, not the original you sent.
  • Check StatusCode, not just the HTTP status. Data is returned only when StatusCode is 0.
  • Using DocumentURL? SIGNiX only downloads from approved sites, so contact SIGNiX before using a new download site. Omit Length and Data when you use it.

Signature policy

The type of signature applied is controlled by the signature policy, specified as the policy OID in the SignaturePolicyID element. The following policy is supported:

  • 1.3.6.1.4.1.6693.4.2.20 - SIGNiX Certifying time-stamp. SIGNiX inserts a new, hidden signature field into the document and signs it with a PDF Document Modification Prevention and Detection (DocMDP) signature.

The certificate on the signature belongs to the SIGNiX Signature Authority, and is issued under the Adobe AATL program, like other signer signatures. In the default configuration of Adobe Acrobat and Reader, it causes a blue ribbon mark to appear above the document.

DocMDP signatures limit the types of changes that can be made after signing. Specify the limitation you want in the SubsequentChanges element. The choices are NO_CHANGES, FORM_FILLING or FORM_FILLING_AND_ANNOTATIONS.

This type of signature must be the first digital signature on a document, so the document must not have any digital signatures on it when submitted.

Digital signatures made under this policy have the legal effect of a pure time stamp. SIGNiX only asserts (in the signature reason field) that the signature represents a time stamp, showing that the document existed in the signed form at the time of signing. Verification of the signature provides evidence that the document has not changed since signing, other than in the ways allowed by the SubsequentChanges setting.

Any assertions about the trustworthiness of other information in the document, including any text or images of signatures, and communication of any information on how to evaluate the trustworthiness of the content, are left to the customer.

CertifyDocument - Request XML

An annotated example of the request XML follows.

CertifyDocument - annotated request 
<?xml version="1.0" ?>
<CertifyDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">

  <CustInfo> <!-- Occurs once only -->

    <!-- Assigned by SIGNiX when the Client is set up. All case sensitive. -->
    <Sponsor>YOUR_SPONSOR</Sponsor>
    <Client>YOUR_CLIENT</Client>
    <UserId>YOUR_USER</UserId>
    <Pswd>YOUR_PASSWORD</Pswd>

  </CustInfo>

  <Data> <!-- Occurs once only -->

    <!-- Required. The signature policy to be used to sign the form. -->
    <SignaturePolicyID>1.3.6.1.4.1.6693.4.2.20</SignaturePolicyID>

    <!-- Optional. Case-sensitive. Defaults to NO_CHANGES. For policies that create a DocMDP
         signature, specifies which changes are still allowed after the signature is made:
         NO_CHANGES, FORM_FILLING or FORM_FILLING_AND_ANNOTATIONS. -->
    <SubsequentChanges>NO_CHANGES</SubsequentChanges>

    <!-- Describes the document to be signed. -->
    <Form>

      <!-- Optional, no default. Max length 50. A client-chosen identifier for this form. Appears in
           the audit trail record of the signing, and is returned in the response. -->
      <RefID>FormID-1</RefID>

      <!-- Max length 100. The title of the document. Appears in the audit trail entry for the
           signing. -->
      <Desc>Express Application #1</Desc>

      <!-- Max length 100. The format of the document. PDF (application/pdf) is the supported
           type. -->
      <MimeType>application/pdf</MimeType>

      <!-- Optional, defaults to blank. Owner password if the document has one. Omit for documents
           without an owner password. -->
      <FormPassword>YOUR_FORM_PASSWORD</FormPassword>

      <!-- Provide the document either as Base64 (Length and Data) or by DocumentURL. -->
      <Length>PDF_BYTE_LENGTH</Length> <!-- Length of the document to be signed, when decoded, in bytes -->
      <Data>BASE64_PDF</Data> <!-- The bytes of the entire document, encoded in Base64 -->

      <!-- Alternative: a URL SIGNiX uses to retrieve the document. Must begin with http:// or
           https://. SIGNiX will only download documents from approved sites, so contact SIGNiX
           before using a new download site. If present, omit Length and Data. -->
      <DocumentURL>https://www.example.com/form1.pdf</DocumentURL>

    </Form>

  </Data>

</CertifyDocumentRq>

CertifyDocument - Response XML

An annotated example of the response XML follows. See Status Codes on the main API page for the possible values and meanings of the StatusCode and StatusDesc elements.

CertifyDocument - annotated response 
<?xml version="1.0" ?>
<CertifyDocumentRs xmlns="urn:com:signix:schema:sdddc-1-1">

  <Status> <!-- Occurs once only -->
    <StatusCode>0</StatusCode> <!-- One of the numeric SC_* values -->
    <StatusDesc>success</StatusDesc> <!-- Human-readable version of StatusCode -->
  </Status>

  <Data> <!-- Occurs when Status.StatusCode is 0. Returns the signed document. -->

    <Form>

      <RefID>FormID-1</RefID> <!-- A client-chosen RefID, echoed from the request -->
      <Desc>Express Application #1</Desc> <!-- Document title, echoed from the request -->
      <MimeType>application/pdf</MimeType> <!-- The format of the document. Matches the MimeType from the request -->
      <Length>PDF_BYTE_LENGTH</Length> <!-- Length of the signed document, when decoded, in bytes -->
      <Data>BASE64_PDF</Data> <!-- The bytes of the entire signed document, encoded in Base64 -->

    </Form>

  </Data>

</CertifyDocumentRs>

Back to top

SIGNiX Products

Industries We Serve

Support

©2016 SIGNiX. All Rights Reserved.