Installing, Running & Uninstalling
Before running MyPDFSigner your system needs to meet one or two requirements: a) your system has java installed, and b) if using smart cards the application provided by your card provider is installed (this will install the drivers needed to interface with the card), and c) if using the PHP, Ruby or Python extensions (Linux only) your system needs to have OpenSSL installed (generally the default).
Note that if you just want to use the PHP, Ruby or Python extensions you still need to start with MyPDFSigner to build the configuration file, mypdfsigner.conf, to use as input to the extensions. However, for a quick test you can just install it and then skip the configuration below and instead use the test configuration provided.
The first requirement, having java installed is probably already met by your system. That is certainly the case for the Mac OS X. See Troubleshooting below for more information. The second requirement only needs to be met if using PKCS#11 smart cards.
If you would like to try MyPDFSigner and you do not have a certificate yet you can get one from Cacert. Install the certificate into the browser and back it up to a *.p12 file that you can use with MyPDFSigner. For testing purposes you can also use the test key store provided.
Installing
-- Windows: Run the MyPDFSigner-Install.exe installer (installs to "Program Files")
-- Mac OS X: Unzip and run the MyPDFSigner.mpkg installer (installs to /Applications)
-- Fedora: rpm -ihv mypdfsigner-1.3.3-1.i386.rpm (installs to /usr/local/)
-- Ubuntu: dpkg -i mypdfsigner_1.3.3-1_i386.deb (installs to /usr/local/)
On Windows you may need to install as Administrator (right click on the installer file and select "Run as Administrator").
Note: in Linux and Mac OS X the command line interface, mypdfsigner-cli, installs to /usr/local/bin. In Windows if you want to use MyPDFSigner-CLI from the command line you need to add "C:\Program Files\MyPDFSigner" to your PATH (or cd into that directory).
Running
-- Windows: Start > Programs > MyPDFSigner > MyPDFSigner
-- Mac OS X: Applications > MyPDFSigner
-- Linux: Applications > Office > MyPDFSigner or mypdfsigner (/usr/local/bin/mypdfsigner)
Configuration
Before running MyPDFSigner with a smart card make sure the card reader is plugged to the computer and that the card is inserted in the card reader! This "step" can be obviously skipped when using PKCS#12 files or, in Windows and Mac OS X, when using certificates in the Windows Certificate Store or the Apple Keychain Store that are not associated with private keys stored in a smart card.
The first time MyPDFSigner is run it needs to have a certificate configured. This is done by choosing a Certificate Store from the top drop down menu and then clicking the "Change" button. The interface that appears then depends on the Certificate Store chosen.
Note: the configuration is saved to a file named ".mypdfsigner" in your home directory:
-- Windows: C:\Documents and Settings\User Name
-- Mac OS X: /Users/username
-- Linux: /home/username
There are some situations where you need to manually edit this file.
Windows Certificate Store: On Windows, when using the Windows Certificate Store, the interface is very simple and consists of a drop down menu of the certificates registered in the system. Select one of them in the "Alias" drop down menu and click "Save".
Note: On Windows 64 bits you need to use Java 7 to properly use the Windows Certificate Store (Java 6 for 64 bits is missing some components necessary to access the Windows Certificate Store).
Apple Keychain Store: Similarly on Mac OS X, when using the Apple Keychain Store, the interface consists of a drop down menu of the certificates registered in the system. Select one of them in the "Alias" drop down menu and click "Save". Note that the Keychain used is the "System" Keychain.
You will be challenged for credentials the first time you try to access the Keychain. If the "Always Allow" button does not work, i.e. you are still challenged for credentials after using it, then you can directly add MyPDFSigner to the list of allowed applications. To do this open Keychain Access (Utilities > Keychain Access), select the private key you will use for signing, open it (double click), select the "Access Control" tab, and add MyPDFSigner to the list of "Always allow access by these applications".
PKCS#11 Security Device: Fill in the the first two fields: name and module. The name is a descriptive name for the card and can be anything. The module is the path of the library used to interface with your card (note that in Windows, if the library is placed in a standard location like Windows\system32, the path can be replaced just by the name of the library).
The module (library) name is indicated in the documentation of your card provider and is the same used to configure Firefox or Thunderbird to use your card. 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). If you really do not know what the library name for your card is check a site like FreeOTFE.
As an example, for the Portuguese Citizen Card the module name is:
-- Windows: C:\Windows\system32\pteidpkcs11.dll (or just pteidpkcs11.dll)
-- Mac OS X: /usr/local/lib/pteidpkcs11.dylib
-- Linux: /usr/local/lib/libpteidpkcs11.so
Note: MyPDFSigner also supports the OpenSC module, but the configuration is a bit more complicated and needs some extra steps. See the section below.
Once the module name is provided, the certificate alias drop down menu is loaded with the aliases values stored in your card. Select the one corresponding to your certificate for signing (click the "Display" button next to it to view its information) and click the "Save" button.
If the above step fails to work that may be due to the fact that the software that comes with your card does not provide a PIN Entry Dialog and instead expects the application (MyPDFSigner in this case) that interfaces with card to provide the PIN Entry Dialog. Add "pindialog=on" to the configuration file and try again to see if makes a difference.
Note that the aliases values are the values associated with the private keys in your card. Usually for every private key in the card there is an associated certificate but there are cases where that does not happen (the certificate in those cases is held by the authority that issued your card). On those cases the "Display" button will obviously fail to show the certificate. But the alias that was indicated by your card issuer authority as being the one to use for signing will always have the associated certificate in the card.
The certificate configuration has an "optional" certificate store. Whether it is optional or not really depends on your card. You can start by assuming that it is optional; then sign a PDF document and check whether the certification path is complete or not. If the path is not complete then you should configure the Certificates Store Path. The reason this step is usually necessary is due to the fact that most cards do not store all the certificates of the certification path in its chip. Instead, the missing certificates are provided as part of the application that came with the card (this is the approach suggested by the PKCS#11 standard). Signing a PDF document with a incomplete certification path is possible but unless you configure your PDF viewer to trust one of the intermediate certificates the signed document will always be flagged as having issues with its digital signature.
If you need to configure the Certificates Store Path look under the installation directory of your card application for a folder with the certificates (files that usually have the extensions .der, .cer or .pem). The path of that folder is the one that needs to be configured in the Certificate Configuration dialog of MyPDFSigner.
As an example, for the Portuguese Citizen Card the Certificates Store Path is:
-- Windows: C:\Program Files\Cartão de Cidadão\eidstore\certs
-- Mac OS X: /Applications/Cartao de Cidadao/Aplicacao Cartao de Cidadao.app/Contents/MacOS/eidstore/certs
-- Linux: /usr/local/bin/eidstore/certs
Note: under Mac OS X the path may be "under" and application "file", i.e., a folder that has the .app extension and looks like a file; use the terminal or "right click + Show Package Contents" to look inside.
PKCS#11 Security Device with OpenSC: The OpenSC project provides a module that works with many smart cards. If it works with your card then you can use it instead of the module provided by your card provider. This is relevant if your card provider does not provide a module for your operating system or if you want to do batch signing and the module provided by your card provider does not cache the PIN (i.e., always pops up the PIN entry dialog before each signing). Although there are good reasons why the module provided by your card provider always requires that a PIN be manually entered for every use of the private key there are also valid situations where having the application that interfaces with the card cache the PIN is desirable. MyPDFSigner provides that functionality.
Before configuring MyPDFSigner to use the OpenSC module install the most recent version of OpenSC. As of this writing that is version 0.12.0 which can be downloaded from the OpenSC site (or is provided by your Linux distro). If using Windows, replace the opensc-pkcs11.dll file by the one provided here.
Note: the opensc-pkcs11.dll file provided here is compiled from the OpenSC 0.12.0 source with the patch from OpenSC ticket #302 applied. It is expected that with release 0.12.1 this step will be unnecessary.
Configuration of MyPDFSigner with the OpenSC module starts the same way as with the module provided by your card provider but may require one or two extra steps. One of them is that you will be required to login to the card during the configuration (MyPDFSigner will pop up a dialog to enter the PIN). The second possible extra step is that you may need to manually configure the slot to use since by default MyPDFSigner uses the slot 1 and the token you want to use may be in a different slot. To find out which slot you want to use, open a terminal, insert your smart card in the card reader and run the pkcs11-tool with the -L switch:
C:\Programs\OpenSC Project\OpenSC>pkcs11-tool.exe -L
Available slots:
Slot 0 (0xffffffff): Virtual hotplug slot
(empty)
Slot 1 (0x1): Gemplus USB Smart Card Reader 0
token label: KryptoKoder Support (User PIN)
token manuf: EnterSafe
token model: PKCS#15
token flags: rng, login required, PIN initialized, token initialized
serial num : 2986055013181210
Slot 2 (0x2): Gemplus USB Smart Card Reader 0
(empty)
Slot 3 (0x3): Gemplus USB Smart Card Reader 0
(empty)
Slot 4 (0x4): Gemplus USB Smart Card Reader 0
(empty)
In the example above the only non empty slot is slot 1. In cases where the smart card has more than one PIN (say, one for authentication and another for signing) there will be a corresponding number of non empty slots. For instance, for the Portuguese Citizen Card (Cartão de Cidadão) the authentication PIN is in slot 1 and the signing PIN is in slot 2.
Once you know the slot to use, open the .mypdfsigner configuration file in your home directory and change the "slotindex" entry to the corresponding value. If you then restart MyPDFSigner and try to configure it again to use the OpenSC module you should see the expected alias in the "Alias" drop down menu.
See the Using the CLI section below for an example on how to do batch signing with a smart card using the OpenSC module.
IMPORTANT OBSERVATIONS: (a) the initial access to the smart card using the OpenSC module is very slow (takes many seconds); (b) when batch signing the caching of the PIN is done by MyPDFSigner, not by the opensc-pkcs11.[dll|so] module.
PKCS#12 Keystore File: Fill in the File field by entering the location of your *.p12 (or *.pfx) file. The file is protected by a password so you also need to enter one. Next to the Password field there is a checkbox that you can check if you want to save the password to the MyPDFSigner configuration file (the .mypdfsigner file in your home directory).
Note that if you choose to save the password it will be encrypted and thus safe from the prying eyes. However anyone with access to your *.p12 file and your .mypdfsigner configuration file will be able to sign PDF documents on your behalf. If you choose not to save the password you can still sign PDF documents for that session (the next time you run MyPDFSigner you will need to enter the password again).
Once the password is entered you can select a certificate from the "Alias" drop down menu and click "Save".
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.
The template consists of free text plus some placeholders that will be replaced by attributes at signing time. There are four placeholders: %N, which is mandatory and will be replaced by the "CN" attribute in the certificate; %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 or %Z, 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'). One of %D, %T or %Z is mandatory, but if the signing is performed with Time Stamping enabled (see below) then any of the alternatives becomes equivalent to the last one, %Z.
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].
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.
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.
Time Stamping: A TSA (Time Stamp Authority) HTTP(S) server can be configured in this section (account and password are optional). At the moment MyPDFSigner only supports the HTTP(S) POST TSA protocol.
If you do not have a TSA server available try one of the public available ones listed in sites like http://security.polito.it/ts/ (usually only valid for testing purposes). An example is http://tsp.iaik.at/tsp/TspRequest. Some governments provide a TSA to their citizens as part of their National Citizen Card program. For instance, portuguese users can use the TSA at http://ts.cartaodecidadao.pt/tsa/server.
If using a TSA HTTPS server the certificate of the server needs to be trusted by your Java installation, i.e., the certificate of the Root CA that issued the TSA HTTPS server certificate needs to be present in the "cacerts" file ($JAVA_HOME/lib/security/cacerts).
To list the certificates of the trusted CAs in the cacerts file:
keytool -list -v -keystore $JAVA_HOME/lib/security/cacerts
To add a new certificate to cacerts:
keytool -import -trustcacerts -file RootCA.crt -alias new_root_ca -keystore $JAVA_HOME/lib/security/cacerts
Note: (a) if you are prompted for a keystore password, the default one is "changeit"; (b) the alias in the above import is a "friendly name" and can be anything; (c) if you update Java you may unknowingly overwrite the cacerts file in which case you will need to repeat the above step.
Using the CLI
You can sign PDF documents from the command line using the mypdfsigner-cli utility. Use of the CLI is really intended for business purposes and in principle you need a server license to use it (but not to try it). See the License section for more information.
Run mypdfsigner-cli without arguments to get the usage instructions which should be clear to understand. 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.
Note: if you get an error like the following in Linux see the Troubleshooting below for more information.
[support@kryptokoder ~]$ mypdfsigner-cli mypdfsigner-cli: error while loading shared libraries: libjvm.so: cannot open shared object file: No such file or directory
If using a PKCS#11 security device with the OpenSC module, batch signing (i.e., signing all the PDF files inside a directory) can also be done with just one entry of the PIN. In this case the PIN will be entered at the command line:
C:\>c:\Programs\MyPDFSigner\MyPDFSigner-CLI.exe -i c:\tmp CitizenCard [SIGNATURE CERTIFICATE] PIN: Document c:\tmp\MyPDFSigner-Manual.pdf signed Document c:\tmp\Network_Security_with_OpenSSL.pdf signed .......... Success: Folder documents signed
Note that the PIN is not echoed back to the screen.
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).
The configuration file is created using the GUI and is originally saved to the home directory as ".mypdfsigner". You can copy it to the installation directory and rename it as "mypdfsigner.conf" and the CLI will use it instead of your personal configuration file.
Note that the installation directory where you should place the mypdfsigner.conf file is:
-- Windows: C:\Program Files\MyPDFSigner
-- Mac OS X: /Applications/MyPDFSigner.app/Contents/Resources/Java
-- Linux: /usr/local/mypdfsigner
Troubleshooting
Checking for Java: If MyPDFSigner fails to launch when trying to run it then it probably means you do not have java installed. Open a command prompt or teminal and run "java -version". If java is not available you need to install it.
Windows: Download and install the JRE package available from the Java site.
Fedora: Run as root (or using sudo)
# yum list | grep jdk (find the right package name to use)
# yum install java-1.6.0-openjdk
Ubuntu: Run as root (or using sudo)
# apt-cache search jre (find the right package name to use)
# apt-get install sun-java6-jre
libjvm.so error: If you get the error mentioned above when running the CLI in Linux it means the shared object libjvm.so is not being found. Start by locating it and add it to ldconfig. As root do "updatedb" followed by "locate libjvm.so". You should see a server and a client one. The directory of the client one is the one we are interested in.
As root do then something like the following:
# echo "/usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0/jre/lib/i386/client" > /etc/ld.so.conf.d/jvm.conf (fedora example)
# echo "/usr/lib/jvm/java-6-sun-1.6.0.16/jre/lib/i386/client" > /etc/ld.so.conf.d/jvm.conf (ubuntu example)
# ldconfig
Running again mypdfsigner-cli without arguments should display the usage instructions.
Mac OS X and the Portuguese Citizen Card: MyPDFSigner works with the Portuguese Citizen Card in Mac OS X systems (both 32 and 64 bits) but the configuration is usually more involved.
64 bit systems: Version 1.23 of the Portuguese Citizen Card software for the Mac OS X (the most recent as of this writing) does not provide a 64 bit version of the PKCS#11 module (pteidpkcs11.dylib). This prevents MyPDFSigner to work properly with the said software (and card) in Mac OS X x86_64. The recommended alternative is to install OpenSC. If your system is running Lion make sure you download the most recent build from the nightly builds since the most recent official release (version 0.12.2 as of this writing) does not install in Lion (but installs in Snow Leopard).
A simple mypdfsigner.conf file ready to use OpenSC with the Portuguese Citizen Card is provided here (place it in your home directory, /Users/username, and rename it to .mypdfsigner). If you open MyPDFSigner with this configuration file and then click the "Display" (certficate) button you will be prompted (after a few seconds) for your signature PIN, after which the associated certificate will be shown. The PIN is saved for the rest of the session.
The OpenSC module has a small bug that causes MyPDFSigner to build an incomplete certificate chain during the signing process. The end result is a signed PDF that does not provide the full certificate chain. The workaround is to start by signing a PDF document and use Adobe Reader to export the missing certificate to a file that should then be placed in the "eidstore/certs" folder of the Portuguese Citizen Card software.
So start by signing a PDF document using the provided configuration file. If you then open the signed document with Adobe Reader and look at the certificate you will notice that the chain has only two certificates instead of the expected five. Click on the top one, which probably will be "EC de Assinatura Digital Qualificada do Cartão de Cidadão 0002", and then click the "Export" button. Then select "Save the exported data to a file" and "Certificate File" and save the file (accept the default values). This file should be placed in the "/Applications/Cartao de Cidadao/Aplicacao Cartao de Cidadao/Contents/MacOS/eidstore/certs" directory. After this step PDF documents are correctly signed with a full certificate chain. Note that you still need to tell Adobe Reader to trust the Root certificate, but this is an expected step.
32 bit systems: If your system is 32 bits then you can use MyPDFSigner with the Portuguese Citizen Card software but if your system has Mac OS X 10.6.5 or newer there is a different problem that prevents MyPDFSigner to work out of the box with it. Mac OS X comes configured with a PKCS#11 module for smart cards that does not work with the Portuguese Citizen Card and that takes precedence over the configuration built by MyPDFSigner. The workaround is to disable that module and replace it by the module that comes with the Portuguese Citizen Card software. To do that create a file named "sunpkcs11-mypdfsigner.cfg" in /Users/username/Documents with these two lines:
name = CitizenCard library = /usr/local/lib/pteidpkcs11.dylib
Then, with a text editor, open the file /System/Library/Frameworks/JavaVM.framework/Home/lib/security/java.security and look for the line that starts with "security.provider.1". Comment out that line (with a #) and replace it with a similar one that points to the config file created above. The result should look like the following (replace the username):
#security.provider.1=sun.security.pkcs11.SunPKCS11 ${java.home}/lib/security/sunpkcs11-macosx.cfg
security.provider.1=sun.security.pkcs11.SunPKCS11 /Users/kryptokoder/Documents/sunpkcs11-mypdfsigner.cfg
With this change MyPDFSigner should work as expected.
If you are not sure whether your system is 32 (i386) or 64 (x86_64) bits run "uname -a" in a terminal. Install the MyPDFSigner package that corresponds to your system. Also, you may have a 32 bit system (i386) but have the default java be 64 bits (run "java -version"). In that case run MyPDFSigner in 32 bit mode ("Get Info" -> check "Open in 32-bit mode").
Uninstalling
-- Windows: Start > Programs > MyPDFSigner > Uninstall
-- Mac OS X: In the Applications folder right-click MyPDFSigner and select "Move to Trash"
-- Fedora: rpm -e mypdfsigner
-- Ubuntu: dpkg -r mypdfsigner
Note that in Mac OS X the CLI needs to be removed from a terminal:
$ sudo rm /usr/local/bin/mypdfsigner-cli