Signature Parameters

The "Signature" web service can be used to digitally sign documents.

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<operation xmlns="http://schema.webpdf.de/1.0/operation">
<signature>
  <add appendSignature="true"
        certificationLevel="noChanges"
        contact="Softvision Development GmbH"
        fieldName="Signature1"
        keyName=""
        keyPassword=""
        reason="sample"
        location="Fulda">
    <appearance page="1" identifier="" name="">
      <identifierElements
              showCommonName="true"
              showCountry="true"
              showDate="true"
              showLocal="true"
              showMail="true"
              showName="true"
              showOrganisationName="true"
              showOrganisationUnit="true"
              showSignedBy="true"
              showState="true"
      />
      <image position="center" opacity="50">
        <data>iVBOR...S7xAAAAABJRU5ErkJggg==</data>
      </imge>
      <position
              x="0"
              y="0"
              width="0"
              height="0"
              coordinates="user"
              metrics="mm"/>
    </appearance>
  </add>
</signature>
</operation>

{
"signature": {
  "add": {
    "appendSignature": true,
    "certificationLevel": "noChanges",
    "contact": "Softvision Development GmbH",
    "fieldName": "Signature1",
    "keyName": "",
    "keyPassword": "",
    "reason": "sample",
    "location": "Fulda",
    "appearance": {
      "page": 1,
      "identifier": "",
      "name": "",
      "identifierElements": {
        "showCommonName": true,
        "showCountry": true,
        "showDate": true,
        "showLocal": true,
        "showName": true,
        "showOrganisationName": true,
        "showOrganisationUnit": true,
        "showSignedBy": true,
        "showState": true
       },
      "image": {
        "position": "center",
        "opacity": 50,
        "data": {
          "value": "iVBOR...S7xAAAAABJRU5ErkJggg=="
         }
       },
      "position": {
        "x": 0,
        "y": 0,
        "width": 0,
        "height": 0,
        "coordinates": "user",
        "metrics": "mm"
       }
     }
   }
 }
}

 

 

add element

 

Used to add a new signature to the PDF document.

 

<add appendSignature="true"
    certificationLevel="noChanges"
    contact="Softvision Development GmbH

    fieldName="Signature1"
    keyName=""
    keyPassword=""
    reason="sample"
    location="Fulda">
    ...
</add>

"add": {
"appendSignature": true,
"certificationLevel": "noChanges",
"contact": "Softvision Development GmbH",
"fieldName": "Signature1",
"keyName": "",
"keyPassword": "",
"reason": "sample",
"location": "Fulda",
     ...
 }

 

appendSignature (default: true)

If the value was set to "true," then a signature will be appended if there is already another signature in the document. If the value was set to "false" and the document already contains a signature, then an exception will be thrown.

 

certificationLevel (default: "noChanges")

This parameter defines the level of the signature.

none = Sign, but do not certify, the document, i.e., additional signatures and changes will be allowed.

noChanges = Certify the document and do not allow any additional changes anymore.

formFillingAndSignatures = Certify the document, but allow for fields to be filled out.

formFillingAndSignaturesAndAnnotations = Certify the document, but allow for fields to be filled out and annotations to be added.

 

contact (default: "")

Specifies the name of the person signing the document.

 

fieldName (default: "Signature1")

Defines the name of the field (in the document) in which the signature will be saved. If a field name that is not unique is declared, then a unique name will be automatically created.

 

keyName (default: "")

Defines the name of the key (alias) that is to be used to sign the document. This option overwrites the server's configuration setting. Additional information can be found in the "Keystore" chapter.

 

keyPassword (default: "")

Used to define the password required in order to access the private key with "keyName." This option overwrites the server's configuration setting. Additional information can be found in the "Keystore" chapter.

 

reason (default: "")

Specifies the reason why the document is being signed.

 

location (default: "")

Specifies the location of the signature.

 

 

appearance element

 

Used to define the signature’s visual appearance.

 

<appearance page="1" identifier="" name="">
      ...
</appearance>
 

"appearance": {
  "page": 1,
  "identifier": "",
  "name": "",
       ...
 }

 

page (default: 1)

Defines the page on which the signature is to be displayed.

 

identifier (default: "" )

Text that should be displayed in the signature’s right-hand side text field. If a value is not specified, the field will display the name of the signatory and the name parts of the certificate (please refer to "<identifierElements>" further below).

 

name (default: "")

Name that will be displayed in the signature’s left-hand side area. If a value is not specified, the area will display the name of the signatory (name from the certificate).

 

 

identifierElements element

 

Used to define the elements that are part of the visual signature.

 

<identifierElements
        showCommonName="true"
        showCountry="true"
        showDate="true"
        showLocal="true"
        showMail="true"
        showName="true"
        showOrganisationName="true"
        showOrganisationUnit="true"
        showSignedBy="true"
        showState="true"/>      

"identifierElements": {
  "showCommonName": true,
  "showCountry": true,
  "showDate": true,
  "showLocal": true,
  "showName": true,
  "showOrganisationName": true,
  "showOrganisationUnit": true,
  "showSignedBy": true,
  "showState": true
},      

 

The following options can be used to show and hide the certificate’s name parts. Setting a value to "true" will show the corresponding part, while "false" will hide it.

 

showCommonName (default: true)

Displays or hides the certificate name (CN) of the certificate.

 

showCountry (default: true)

Displays or hides the (ISO valid) country code (C) of the country in which the certificate holder is located.

 

showDate (default: true)

Displays or hides the signature time.

 

showLocal (default: true)

Displays or hides the location/city (L) where the certificate holder is located.

 

showMail (default: true)

Displays or hides the email address (E) at which the certificate holder can be contacted.

 

showName (default: true)

Displays or hides the signature name.

(If this name has not been set, the certificate authority (CN) is displayed instead during activation.)

 

showOrganisationName (default: true)

Displays or hides the certificate holder's organization/company (O).

 

showOrganisationUnit (default: true)

Displays or hides the certificate owner's suborganization/department (OU).

 

showSignedBy (default: true)

Displays or hides the Certificate Authority (CN) of the certificate.

 

showState (default: true)

Displays or hides the state (S) in which the certificate holder is located.

 

image element

 

Used to define an image, for the visual signature, that will be drawn in the signature’s background. The image itself is passed with "<data>".

 

<image position="center" opacity="50">
  <data>iVBOR...S7xAAAAABJRU5ErkJggg==</data>
</image>

"image": {
    "position": "center",
    "opacity": 50,
    "data": {
      "value": "iVBOR...S7xAAAAABJRU5ErkJggg=="
    }
},

 

position (default: "center")

Position of image within signature field:

center = Centred

left = Left

right = Right

 

opacity (default: 50)

Opacity of image as a percentage value between 0 and 100.

 

 

data element

An image that will be placed in the field’s background. The data will be passed in Base64. In order to ensure that the image will have the best possible appearance, it should be transparent (e.g., PNG).

 

 

position element

 

Used to define the position of the visual signature.

 

<position
    x="0"
    y="0"
    width="0"
    height="0"
    coordinates="user"
    metrics="mm"/>

"position": {
  "x": 0,
  "y": 0,
  "width": 0,
  "height": 0,
  "coordinates": "user",
  "metrics": "mm"
}

 

x (default: 10 millimetres from the left margin)

X-axis position of field.

 

x (default: 10 millimetres from the bottom margin)

Y-axis position of field.

 

width (default: 80 - in millimetres)

The signature field’s width

 

height (default: 40 - in millimetres)

The signature field’s height

 

coordinates (default: "user")

Used to define the coordinate system and, accordingly, the origin for the position arguments.

user = User coordinate system (origin at top left)

pdf = PDF coordinate system (origin at bottom left)

 

metrics (default:"mm")

Unit for the X-axis/Y-axis position and signature field height and width arguments:

mm = Millimetres

px = Pixels