KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > faceless > pdf > FormSignature


1 // $Id: FormSignature.java,v 1.4 2003/11/03 14:03:51 mike Exp $
2
3 package org.faceless.pdf;
4
5 import java.io.*;
6 import java.util.*;
7 import java.security.*;
8 import java.security.cert.*;
9 import java.security.spec.*;
10
11 /**
12  * <p>
13  * This class represents a public key "Digital Signature" which can
14  * be used to sign a PDF document. Signatures from existing documents can be
15  * verified and new signatures can be added. Signatures not based around a
16  * Public Key crypto system are not supported.
17  * </p><p>
18  * Signatures may be applied and verified using either the full version of
19  * Adobe Acrobat&trade; or Adobe Approval, <b>not</b> the free Acrobat Reader.
20  * Acrobat comes with a "digital signature handler" called the Self-Sign
21  * handler, which allows a limited form of verification, and additional handlers
22  * are available as plugins for Acrobat. Several are supplied on the Acrobat CD.
23  * </p><p>
24  * The signatures used in PDF documents are X.509 certificates, which are
25  * already handled by the <code>java.security</code> packages supplied with
26  * J2SE 1.2 and later. No additional Java classes are required.
27  * </p><p>
28  * An important point to remember is that the signatures on an existing
29  * document are <b>not preserved</b> if that document is loaded then saved.
30  * This is because the document structure is irreversably changed by this
31  * process, which renders the signature invalid. Another key point is that in
32  * the current version of this library only a single {@link #STATE_PENDING}
33  * signature can be applied to a PDF.
34  * </p><p>
35  * So how do you use this class? First we'll cover how to verify signatures
36  * on an existing document.
37  * </p>
38  *
39  * <h3>Verifying existing signatures</h3>
40  * <p>
41  * To verify a document has been signed and not altered since signing, and
42  * to be sure of the signatory, three steps are required:
43  * <ol>
44  * <li>You must verify that content of the document matches the signature</li>
45  * <li>You must verify that the signature covers the whole document</li>
46  * <li>You must verify that the key used to sign the document belongs to who it says it does</li>
47  * </ol>
48  * First, verifying that the signature matches the document content is done
49  * using the {@link #verify} method. This can be done like so:
50  * </p>
51  * <pre>
52  * PDF pdf = new PDF(new PDFReader(new FileInputStream(args[0])));
53  * <b>Map elements = pdf.getForm().getElements();</b>
54  *
55  * for (Iterator i=elements.keySet().iterator(); i.hasNext();) {
56  * String name = (String)i.next();
57  * if (elements.get(name) instanceof FormSignature) {
58  * <b>FormSignature sig = (FormSignature)elements.get(name);
59  * if (sig.verify()) {</b>
60  * System.out.println("Signature from "+sig.getName()+" matches");
61  * }
62  * }
63  * }
64  * </pre>
65  * <p>
66  * Second, you must verify that the signature covers the latest revision of the
67  * document - otherwise the document could have been altered after signing. See the
68  * {@link PDFReader} class documentation for more information about revisions. To
69  * verify the signature covers the latest revision, you need to compare the value of
70  * {@link PDF#getNumberOfRevisions} with the value of {@link #getNumberOfRevisionsCovered}.
71  * Something like this should do it:
72  * </p>
73  * <pre>
74  * int pdfrevision = pdf.getNumberOfRevisions();
75  * int sigrevision = signature.getNumberOfRevisionsCovered();
76  * if (pdfrevision==sigrevision) System.out.println("Whole document is covered");
77  * </pre>
78  * <p>
79  * At this point you know the signature covers the whole document, and that the
80  * document hasn't been changed since signing. However, this is only half the
81  * story. Although the signature matches the content, in order to be 100% sure the
82  * document is unaltered you need to check the certificates used to sign the
83  * document - otherwise anyone could create a certificate with any name they choose.
84  * A full discussion of PKI could fill a book in itself, but generally speaking a
85  * key is signed by a "chain" of certificates, with the certificate at the end of the
86  * chain considered to be "trusted".
87  * </p><p>
88  * Each Java distribution comes with a list of trusted top-level certificates,
89  * which are used to verify signed JAR files. One of these top-level certificates
90  * is usually at the end of every certificate chain. Here's how to verify the
91  * certificates used against that list, called a "KeyStore".
92  * </p>
93  * <pre>
94  * <b>KeyStore trusted = FormSignature.loadDefaultKeyStore();</b>
95  *
96  * PDF pdf = new PDF(new PDFReader(new FileInputStream(args[0])));
97  * <b>Map elements = pdf.getForm().getElements();</b>
98  *
99  * for (Iterator i=elements.keySet().iterator(); i.hasNext();) {
100  * String name = (String)i.next();
101  * if (elements.get(name) instanceof FormSignature) {
102  * <b>FormSignature sig = (FormSignature)elements.get(name);
103  * if (sig.verifyCertificates(trusted,null)==null) {</b>
104  * System.out.println("Certificates for "+sig.getName()+" verified");
105  * }
106  * }
107  * }
108  * </pre>
109  * <p>
110  * As any cryptographer will tell you, there is much more to key management
111  * than we've described here. It's hard not to sound paranoid when discussing
112  * cryptography, because you must always remember when verifying certificates
113  * that you are trusting every entity in the certificate chain. Their certificate
114  * is the only guarantee you've got that the certificates they've signed
115  * belong to the entities those certificates represent. The certificate chain can be accessed
116  * via the {@link #getCertificates} method, and the
117  * <code>isValidCertificate</code> method used to perform some basic validation
118  * if you want to check the certificates yourself.
119  * </p>
120  *
121  * <h3>Signing documents</h3>
122  * <p>
123  * A single signature can be applied to a PDF document by adding the signature
124  * to the PDF documents Form. Although the PDF library supports reading documents
125  * with multiple revisions, it doesn't support writing them, which is why only a
126  * single signature can be used. Here's an example.
127  * </p>
128  * <pre>
129  * PDF pdf = new PDF();
130  * // Create pdf document here
131  *
132  * KeyStore keystore = loadMyKeyStore(); // Somehow load a keystore
133  *
134  * <b>FormSignature sig = new FormSignature(keystore, "mykey",
135  * "secret".toCharArray(),
136  * FormSignature.HANDLER_VERISIGN);</b>
137  * <b>pdf.getForm().addElement("Test Signature", sig);</b>
138  * </pre>
139  * <p>
140  * This slightly oversimplified example demonstrates two things. One, that the
141  * private key and its associated certificates used to sign a document must be
142  * loaded from a {@link KeyStore}, and two, that a digital signature must
143  * be verified by a specified digital signature handler.
144  * </p><p>
145  * Although in theory all PKI signature handlers should be interoperable (Adobe recommend
146  * this in their <a HREF=http://partners.adobe.com/asn/developer/acrosdk/docs/ppk_pdfspec.pdf>specification</a>,
147  * and this library can verify all signatures that meet those requirements),
148  * at least Acrobat 4.0 doesn't allow a signature created with the Self-Sign handler
149  * to be verified by the VeriSign handler, and vice-versa. This means before applying a
150  * digital signature you need to know which handlers are available to your audience.
151  * </p><p>
152  * Here are the handlers we know about with the level of support we offer.
153  * </p><p>
154  * <table border=1>
155  * <tr><td><b>Adobe "Self Sign" handler</b></td><td>Can read/write signatures. See {@link #HANDLER_SELFSIGN}</td></tr>
156  * <tr><td nowrap><b>VeriSign Document Signer</b></td><td>Can read/write signatures. See {@link #HANDLER_VERISIGN}</td></tr>
157  * <tr><td nowrap><b>Entrust PPKEF architecture</b></td><td>Currently unsupported. We hope to support the Entrust architecture in the not-so-distant future.</td></tr>
158  * <tr><td><b>CIC "Sign-It" handler</b></td><td>Not a public/private key handler, uses custom "written" signatures instead. Unsupported.</td></tr>
159  * </table>
160  * <p>
161  * Finally to get you started, here is a complete example showing how to create
162  * a PDF signed with the Adobe "self-sign" signature handler. Rather than type
163  * all this out we suggest you take a look at the "Sign.java" example supplied
164  * with the package, which does all this and more.
165  * </p>
166  * <ol>
167  * <li>
168  * <p>
169  * Create a self-signed key using the "keytool" program supplied with the JDK.
170  * The following command will create a 1024-bit RSA key plus certificate in
171  * the file "mykeystore". You'll be prompted for a password.
172  * </p>
173  * <pre>
174  * keytool -genkey -alias mykey -keyalg RSA -sigalg MD5withRSA \
175  * -keystore mykeystore -dname 'C=UK, O=BigFaceless, CN=BFO'
176  * </pre>
177  * </li>
178  * <li>
179  * <p>
180  * The following code can be used to create a blank PDF which is digitally
181  * signed with this key.
182  * </p><pre>
183  * import java.security.KeyStore;
184  * import java.io.*;
185  * import org.faceless.pdf.*;
186  *
187  * public static void TestSign
188  * {
189  * static final String KEYFILE = "mykeystore"; // Name of keystore file
190  * static final String KEYALIAS = "mykey"; // Alias for private key
191  * static final char[] PASSWORD = "secret".toCharArray(); // Password
192  * static final String OUTFILE = "signed.pdf"; // File to write to.
193  *
194  * public static void main(String[] args) throws Exception
195  * {
196  * // Load the keystore
197  * //
198  * KeyStore keystore = KeyStore.getInstance("JKS");
199  * keystore.load(new FileInputStream(KEYFILE), PASSWORD);
200  *
201  * // Create the PDF (with 1 blank page to keep Acrobat happy).
202  * //
203  * PDF pdf = new PDF();
204  * PDFPage page = pdf.newPage(PDF.PAGESIZE_A4);
205  *
206  * // Create the digital signature object
207  * //
208  * FormSignature sig = new FormSignature(keystore, KEYALIAS, PASSWORD,
209  * FormSignature.HANDLER_SELFSIGN);
210  * pdf.getForm().addElement("Test Signature", sig);
211  *
212  * // Write it out
213  * pdf.render(new FileOutputStream(OUTFILE));
214  * }
215  * }
216  * </pre>
217  * </li><li>
218  * <p>
219  * Run the program. This creates a file "signed.pdf", whose integrity can be
220  * verified in Adobe Acrobat 4.0 or greater.
221  * </p><pre>
222  * java TestSign
223  * </pre>
224  * </li></ol>
225  * <p>
226  * More information on digital signatures is available in the userguide.
227  * </p>
228  *
229  * @since 1.1.13
230  * @version $Revision: 1.4 $
231  */
232 public final class FormSignature extends FormElement
233 {
234     FormSignature(org.faceless.pdf2.FormSignature b)
235     {
236         super(b);
237     }
238
239     /**
240      * <p>
241      * A type of handler representing the Adobe "self-sign" signature handler
242      * supplied with every version of Acrobat. Keys must use the RSA algorithm
243      * and may be any length (we've tested 512, 1024 and 2048-bit keys).
244      * Certificates must use the MD5/RSA signature algorithm. Obviously the
245      * certificate associated with the key must be self-signed, and Acrobat also
246      * insists that the country code, if specified, must be exactly 2 letters long.
247      * </p><p>
248      * Self-sign signatures are limited in that only certificates in the viewing
249      * users "Personal Address Book" are considered to be trusted - a Certifying
250      * Authority is not used. Certificates may be added to the address book if they're
251      * not already there, and provided they are confirmed (by manually checking
252      * the serial number with the issuer), this handler does most of what is required
253      * of a PKI system.
254      * </p>
255      */
256     public static final int HANDLER_SELFSIGN = 0;
257
258     /**
259      * <p>
260      * A type of handler representing the VeriSign "Document Signer" digital signature handler.
261      * Keys must use the RSA algorithm and may be any length, but <i>must</i>
262      * be signed by a VeriSign CA key or they will be considered invalid by the
263      * VeriSign plugin. Having said that, VeriSign also distribute an "Administrator Tool"
264      * which allows you to set your own list of trusted certificates, although we haven't
265      * tested this functionality.
266      * </p><p>
267      * The plugin itself is distributed on the Acrobat CD or available from the
268      * <a HREF="http://www.verisign.com/products/acrobat">VeriSign website</a>
269      * as a free download. Details on how to use and install the plugin are also
270      * available from this site.
271      * </p><p>
272      * The VeriSign test certificate we worked with was MD5/RSA,
273      * and we expect that all keys that work with this plugin must
274      * use this algorithm.
275      * </p>
276      */
277     public static final int HANDLER_VERISIGN = 1;
278
279     /**
280      * This value is returned from the {@link #getState} method if the signature is
281      * "old" - the PDF document that was read in was already signed with this
282      * signature. The signature may be validated, but will not be exported again if
283      * the document is resaved.
284      * @see #STATE_PENDING
285      * @see #getState
286      */
287     public static final int STATE_SIGNED = 0;
288
289     /**
290      * This value is returned from the {@link #getState} method if the signature is
291      * "new" - it has been added to the document and is waiting for the document to
292      * be completed before it is applied. Only one "pending" signature may currently
293      * be applied to each document.
294      * @see #STATE_SIGNED
295      * @see #getState
296      */
297     public static final int STATE_PENDING = 1;
298
299     private org.faceless.pdf2.FormSignature sig;
300
301     /**
302      * <p>
303      * Create a new digital signature to sign a PDF document. The private key and
304      * the certificates used to sign the PDF are contained in the specified
305      * keystore.
306      * </p>
307      * @param keystore the KeyStore containing the private key and a list of certificates
308      * to sign the document with
309      * @param alias the alias or "friendly-name" which the private key is stored under
310      * in the keystore
311      * @param password the password to unlock the private key
312      * @param handler the digital signature handler that will be used to verify the
313      * signature. Current values are {@link #HANDLER_SELFSIGN}, for the Adobe Self-Sign handler,
314      * and {@link #HANDLER_VERISIGN}, for the VeriSign handler.
315      * @throws GeneralSecurityException if the keystore, private key, password or certificates are invalid in any way
316      * @throws IllegalArgumentException if the arguments are technically correct but will result in an invalid signature for any reason.
317      */
318     public FormSignature(KeyStore keystore, String JavaDoc alias, char[] password, int handler)
319         throws GeneralSecurityException, IllegalArgumentException JavaDoc
320     {
321     super(new org.faceless.pdf2.FormSignature(keystore, alias, password, handler==HANDLER_VERISIGN ? org.faceless.pdf2.FormSignature.HANDLER_VERISIGN : org.faceless.pdf2.FormSignature.HANDLER_SELFSIGN));
322     }
323
324     /**
325      * Returns the current state of the signature. The state is
326      * currently either {@link #STATE_SIGNED} for existing signatures,
327      * or {@link #STATE_PENDING} for new signatures.
328      */
329     public int getState()
330     {
331     int state = ((org.faceless.pdf2.FormSignature)element).getState();
332     if (state==org.faceless.pdf2.FormSignature.STATE_SIGNED) {
333         return STATE_SIGNED;
334     } else {
335         return STATE_PENDING;
336     }
337     }
338
339     /**
340      * Set the name of the person or entity who is applying this signature.
341      * Setting this field is recommended but not necessary - it defaults
342      * to the Common Name (CN) of the signing certificate.
343      *
344      * @param name the name of the entity signing the PDF,
345      * or <code>null</code> to clear the current reason
346      */
347     public void setName(String JavaDoc name)
348     {
349     ((org.faceless.pdf2.FormSignature)element).setName(name);
350     }
351
352     /**
353      * Return the name of the person or entity who created this signature
354      * if specified, or <code>null</code> otherwise.
355      */
356     public String JavaDoc getName()
357     {
358     return ((org.faceless.pdf2.FormSignature)element).getName();
359     }
360
361     /**
362      * Set the reason why the the document is being signed -
363      * e.g. "Approved for distribution". This field is optional.
364      * @param reason the reason the entity is signing the document,
365      * or <code>null</code> to clear the current reason
366      */
367     public void setReason(String JavaDoc reason)
368     {
369     ((org.faceless.pdf2.FormSignature)element).setReason(reason);
370     }
371
372     /**
373      * Return the reason this signature was applied to the PDF
374      * if specified, or <code>null</code> otherwise.
375      */
376     public String JavaDoc getReason()
377     {
378     return ((org.faceless.pdf2.FormSignature)element).getReason();
379     }
380
381     /**
382      * Set the location where the signer is signing the PDF
383      * document - e.g. "Head Office". This field is optional.
384      * @param location the location where the entity is signing the document,
385      * or <code>null</code> to clear the current location
386      */
387     public void setLocation(String JavaDoc location)
388     {
389     ((org.faceless.pdf2.FormSignature)element).setReason(location);
390     }
391
392     /**
393      * Return the location where this document was signed if
394      * specified, or <code>null</code> otherwise.
395      */
396     public String JavaDoc getLocation()
397     {
398     return ((org.faceless.pdf2.FormSignature)element).getLocation();
399     }
400
401     /**
402      * Return the time the signature was applied to the document.
403      * @return the time the document was signed.
404      */
405     public Calendar getSignDate()
406     {
407     return ((org.faceless.pdf2.FormSignature)element).getSignDate();
408     }
409
410     /**
411      * Return the name of the digital signature handler used to sign the
412      * document. Common values are <code>Adobe.PPKLite</code> for the Adobe
413      * Self-Sign handler supplied by default with Acrobat 4.0 and greater,
414      * <code>VeriSign.PPKVS</code> for VeriSigns document signer plugin,
415      * <code>Entrust.PPKEF</code> for the Entrust architecture or
416      * <code>CICI.SignIt</code>.
417      * @see #HANDLER_SELFSIGN
418      * @see #HANDLER_VERISIGN
419      */
420     public String JavaDoc getType()
421     {
422     return ((org.faceless.pdf2.FormSignature)element).getFilter();
423     }
424
425     /**
426      * Return the list of certificates included in this signature.
427      * The first certificate is the X.509 certificate used to sign
428      * the PDF, and the optional additional certificates are those
429      * used to validate the earlier certificates, in no particular
430      * order.
431      *
432      * @return a list of one or more X.509 Certificates
433      */
434     public X509Certificate[] getCertificates()
435         throws CertificateException
436     {
437     org.faceless.pdf2.PKCS7SignatureHandler handler;
438     handler = (org.faceless.pdf2.PKCS7SignatureHandler)((org.faceless.pdf2.FormSignature)element).getSignatureHandler();
439     return handler.getCertificates();
440     }
441
442
443     /**
444      * <p>
445      * Verify a signature by ensuring that the PDF document hasn't been altered
446      * since it was signed. Only signatures with a state of {@link #STATE_SIGNED}
447      * may be verified.
448      * </p><p>
449      * Note that this only ensures the document matches the specified X.509
450      * certificate(s) - to completely confirm the document is unaltered the
451      * certificates returned by {@link #getCertificates} should also be
452      * validated, either manually or using the {@link #verifyCertificates}
453      * method.
454      * </p>
455      * @return <code>true</code> if the document is unaltered, <code>false</code>
456      * if the document has been altered since signing
457      *
458      * @throws IllegalStateException if the signature you're verifying isn't
459      * {@link #STATE_SIGNED}
460      * @throws GeneralSecurityException if the specified signing algorithm is
461      * unknown, or the certificate or key are invalid
462      */
463     public boolean verify()
464         throws GeneralSecurityException
465     {
466     return ((org.faceless.pdf2.FormSignature)element).verify();
467     }
468
469
470     /**
471      * Return the number of document revisions covered by this signature. A
472      * PDF document can be revised a number of times - for example, filling
473      * out a form in Acrobat and saving the document creates a new revision.
474      * Every revision of the document must be covered by a signature in order
475      * to be sure of the documents contents. See the {@link PDFReader} class
476      * for more information on document revisions, and the class documentation
477      * for this class for examples of how to validate a signature using this
478      * method.
479      * @return the number of revisions covered by this signature, or zero
480      * if the signature doesn't cover any (in which case it should be discounted)
481      * @since 1.2.1
482      */
483     public int getNumberOfRevisionsCovered()
484     {
485     return ((org.faceless.pdf2.FormSignature)element).getNumberOfRevisionsCovered();
486     }
487
488     /**
489      * Verify the certificates used to sign this document against a list
490      * of trusted certificates.
491      * <p>
492      * The X.509 certificate(s) used to sign the document are verified and
493      * compared against the certificates in the keystore, which are
494      * assumed to be trusted. An optional <i>Certificate Revocation
495      * List</i> may be specified with a list of compromised certificates.
496      * </p><p>
497      * The method returns the first certificate specified in the PDF that
498      * <i>cannot</i> be verified. If every certificate in the chain is verified
499      * and the final certificate is signed by a certificate in the specified
500      * keystore, the entire chain is considered valid and this method returns
501      * <code>null</code>.
502      * </p><p>
503      * The specified keystore may be the result of {@link #loadDefaultKeyStore},
504      * or a user specified keystore. The CRL may be (and usually is) <code>null</code>.
505      * </p><p>
506      * Note that self-signed certificates (as created by the Adobe Self-Sign
507      * handler) will generally fail, as they cannot be verified against a trusted
508      * root certificate. The only exception to this is if you're verifying against
509      * a keystore returned from {@link #loadAKFKeyStore}, containing a certificate
510      * that was exported from Acrobat.
511      * </p><p>
512      * Also note that unless you personally trust every entity (represented by
513      * a certificate) in the chain to issue certificates responsibly, verifying
514      * the chain integrity is worthless.
515      * </p>
516      *
517      * @param keystore the <code>KeyStore</code> containing one or more
518      * trusted certificates to verify the certificate chain against.
519      *
520      * @param crl the Certificate Revocation List to check the
521      * certificates against. May be <code>null</code>.
522      *
523      * @return the first certificate in the chain that <i>couldn't</i> be
524      * verified, or <code>null</code> if all were verified against a
525      * certificate from the keystore.
526      *
527      * @throws GeneralSecurityException if the KeyStore or any of the
528      * certificates are invalid.
529      * @see #loadAKFKeyStore
530      * @see #loadPKCS7KeyStore
531      * @see #loadDefaultKeyStore
532      */
533     public X509Certificate verifyCertificates(KeyStore keystore, CRL crl)
534         throws GeneralSecurityException
535     {
536     org.faceless.pdf2.PKCS7SignatureHandler handler;
537     handler = (org.faceless.pdf2.PKCS7SignatureHandler)((org.faceless.pdf2.FormSignature)element).getSignatureHandler();
538     X509Certificate[] certs = handler.getCertificates();
539     Calendar signdate = getSignDate();
540     return org.faceless.pdf2.FormSignature.verifyCertificates(certs, keystore, crl, signdate);
541     }
542
543     //--------------------------------------------------------------------------
544
545
546     /**
547      * Return true if the specified X.509 Certificate is valid for the specified date,
548      * has not been revoked and has no unknown critical extensions.
549      *
550      * @param cert the X.509 certificate to verify
551      * @param crl the Certificate Revokation List to search - may be <code>null</code>
552      * @param signdate the date the certificate was used for signing
553      */
554     public static boolean isValidCertificate(X509Certificate cert, CRL crl, Date signdate)
555     {
556     return org.faceless.pdf2.FormSignature.isValidCertificate(cert, crl, signdate);
557     }
558
559     /**
560      * Return the default Java keystore to validate keys against.
561      * This is the same keystore used to verify signed JAR files,
562      * and is distributed with most versions of Java. It includes
563      * the public certificates for several certifying authorities -
564      * in our version (Sun JDK1.3.1), VeriSign and Thawte.
565      */
566     public static KeyStore loadDefaultKeyStore()
567         throws GeneralSecurityException
568     {
569     return org.faceless.pdf2.FormSignature.loadDefaultKeyStore();
570     }
571
572     /**
573      * <p>
574      * Load an X.509 certificate from an "Adobe Key File" keystore, the type
575      * exported from the Adobe Self-Sign signature handler in Acrobat 4.0. The
576      * file (which is exported with a <code>.akf</code> suffix) contains a
577      * self-signed X.509 certificate, which can be used to verify (but not sign)
578      * documents created with the Adobe Self-Sign signature handler.
579      * </p><p>
580      * The returned KeyStore has a single X.509 certificate, and can be
581      * passed to the <code>verifyCertificates</code> method to fully validate
582      * a document signed with the "self-sign" signature handler, acting as
583      * the Java equivalent of the "Personal Address Book" in Acrobat 4 terminology.
584      * </p><p>
585      * Acrobat 5.0 keystores are saved in a different format - the filename is usually
586      * "<code>CertExchange<i>Name</i>.fdf", where <i>Name</i> is the name of the user.
587      * These keystores can be loaded via the {@link #loadFDFKeyStore} method.
588      * </p>
589      * @see #HANDLER_SELFSIGN
590      * @see #verifyCertificates
591      * @see #loadFDFKeyStore
592      */
593     public static KeyStore loadAKFKeyStore(InputStream in)
594         throws IOException, GeneralSecurityException
595     {
596     return org.faceless.pdf2.FormSignature.loadAKFKeyStore(in);
597     }
598
599     /**
600      * <p>
601      * Load an X.509 certificate from an "Adobe Self-Sign Key" keystore, the type
602      * exported from the Adobe Self-Sign signature handler in Acrobat 5.0. The
603      * file (which is exported with a <code>.fdf</code> suffix) contains a
604      * self-signed X.509 certificate, which can be used to verify (but not sign)
605      * documents created with the Adobe Self-Sign signature handler.
606      * </p><p>
607      * The returned KeyStore has a single X.509 certificate, and can be
608      * passed to the <code>verifyCertificates</code> method to fully validate
609      * a document signed with the "self-sign" signature handler, acting as
610      * the Java equivalent of the "Trusted Certificates" in Acrobat 5 terminology.
611      * </p><p>
612      * Acrobat 4.0 keystores are saved in a different format - the filename has a suffix
613      * of "<code>.akf</code>". These keystores can be loaded via the
614      * {@link #loadAKFKeyStore} method. Acrobat 5.0 can also save keys in a PKCS#7 format,
615      * which can be loaded using the {@link #loadPKCS7KeyStore} method.
616      * </p>
617      * @since 1.2.1
618      * @see #HANDLER_SELFSIGN
619      * @see #verifyCertificates
620      * @see #loadAKFKeyStore
621      */
622     public static KeyStore loadFDFKeyStore(InputStream in)
623         throws IOException, GeneralSecurityException
624     {
625     return org.faceless.pdf2.FormSignature.loadFDFKeyStore(in);
626     }
627
628     /**
629      * <p>
630      * Load a list of one or more X.509 certificates from a PKCS#7 file.
631      * </p><p>
632      * The returned KeyStore contains X.509 certificates and can be
633      * passed to the <code>verifyCertificates</code> method to verify (but not sign)
634      * the certificates used to sign a PDF document.
635      * </p><p>
636      * Note that we provide this method for convenience only. If you're working
637      * heavily with PKCS format files, we recommend obtaining a JCE implementation
638      * that supports them fully. One that we have tested with some success is provided by
639      * <a HREF="http://www.bouncycastle.org">The Legion of the Bouncy Castle</a>.
640      * </p>
641      * @see #HANDLER_VERISIGN
642      * @see #verifyCertificates
643      */
644     public static KeyStore loadPKCS7KeyStore(InputStream in)
645         throws IOException, GeneralSecurityException
646     {
647     return org.faceless.pdf2.FormSignature.loadPKCS7KeyStore(in);
648     }
649
650     /**
651      * <p>
652      * Return the specified X.500 field from the specified X.509 certificates Issuer.
653      * </p><p>
654      * Each X.509 certificate has two entities - a subject and an issuer. These are
655      * represented in java by the <code>java.security.Principal</code> class, but
656      * unfortunately that class doesn't allow for extraction of the various elements
657      * from the entity - elements like Common Name, Country, Organization etc.
658      * </p><p>
659      * The {@link #getIssuerField} and {@link #getSubjectField} methods aren't
660      * specific to digital signatures or PKCS#7, but are useful "utility" methods
661      * that fill that gap in functionality.
662      * </p>
663      *
664      * @param cert the X.509 certificate to extract the Issuer from
665      * @param field the field to return. Can be one of "C" (country), "CN" (common
666      * name), "O" (organization", "OU" (organization unit), "L" (locale), "ST" (state
667      * or province) or "Email" (email address - although technically not part of X.500
668      * this is sometimes included)
669      * @return the requested field, or <code>null</code> if the field is not part of
670      * the X.500 name.
671      */
672     public static String JavaDoc getIssuerField(X509Certificate cert, String JavaDoc field)
673         throws CertificateException
674     {
675     return org.faceless.pdf2.FormSignature.getIssuerField(cert, field);
676     }
677
678     /**
679      * <p>
680      * Return the specified X.500 field from the specified X.509 certificates Subject.
681      * See the {@link #getIssuerField} method for more information.
682      * </p>
683      * @param cert the X.509 certificate to extract the Issuer from
684      * @param field the field to return. Can be one of "C" (country), "CN" (common
685      * name), "O" (organization", "OU" (organization unit), "L" (locale), "ST" (state
686      * or province) or "Email" (email address - although technically not part of X.500
687      * this is sometimes included)
688      * @return the requested field, or <code>null</code> if the field is not part of
689      * the X.500 name.
690      */
691     public static String JavaDoc getSubjectField(X509Certificate cert, String JavaDoc field)
692         throws CertificateException
693     {
694     return org.faceless.pdf2.FormSignature.getSubjectField(cert, field);
695     }
696 }
697
Popular Tags