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 automatically embeds OCSP status in the signed PDF. This, when available, is enough to make the
signed PDF be LTV (Long Term Validation) enabled. In situations where an OCSP status is not available, either
because the OCSP end point is not present in the signer certificate or for any other reason (like being unable
to reach the OCSP server), there is the option of embedding a CRL file, if available, in the signed PDF. By default MyPDFSigner
does not embed the CRL file but that can be forced by setting the embedcrl configuration entry to
on (or true).
# force embedding CRL if OCSP not available; default is off embedcrl=on
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: