The MyPDFSigner core package provides a command line tool (CLI) to sign PDF documents using tokens stored in PKCS#11 and PKCS#12 certificate stores. The tool supports time stamping (RFC 3161) and visible signatures, including the incorporation of "watermark" images, PAdES LTV, PAdES B-B and B-T, encryption and signature verification.

If installing through native packages:

On Windows you need to install as Administrator (right click on the installer file and select "Run as Administrator").

If installing through package managers:

The command line tool mypdfsigner will be automatically available from a terminal if installing with a package manager or with native Linux packages. The native package for Mac OS X installs mypdfsigner to /Applications/MyPDFSigner.app/Contents/MacOS/ (you can add this path to the /etc/paths file if you wish) and in Windows to use MyPDFSigner.exe from the command line you need to add "C:\Program Files\MyPDFSigner" to your PATH (or cd into that directory).

Run mypdfsigner with -h to get the usage instructions which should be clear to understand. The behavior is the same in all platforms.

[support@kryptokoder ~]$ mypdfsigner -h
MyPDFSigner v3.1.5, (c) 2009-2021 KryptoKoder LLC
Usage:
mypdfsigner -i input.pdf -o output.pdf -p "password" -l "location" -r "reason" -v <visible> -c <certify> -q <timestamp> -t "title" -a "author" -s "subject" -k "keywords" -z mypdfsigner.conf

Only -i is required. If -o is missing the output file is the same as the input with "-signed" appended.
If -i and -o are directories all the PDF files in the input directory are signed and placed in the output directory, if not there yet.
If -z is missing the configuration file "/usr/local/mypdfsigner/mypdfsigner.conf" is used instead.
The password is the open document password, needed if the signed document is to be encrypted.

The configuration file can store an encrypted password for the PKCS#12 key store. The password can be encrypted from the command line with -e "password".

kryptokoder:~ support$ /Applications/MyPDFSigner.app/Contents/MacOS/mypdfsigner -h
MyPDFSigner v2.7.4, (c) 2009-2017 KryptoKoder LLC
Usage:
mypdfsigner -i input.pdf -o output.pdf -p "password" -l "location" -r "reason" -v <visible> -c <certify> -q <timestamp> -t "title" -a "author" -s "subject" -k "keywords" -z mypdfsigner.conf

Only -i is required. If -o is missing the output file is the same as the input with "-signed" appended.
If -i and -o are directories all the PDF files in the input directory are signed and placed in the output directory, if not there yet.
If -z is missing the configuration file "/Applications/MyPDFSigner.app/Contents/Home/mypdfsigner.conf" is used instead.
The password is the open document password, needed if the signed document is to be encrypted.

The configuration file can store an encrypted password for the PKCS#12 key store. The password can be encrypted from the command line with -e "password".

C:\Program Files\MyPDFSigner>MyPDFSigner.exe -h
MyPDFSigner v3.1.5, (c) 2009-2021 KryptoKoder LLC
Usage:
mypdfsigner -i input.pdf -o output.pdf -p "password" -l "location" -r "reason" -v <visible> -c <certify> -q <timestamp> -t "title" -a "author" -s "subject" -k "keywords" -z mypdfsigner.conf

Only -i is required. If -o is missing the output file is the same as the input with "-signed" appended.
If -i and -o are directories all the PDF files in the input directory are signed and placed in the output directory, if not there yet.
If -z is missing the configuration file "C:\Program Files\MyPDFSigner\mypdfsigner.conf" is used instead.
The password is the open document password, needed if the signed document is to be encrypted.

The configuration file can store an encrypted password for the PKCS#12 key store. The password can be encrypted from the command line with -e "password".

Note that the -i and -o arguments can be either a file or a directory. In the latter case all the PDF files in the input directory are signed and placed in the output directory.

The CLI needs a configuration file to run and can accept one from the command line (using the -z switch), or read it from the installation directory (if present), or use the configuration file present in the user home directory (if the CLI is being run by an user that has previously configured one) as long as it is named .mypdfsigner (note: dot mypdfsigner).

Note that the installation directory where you should place the mypdfsigner.conf file, if not using the -z switch, is:

Alternatively you can place a .mypdfsigner (dot mypdfsigner) file, if not using the -z switch, in:

Test the CLI in Linux:

[support@kryptokoder ~]$ mypdfsigner -i /usr/local/mypdfsigner/tests/example.pdf -o /tmp/example-signed.pdf -z /usr/local/mypdfsigner/tests/mypdfsigner.conf -v -c -q

Check /tmp/example-signed.pdf with a viewer (like Adobe Reader) that can display the digital signature. Note that viewers like Evince or Preview cannot yet display the digital signature, and the warning one sees with Adobe Reader about lack of certificate trust is to be expected (see Evaluation KeyStore).

Similarly on Mac OS X:

kryptokoder:~ support$ /Applications/MyPDFSigner.app/Contents/MacOS/mypdfsigner -i /Applications/MyPDFSigner.app/Contents/Home/tests/example.pdf -o /tmp/example-signed.pdf -z /Applications/MyPDFSigner.app/Contents/Home/tests/mypdfsigner.conf -v -c -q

To run the example in Windows add "C:\Program Files\MyPDFSigner" to the environment PATH variable. Then:

C:\> MyPDFSigner.exe -i "C:\Program Files\MyPDFSigner\tests\example.pdf" -o C:\Users\Username\Downloads\example-signed.pdf -z "C:\Program Files\MyPDFSigner\tests\mypdfsigner.conf" -v -c -q

You can also quickly play with MyPDFSigner in a Docker container by running the kryptokoder/mypdfsigner:latest image as shown below. Note that the example mounts a host directory as a data volume where the signed document is placed.

PS C:\> dir .\docker-demo\
PS C:\> docker run -v C:\docker-demo:/tmp -it kryptokoder/mypdfsigner:latest /bin/bash
root@69b8e0e5356c:/# mypdfsigner
MyPDFSigner v3.1.5, (c) 2009-2020 KryptoKoder LLC
Usage:
mypdfsigner -i input.pdf -o output.pdf -p "password" -l "location" -r "reason" -v  -c  -q  -t "title" -a "author" -s "subject" -k "keywords" -z mypdfsigner.conf

Only -i is required. If -o is missing the output file is the same as the input with "-signed" appended.
If -i and -o are directories all the PDF files in the input directory are signed and placed in the output directory, if not there yet.
If -z is missing the configuration file "/usr/local/mypdfsigner/mypdfsigner.conf" is used instead.
The password is the open document password, needed if the signed document is to be encrypted.

The configuration file can store an encrypted password for the PKCS#12 key store. The password can be encrypted from the command line with -e "password".
root@69b8e0e5356c:/# mypdfsigner -i /usr/local/mypdfsigner/tests/example.pdf -o /tmp/example-signed.pdf -z /usr/local/mypdfsigner/tests/mypdfsigner.conf -v -q
0#Document signed: input[/usr/local/mypdfsigner/tests/example.pdf] output[/tmp/example-signed.pdf]
root@69b8e0e5356c:/# ls -l /tmp/
total 193
-rwxr-xr-x 1 root root 196769 Feb 16 02:03 example-signed.pdf
root@69b8e0e5356c:/# mypdfsigner verify -i /tmp/example-signed.pdf
0#Document signature verified [Signer: MyPDFSigner Test]
root@69b8e0e5356c:/# exit
exit
PS C:\> dir .\docker-demo\


    Directory: C:\docker-demo


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         15-Feb-21   6:03 PM         196769 example-signed.pdf


PS C:\>

MyPDFSigner supports certificates stored in PKCS#12 files or PKCS#11 Security devices (an USB token or a smart card or a cloud HSM). Most of the entries in the respective configuration files are independent of the key store used with the exception of a few key store specific entries. The certstore is the entry used to select one of the two key stores and can take one of two values, PKCS12 KEYSTORE FILE or PKCS11 SECURITY DEVICE.

PKCS#12 KeyStore File
Below is an example of a configuration file for a PKCS#12 key store:

#MyPDFSigner test configuration file
certstore=PKCS12 KEYSTORE FILE
certfile=/Applications/MyPDFSigner.app/Contents/Home/tests/mypdfsigner-test.p12
certpasswd=47cabdb7b2b2dcc416a21cd0c4b6903e
subfilter=ETSI.CAdES.detached
sigrect=[-170 -80 -40 -40]
sigimage=/Applications/MyPDFSigner.app/Contents/Home/tests/signature.png
tsaurl=http://adobe-timestamp.geotrust.com/tsa

The two entries specific to the PKCS#12 key store are shown below:

# pkcs12 specific parameters
certpasswd=<encrypted password>
certfile=/path/to/keystore/file.p12

The password for the PKCS#12 key store can be encrypted from the command line using the mypdfsigner command with the -e switch:

$ mypdfsigner -e password

PKCS#11 Security Device
Below is an example of a configuration file for a PKCS#11 security device:

#MyPDFSigner configuration file
certstore=PKCS11 SECURITY DEVICE
signerpem=C\:\\Users\\KryptoKoder\\certificates\\signer.pem
capem=C\:\\Users\\KryptoKoder\\certificates\\globalsign-ca.pem
engine=C\:\\Program Files\\MyPDFSigner\\pkcs11.dll
p11url=pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;id=%68%83%68%57%23%be%8e%6e;type=private
pin=40c9bac5516520bdfca4ae639207639a
library=C\:\\Windows\\System32\\eTPKCS11.dll
sigimage=C\:\\Program Files\\MyPDFSigner\\tests\\signature.png
tsaurl=http\://adobe-timestamp.geotrust.com/tsa
sigrect=[-170 -80 -40 -40]
subfilter=ETSI.CAdES.detached
cachedir=C\:\\Temp
sigtext=Signed by %N\nLocation\: %L\nReason\: %R\nDate\: %C
sigdateformat=%c

The six entries specific to the PKCS#11 key store are shown below:

# pkcs11 specific parameters
signerpem=/path/to/signer/certificate.pem
capem=/path/to/ca/chain.pem
engine=/path/to/pkcs11-engine
p11url=<private key URL>
pin=<encrypted PIN>
library=/path/to/pkcs11-module

The library (driver) name is the module indicated in the documentation of your token provider and is the same used to configure Firefox or Thunderbird to use your token. This is the driver needed to interface with your token. Very often, the library has the "word" pkcs11 as part of the name and the extension .dll (Windows), or .so (Linux) or .dylib (Mac OS X).

The signerpem is the path to a file with your certificate in PEM format. This is the certificate associated with your token private key. You can use the p11tool command (see below) to extract the certificate from the token into a file.

The capem is the path to a file containing the certificates of your chain of trust from the Root CA certificate down to the certificate of the authority that issued your own certificate. The certificates should be in PEM format again. In general the certificates of the chain of trust are not embedded in the token but are instead provided with the software that came with your token. You can also get the certificates from the entity that provided your token. In some cases it is possible to extract the chain from the token if it happens to be embedded. For that we can use the p11tool command again.

The engine is the path to the PKCS#11 engine, the module that allows OpenSSL to interface with your token through its own PKCS#11 driver (OpenSSL ↔ Engine ↔ Driver ↔ Token). In Linux it is generally in /usr/lib/engines/engine_pkcs11.so or /usr/lib64/openssl/engines/pkcs11.so, and in Mac OS X the predefined location is /usr/local/opt/engine_pkcs11/lib/engines/engine_pkcs11.so. For Windows a pkcs11.dll engine file is provided in the installation directory.

The p11url is the URL of the token private key. You can use the p11tool command (see below) to get it.

For an example that uses a PKCS#11 library backed by a cloud HSM see the Google Cloud KMS section.

The P11Tool
The p11tool command is part of the GnuTLS package. In Linux you can get it from your distro. For instance, for Ubuntu:

kryptokoder@4550a76a539b:/# sudo apt install gnutls-bin

In Mac OS X you can use brew to install gnutls. You also need to install opensc and engine_pkcs11. This applies both Mac OS X and Linux, although the proper command for Linux depends on your distro (see below).

For Windows you can download the package from gnutls.org. If the link is broken, a copy of the package is provided here.

The example below shows how to get the private key URL from your token. The command needs the --provider argument, which is the path to the PKCS#11 module provided by your token provider.

C:\gnutls-MinGW64.DLLs-3.6.13\win64-build\bin>p11tool.exe --provider C:\Windows\System32\eTPKCS11.dll --list-keys --login
Token 'SafeNet eToken 5110' with URL 'pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110' requires user PIN
Enter PIN:
Object 0:
        URL: pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;id=%f8%76%7a%bb%7f%f9%d5%b1;type=private
        Type: Private key (RSA-2048)
        Label:
        Flags: CKA_WRAP/UNWRAP; CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE;
        ID: f8:76:7a:bb:7f:f9:d5:b1

Object 1:
        URL: pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;id=%68%83%68%57%23%be%8e%6e;type=private
        Type: Private key (RSA-2048)
        Label:
        Flags: CKA_WRAP/UNWRAP; CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE;
        ID: 68:83:68:57:23:be:8e:6e
    

In the example above we see two private keys. To find out each one to use again the p11tool command to get the certificates:

C:\gnutls-MinGW64.DLLs-3.6.13\win64-build\bin>p11tool.exe --provider C:\Windows\System32\eTPKCS11.dll --list-certs --login
Token 'SafeNet eToken 5110' with URL 'pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110' requires user PIN
Enter PIN:
Object 0:
        URL: pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;id=%f8%76%7a%bb%7f%f9%d5%b1;object=te-0f2e1de4-fc8a-467b-8829-069b7bf49bc5;type=cert
        Type: X.509 Certificate (RSA-2048)
        Expires: 03/11/20 07:18:40
        Label: te-0f2e1de4-fc8a-467b-8829-069b7bf49bc5
        ID: f8:76:7a:bb:7f:f9:d5:b1

Object 1:
        URL: pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;type=cert
        Type: X.509 Certificate
        Label:
        Flags: CKA_CERTIFICATE_CATEGORY=CA;
        ID:

Object 2:
        URL: pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;type=cert
        Type: X.509 Certificate
        Label:
        Flags: CKA_CERTIFICATE_CATEGORY=CA;
        ID:

Object 3:
        URL: pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;type=cert
        Type: X.509 Certificate
        Label:
        Flags: CKA_CERTIFICATE_CATEGORY=CA;
        ID:

Object 4:
        URL: pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;id=%68%83%68%57%23%be%8e%6e;object=te-46c144a3-e622-4f83-b8c7-c5611826e10a;type=cert
        Type: X.509 Certificate (RSA-2048)
        Expires: 04/13/21 13:18:17
        Label: te-46c144a3-e622-4f83-b8c7-c5611826e10a
        ID: 68:83:68:57:23:be:8e:6e

We can see above that the certificates have different expiration date and this may be enough to decide which to use. Since a file with the certificate is needed as the signerpem entry, we can use the p11tool again to extract it:

C:\gnutls-MinGW64.DLLs-3.6.13\win64-build\bin>p11tool.exe --provider C:\Windows\System32\eTPKCS11.dll --export pkcs11:model=eToken;manufacturer=SafeNet%2c%20Inc.;serial=02910c28;token=SafeNet%20eToken%205110;id=%68%83%68%57%23%be%8e%6e;object=te-46c144a3-e622-4f83-b8c7-c5611826e10a;type=cert --outfile=C:\temp\signer.pem

The above example, with the argument --export extracted the certificate identified by the given URL to the file C:\temp\signer.pem. You can look at the contents of the certificate with OpenSSL:

$ openssl.exe x509 -in /cygdrive/c/temp/signer.pem -text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            1c:71:50:7f:bf:4c:87:ff:5a:da:0f:a0
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C = BE, O = GlobalSign nv-sa, CN = GlobalSign CA 2 for AATL
        Validity
            Not Before: Mar 13 20:18:17 2020 GMT
            Not After : Apr 13 20:18:17 2021 GMT
................................................

You can also try the argument --export-chain to extract the certificate chain but that will only work if the chain is embedded in the token, which is not common. In that case you need to build the capem entry file manually from the certificates provided by your CA. If the certificates are in DER format you can use OpenSSL to convert them to PEM format.

The PKCS#11 Engine
In Linux the engine_pkcs11 module has different package names in different distros. For instance, for Ubuntu:

kryptokoder@4550a76a539b:/# sudo apt install libengine-pkcs11-openssl

In this case the module gets installed in /usr/lib/x86_64-linux-gnu/engines-1.1/pkcs11.so. The engine entry would then be:

engine=/usr/lib/x86_64-linux-gnu/engines-1.1/pkcs11.so

In Mac OS X you can use brew to install it. For Windows a pkcs11.dll module is provided in the installation directory.

If you do not have a TSA server available try one of the public available ones. A search should provide you a few free ones.

Time Stamping
A TSA (Time Stamp Authority) HTTP(S) server can be configured in this section (account and password are optional, as is policy OID). At the moment MyPDFSigner only supports the HTTP(S) POST TSA protocol. If using HTTPS, a extra entry, tsacert may be needed.

# time stamping parameters
tsaurl=http://adobe-timestamp.geotrust.com/tsa
# tsauser and tsapasswd if required by you TSA provider
tsauser=tsausername
tsapasswd=tsauserpassword
# if using HTTPS and certificate trust not established
tsacert=/path/to/CAcert.pem
# in general not needed
tsapolicyoid=1.2.3.4.5.6789.0.1.2
tsaalgo=sha256

To establish a connection to a HTTPS Time Stamping server, the CA that issued the certificate of the server needs to be trusted. If the CA certificate is already present in the ca-bundle.crt file (usually in the /etc/ssl/certs/ directory) then the trust is already established and no further steps are needed.

If trust has not been established then one needs to import the certificate of the CA that issued the time stamping server certificate. The certificate can be appended to the ca-bundle.crt file, or can be placed into its own file, whose path then needs to be used as the tsacert entry in the configuration file. In either case, the certificate needs to be converted to the PEM format.

You can test that the certificate is correct and that you can establish a connection to the server by using the command curl:

$ curl -v --cacert /path/to/CAcert.pem https://tsa.example.com

Visible Signatures
MyPDFSigner supports visible signatures and allows for some customization (image, size, position and page). A signature is made visible by setting TRUE the "visible" argument of the "sign" function (or by passing -v when using the command line).

The visible signature is placed by default on the first page of the document. To place it in a different page add the entry sigpage=page to the configuration file. The "page" value is a positive or negative integer; if negative it means the pages are counted from the end. For instance, to place the signature on the last page the entry can just be sigpage=-1.

Before explaining how signature customization is done one needs to know about PDF size units, also known as points. Point units are based on a "72 units per inch" scale. Hence letter size (8.5 by 11 inches) corresponds to 612 x 792 points, and A4 (210 by 297 mm) corresponds to 595 x 842 points. A visible signature position is specified by an array of four values corresponding to the "lx" (left x), "by" (bottom y), "rx" (right x) and "ty" (top y) coordinates of the sides of the signature rectangle. MyPDFSigner can accept both positive and negative coordinates, with negative coordinates being mesured from the right and top edges of the page (positive units are measured from the lower left corner of the page). By default MyPDFSigner uses the rectangle [-170 -80 -40 -40]. A different signature rectangle can be specified in the configuration file by adding the entry sigrect=[lx by rx ty] with the new values. The text part of the visible signature consists of four lines: the cn (common name, obtained from the certificate), reason, location and date. The font size is adapted to the specified rectangle height. However the width of the rectangle needs to be manually tuned so that the text fits.

A visible signature can also incorporate an image if the sigimage entry is present in the configuration file. The image will be scaled to fit inside the signature rectangle. The suggested approach to select the right sized signature image is to start by choosing the right visible signature rectangle size (as explained above). Once that is known create a signature image with the same proportions (but high enough resolution so that it looks fine when printed). An example: if the rectangle is 130 (units) wide by 40 tall (like the default one) the size when printed will be 130/72 inches by 40/72 inches. Sign your name in a piece of paper inside a rectangle of such dimensions and scan it at, say, 300 dpi. This will create an image that is 130*300/72 (pixels) wide by 40*300/72 tall (or 542 by 167 pixels). An image with such resolution will scale nicely and the resulting graphics will have the right size. Images of different proportions can be used but since they will be scaled (and centered) to fit inside the rectangle there will be space around two of the sides of the image.

MyPDFSigner has some limitations regarding the type of images that can use. The image needs to be of RGB-Alpha PNG type. That is not a serious limitation since it is the default format used by Gimp when saving a color PNG file that includes a transparent layer. In case of doubt look at the image properties using Gimp.

An example of a signed and time stamped PDF document with a visible signature is available here. Note that it was signed with a self signed certificate so the warning one sees when opening in Adobe Reader is expected.

# visible signature parameters
# sigpage defaults to 1; sigimage needs to point to a PNG image
sigrect=[lx by rx ty]
sigpage=1
sigimage=/path/to/image.png

Signature Attributes
To avoid the repetitive task of entering attributes that are usually the same for every signed document, like the location attribute and the placement of visible signatures, one can define a signing profile. Besides the "Location", "Reason" and "Contact" attributes, a signing profile can also include the page and position for visible signatures, an optional "watermark" image, and a customizable text template. The page attribute can be a positive or negative value; a negative value means the pages are counted backwards from the last page. For instance a value of -1 (sigpage=-1 in the configuration file) places the signature on the last page. You can also set the page value to * and then the signature will be visible in all pages.

# general signature parameters
# to place signature on last page use value -1
sigpage=-1
sigloc=Location
sigreason=Evaluating MyPDFSigner
sigcontact=support@kryptokoder.com

The template consists of free text plus some placeholders that will be replaced by attributes at signing time. There are four placeholders: %N which will be replaced by the "CN" attribute in the certificate (if "CN" or "cn" is missing, then the following are tried in this order: "GN" plus "SN", "O", "OU", "emailAddress"); %L, which is optional and corresponds to the "Location"; %R, which is optional if a license key is present (otherwise becomes mandatory), and corresponds to the "Reason"; and %D, %T, %Z or %C which correspond to either the date (yyyy.MM.dd), or date plus time (yyyy.MM.dd HH:mm:ss), or date plus time plus time zone (yyyy.MM.dd HH:mm:ss ZHH'mm') or a custom date and time. The custom date can be chosen using the C language date formatting rules. Note that except for the %Z placeholder, all the other date and time placeholders require a valid license.

# visible signature parameters
# the sigtext template below is enforced if a valid license is not present
sigtext=Signed by %N\nReason\: %R\nLocation\: %L\nDate\: %Z
sigdateformat=%c

The visible signature text may use glyphs that are not present in the Helvetica default font. In that case the font will be replaced by Arial assuming the font file is present in the local computer in the default location. If that is not the case, or a different font is preferred, the sigfont entry can be used to specify the font file to use.

# visible signature parameters
sigfont=/path/to/fontfile.ttf

The signature rectangle is the rectangle in the page where the visible signature will be displayed. The rectangle consists of four values inside square brackets [], corresponding to the left, bottom, right and top coordinates of the rectangle. The values are units in a "72 units per inch" scale with the origin being the lower left corner of the page. In these units, a letter sized page (8.5 by 11 inches) is 612 x 792 units, and a A4 page (210 x 297 mm) corresponds to 595 x 842 units. The rectangle values can be either positive or negative. If negative then they are measured from the right and top sides of the page; if positive they are measured from the left and bottom sides of the page. For instance, to place a 100 x 50 (W x H) rectangle in the lower left corner, 20 units from the edges one would use the values [20 20 120 70]. To place the rectangle in the upper right corner, 20 units from the page edges, one could use the values [-120 -70 -20 -20]. Note that for a A4 page this is equivalent to [475 872 575 822].

# visible signature parameters
sigrect=[lx by rx ty]

A visible signature will also incorporate an image if one was defined in the "Signature Profile". The image will be scaled to fit inside the signature rectangle. Ideally the image will have a transparent background. The suggested approach to select the right sized signature image is to start by choosing the right visible signature rectangle size so that the filled text template fits nicely. Once that is known create a signature image with the same proportions (but high enough resolution so that it looks fine when printed). An example: if the rectangle is 130 (units) wide by 40 tall (like the default one) the size when printed will be 130/72 inches by 40/72 inches. Sign your name in a piece of paper inside a rectangle of such dimensions and scan it at, say, 300 dpi. This will create an image that is 130*300/72 (pixels) wide by 40*300/72 tall (or 542 by 167 pixels). An image with such resolution will scale nicely and the resulting graphics will have the right size. Images of different proportions can be used but since they will be scaled (and centered) to fit inside the rectangle there will be space around two of the sides of the image. For testing purposes there is a signature.png file in the tests directory of the installation. This file can be used with the default (130 x 40) rectangle.

# visible signature parameters
sigimage=/path/to/image.png

While the size of the visible signature rectangle needs to be set manually in the profile (unless you want to use the default 130 x 40 rectangle), its page and position can be set with the mouse: when the original document is selected, checking the "visible" checkbox opens up a dialog with a preview of the page and visible signature rectangle. The position of the signature can be changed by grabbing and dragging the rectangle. Note that this dialog has "Save" and "OK" buttons. The first one saves the changes permanently to the configuration file while the latter only saves for the session.

Encryption
Encryption of signed PDFs can be enabled if a non empty password is provided (either in the command line, with the -p switch, or using the API - see below). The password provide is the User (or Open Document) password. An Owner (or Permissions) password can also be provided in the configuration file, together with the permissions, using the following entries:

# pdf encryption parameters
# owner (permissions) password
encpermpwd=ownerpassword
# print permission: 0 = full, 1 = low, 2 = none
encpermprint=2
# change permission: 0 = all, 1 = annotate, 2 = form, 3 = assembly, 4 = none
encpermchange=4
# copy permission: 0 = no, 1 = yes
encpermcopy=0
# accessbility permission: 0 = no, 1 = yes
encpermaccess=0
# metadata encryption: 0 = no, 1 = yes
encmetadata=1

Note: support for certified signatures is not implemented yet if encryption is used.

Hash Algorithm
By default MyPDFSigner uses SHA256 but that can be replaced by SHA1, SHA224, SHA384 or SHA512 if the entry hashalgo is present in the configuration file (example: hashalgo=sha1). Although SHA256 is more secure that SHA1 it may also be noticeably slower if the entropy gathering engine of your machine is slow (this is in general not observed but it may happen). You can check whether that is the case by experimenting signing with SHA1.

# hash algorithm parameters
# possible values: sha1, sha224, sha256 (default), sha384 and sha512
hashalgo=sha256

Subfilter
By default MyPDFSigner uses the adbe.pkcs7.detached subfilter but that can be changed using the entry subfilter in the configuration file. The possible values are adbe.pkcs7.sha1, adbe.x509.rsa.sha1, adbe.pkcs7.detached (the default) and ETSI.CAdES.detached. Note that the subfilter value adbe.pkcs7.sha1 requires hashalgo=sha1, and the subfilter value adbe.x509.rsa.sha1, not withstanding the name, does allow for hash algorithms that are not SHA1 (so any of the SHA algorithms is allowed), but MyPDFSigner does not support the creation yet of signatures compatible with this subfilter (but the PDF can be prepared for signature using this subfilter, and the signature can then be created by a third party application). The subfilter value ETSI.CAdES.detached should be used to create signed documents compliant with PAdES compliance level B-B and B-T (requires that Time Stamping is enabled).

# subfilter parameters
# possible values: adbe.pkcs7.sha1 (requires hashalgo=sha1), adbe.x509.rsa.sha1, adbe.pkcs7.detached (the default) and ETSI.CAdES.detached 
subfilter=adbe.pkcs7.detached

Certification
The first signature of a document can be certified, and configured to allow or disallow further changes. This can be configured with the mdplevel entry which can take the values 1, 2 or 3. The default value is 2 which allows for further signatures. A value of 1 means that the document is final and no further signatures are allowed. MDP here stands for modification detection prevention.

# certification parameters
# possible values: 1, 2 or 3
mdplevel=2

Application Name
If using a license you can tag the signed PDFs with your own application name. This is the name that appears in the "Advanced Signature Properties" window of Adobe Reader (click visible signature box → Signature Properties.. → Advanced Properties...). To that end add the entry appname to your configuration file (example: appname=ACME Super Signer). More information is available in the license page.

# name of signing application (this requires a license)
appname=ACME Super Signer

PAdES B-B/T and eIDAS
PAdES signature level B-B and B-T can be performed if the subfilter entry is set to ETSI.CAdES.detached. The level B-T is performed if Time Stamping is enabled, B-B is performed otherwise.

# perform PAdES B-B or B-T
subfilter=ETSI.CAdES.detached

Note: many European governments provide online PAdES validation services; an example is http://dss.agid.gov.it/validation.

An eIDAS signature is a PAdES signature performed with an eIDAS compliant certificate.

Byte Range
During the process of signing a PDF a default placeholder for the signature is created inside the document. If this placeholder is not large enough to hold the signature, and this generally happens if the certificate chain is long, MyPDFSigner will emit an error similar to:

-1#Byte range underestimated... add extrarange=5300 to config file (add to existing value). 

This means that placeholder is too small and a larger one is needed. To help MyPDFSigner create a larger placeholder add the following entry to the configuration file and rerun the signing process.

# tell mypdfsigner to expand the default placeholder by this amount
extrarange=5300

Other Parameters
There are a few other parameters that may be useful when experimenting with signature placement and design, or when the application does not work (like when configuring the certificate fails to work), or when you are behind a proxy.

# other optional parameters, all of them with a default value
# defaults to keys directory of installation if not present 
keyfile=/path/to/license.key
# use when requesting support, default is off
debug=off
# defaults to mypdfsigner.log in local user directory if not present; requires debug=on
logfile=/path/to/mypdfsigner.log
# if you are behind a proxy you will need to set these so that internet requests, like retrieval of OCSP, work properly
proxyprotocol=http
proxyhost=proxy.example.com
proxyport=1080

MyPDFSigner LTV enables signed PDFs by default. If that is not possible, either because the OCSP status or the CRL cannot be retrieved, or are invalid, MYPDFSigner proceeds to sign without LTV. If you desire LTV to be enforced then you can set the enforceltv configuration entry to on. This will result, in the cases where LTV cannot be enabled, in an error when signing that your application can catch and handle as needed.

# fail signing if LTV not possible; default is off
enforceltv=on

MyPDFSigner can also be used to add PAdES LTV to already signed PDFs.

[support@kryptokoder ~]$ mypdfsigner addltv -i input-signed.pdf -o output-ltved.pdf -z mypdfsigner.conf

This feature is fully functional without a license but the OCSP and CRL data will only be cached for 30 seconds and 5 minutes respectively. With a license the caching times will be extended to 1 hour and 24 hours respectively.

MyPDFSigner can be used to verify the validity of a signed PDF (validation of the certificates is not performed yet).

[support@kryptokoder ~]$ mypdfsigner verify -i input-signed.pdf -z mypdfsigner.conf

This feature is fully functional without a license but the signed documents are restricted to five pages maximum. With a license the restriction is lifted.

MyPDFSigner ships with a pre-configured test PKCS#12 KeyStore in the tests directory of the installation: mypdfsigner-test.p12. The password for the KeyStore is already encrypted and saved in the test configuration file, mypdfsigner.conf, in the same directory. The evaluation KeyStores uses a self-signed certificate so the warnings about lack of trust are to be expected.

If you are unable to configure the certificate or run into other problems please set debug=on in the configuration file and run the application to reproduce the problem. Then contact KryptoKoder and include the log file (usually mypdfsigner.log in your home directory) in your submission.

If you used package managers to install, then: