iaik.pdf.signature

Class PdfSignatureInstance

java.lang.Object

iaik.pdf.signature.PdfSignatureInstance

Direct Known Subclasses:

PdfSignatureInstanceItext, PdfSignatureInstancePdfbox

public abstract class PdfSignatureInstance
extends java.lang.Object

This class provides methods to create, extract and verify PDF signatures.

Constructor Summary

Constructors

Constructor and Description
PdfSignatureInstance()

Method Summary

Modifier and Type	Method and Description
abstract void	addArchivalTimestamp(java.lang.String tsaUrl, java.lang.String username, java.lang.String password, PadesLTVParameters params, java.lang.String newTimestampedFilePath) Add the validation data contained in params to this document's DSS (document security store) as defined by PAdES-LTV (PAdES - long term validation).
abstract void	addArchivalTimestamp(java.lang.String tsaUrl, java.lang.String username, java.lang.String password, PadesLTVParameters params, java.lang.String newTimestampedFilePath, java.lang.String digestAlgorithm) Add the validation data contained in params to this document's DSS (document security store) as defined by PAdES-LTV (PAdES - long term validation).
static java.lang.String	certificateInfosToText(iaik.x509.X509Certificate cert, java.util.Calendar signDate, java.lang.String reason, java.lang.String location) Create a String of certificate and signature details.
abstract void	certify() Add a certification signature as defined in initSign.
abstract void	certify(CertificationSignature.ModificationPermission allowedModification) Add a certification signature as defined in initSign.
abstract void	certify(CertificationSignature.ModificationPermission allowedModification, LegalContentAttestation attestation) Add a certification signature as defined in initSign.
abstract void	closeDocument() Close document instances that may still be open.
abstract CertificationSignature	getCertificationSignature() Extract the certification signature if included.
abstract PadesLTVParameters	getDocumentSecurityStore() Get all validation data included in the document security store (dss).
abstract PdfSignatureDetails[]	getSignatures() Extract all PDF signatures (approval and certification signatures) contained in the document.
abstract void	initSign(java.io.InputStream originalPdf, byte[] pwd, java.io.OutputStream signedPdf, java.security.PrivateKey privateKey, java.security.cert.Certificate[] certChain, PdfSignatureParameters params) Set all details needed to create a PDF signature.
abstract void	initSign(java.lang.String originalFilePath, byte[] pwd, java.lang.String signedFilePath, java.security.PrivateKey privateKey, java.security.cert.Certificate[] certChain, PdfSignatureParameters params) Set all details needed to create a PDF signature.
abstract void	initVerify(java.io.InputStream pdfStream, byte[] pwd) Specify the signed PDF document to be further analyzed.
abstract void	initVerify(java.lang.String path, byte[] pwd) Specify the signed PDF document to be further analyzed.
static void	setCmsSecurityProvider(iaik.cms.SecurityProvider cmsSecProvider) Only calls SecurityProvider.setSecurityProvider(cmsSecProvider); to tell IAIK CMS which provider to use for signing.
abstract void	sign() Sign the PDF document given as defined in initSign.
void	verify() Verifies the signature value of each contained signature.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PdfSignatureInstance

public PdfSignatureInstance()

Method Detail

initSign

public abstract void initSign(java.lang.String originalFilePath,
                              byte[] pwd,
                              java.lang.String signedFilePath,
                              java.security.PrivateKey privateKey,
                              java.security.cert.Certificate[] certChain,
                              PdfSignatureParameters params)
                       throws java.io.IOException,
                              PdfSignatureException

Set all details needed to create a PDF signature. Depending on the key type specified, you may need to set a CMSSecurityProvider. E.g. if you use the IAIK PKCS#11-provider to create the signature on a smart card or token you have to set the PKCS#11 security provider: SecurityProvider.setSecurityProvider(new IaikPkcs11SecurityProvider((IAIKPkcs11)pkcs11Provider)); If using EC-keys and the IAIK ECCelerate toolkit, also use the corresponding CMS security provider: SecurityProvider.setSecurityProvider(new ECCelerateProvider());

Parameters:

originalFilePath - path to the PDF document, that shall be signed

pwd - password to open the document if encrypted (may be null)

signedFilePath - path where to save the signed PDF document

privateKey - private key to use for creating the signature

certChain - certificate chain corresponding to the given private key

params - parameters defining the required characteristics of the signature

Throws:

java.io.IOException - if the original file can't be read or the signed file can't be written

PdfSignatureException - if specified parameters are invalid or certificates can't be parsed

initSign

public abstract void initSign(java.io.InputStream originalPdf,
                              byte[] pwd,
                              java.io.OutputStream signedPdf,
                              java.security.PrivateKey privateKey,
                              java.security.cert.Certificate[] certChain,
                              PdfSignatureParameters params)
                       throws java.io.IOException,
                              PdfSignatureException

Set all details needed to create a PDF signature. Depending on the key type specified, you may need to set a CMSSecurityProvider. E.g. if you use the IAIK PKCS#11-provider to create the signature on a smart card or token you have to set the PKCS#11 security provider: SecurityProvider.setSecurityProvider(new IaikPkcs11SecurityProvider((IAIKPkcs11)pkcs11Provider)); If using EC-keys and the IAIK ECCelerate toolkit, also use the corresponding CMS security provider: SecurityProvider.setSecurityProvider(new ECCelerateProvider()); If using PdfBox the given originalPdf stream will be wrapped in a NonClosingIteratingInputStream.

Parameters:

originalPdf - the stream to read the PDF document from, that shall be signed

pwd - password to open the document if encrypted (may be null)

signedPdf - stream to write the signed PDF document to

privateKey - private key to use for creating the signature

certChain - certificate chain corresponding to the given private key

params - parameters defining the required characteristics of the signature

Throws:

java.io.IOException - if the original file can't be read or the signed file can't be written

PdfSignatureException - if specified parameters are invalid or certificates can't be parsed

sign

public abstract void sign()
                   throws PdfSignatureException,
                          java.io.IOException

Sign the PDF document given as defined in initSign. (Add an approval signature.)

Throws:

PdfSignatureException - if errors during signing occur

java.io.IOException - if the signed document can't be written

certify

public abstract void certify()
                      throws PdfSignatureException,
                             java.io.IOException

Add a certification signature as defined in initSign. Such a signature shall be the first signature in the document and additionally to the signature as used in the approval signature defines what kind of modifications are allowed. Uses ModificationPermission.SignaturesFormsTemplates as default.

Throws:

PdfSignatureException - if errors during signing occur

java.io.IOException - if the signed document can't be written

See Also:

CertificationSignature.ModificationPermission

certify

public abstract void certify(CertificationSignature.ModificationPermission allowedModification)
                      throws PdfSignatureException,
                             java.io.IOException

Add a certification signature as defined in initSign. Such a signature shall be the first signature in the document and additionally to the signature as used in the approval signature defines what kind of modifications are allowed. Uses ModificationPermission.SignaturesFormsTemplates as default.

Parameters:

allowedModification - the modifications allowed in order not to invalidate the signature

Throws:

PdfSignatureException - if errors during signing occur

java.io.IOException - if the signed document can't be written

See Also:

CertificationSignature.ModificationPermission

certify

public abstract void certify(CertificationSignature.ModificationPermission allowedModification,
                             LegalContentAttestation attestation)
                      throws PdfSignatureException,
                             java.io.IOException

Add a certification signature as defined in initSign. Such a signature shall be the first and only signature in the document and additionally to the signature as used in the approval signature defines what kind of modifications are allowed. Uses ModificationPermission.SignaturesFormsTemplates as default.

Parameters:

allowedModification - the modifications allowed in order not to invalidate the signature

attestation - legal content attestation certifying the document's content

Throws:

PdfSignatureException - if errors during signing occur

java.io.IOException - if the signed document can't be written

See Also:

CertificationSignature.ModificationPermission

initVerify

public abstract void initVerify(java.lang.String path,
                                byte[] pwd)
                         throws java.io.IOException

Specify the signed PDF document to be further analyzed.

Parameters:

path - path to the signed PDF document that shall be analyzed

pwd - password to open the document if encrypted (may be null)

Throws:

java.io.IOException - if the document can't be read

initVerify

public abstract void initVerify(java.io.InputStream pdfStream,
                                byte[] pwd)
                         throws java.io.IOException

Specify the signed PDF document to be further analyzed. If using PdfBox the given pdfStream will be wrapped in a NonClosingIteratingInputStream.

Parameters:

pdfStream - the stream to read the PDF document that shall be analyzed

pwd - password to open the document if encrypted (may be null)

Throws:

java.io.IOException - if the stream can't be read

getSignatures

public abstract PdfSignatureDetails[] getSignatures()
                                             throws PdfSignatureException,
                                                    java.io.IOException

Extract all PDF signatures (approval and certification signatures) contained in the document. The position of the signatures in the array is in ascending order beginning with the first (oldest, innermost) and ending with the last (most current, outermost) signature. For further operations on the received signatures, detect the signature's type and call the respective methods, e.g. like this:

 PdfSignatureDetails[] signatures = signatureInstance.getSignatures();
 for (int i = 0; i < signatures.length; i++) {
   PdfSignatureDetails signature = signatures[i];
   if (signature instanceof ApprovalSignature) {
     ((ApprovalSignature) signature).verifySignatureValue();
     if (signature instanceof CertificationSignature) {
       ModificationPermission permissions = ((CertificationSignature) signature)
           .getModificationPermission();
     }
   } else if (signature instanceof DocumentTimestamp) {
     PadesLTVParameters ltvParams = ((DocumentTimestamp) signature).getLTVParams();
   }
 }
 

Returns:

all signatures as array

Throws:

PdfSignatureException - if no signed document has been specified with initVerify

java.io.IOException - if the document can't be read

getCertificationSignature

public abstract CertificationSignature getCertificationSignature()
                                                          throws PdfSignatureException,
                                                                 java.io.IOException

Extract the certification signature if included.

Returns:

The PDF signature implying the certification signature.

Throws:

PdfSignatureException - if more than one certification signature was found

java.io.IOException - if the document can't be read

verify

public void verify()
            throws PdfSignatureException,
                   java.io.IOException

Verifies the signature value of each contained signature. This is only a very rudimentary verification and should be extended or replaced using methods provided by each signature. An PdfSignatureException containing the revisions for the invalid signatures is thrown, if some signature values could not be verified.

Throws:

PdfSignatureException - if some signatures can't be parsed or are invalid

java.io.IOException - if the document or the signatures can't be read

See Also:

getSignatures()

getDocumentSecurityStore

public abstract PadesLTVParameters getDocumentSecurityStore()
                                                     throws PdfSignatureException,
                                                            java.io.IOException

Get all validation data included in the document security store (dss).

Returns:

the dss as ltv parameters

Throws:

PdfSignatureException - if some dss data can't be parsed

java.io.IOException - if some dss data can't be read

addArchivalTimestamp

public abstract void addArchivalTimestamp(java.lang.String tsaUrl,
                                          java.lang.String username,
                                          java.lang.String password,
                                          PadesLTVParameters params,
                                          java.lang.String newTimestampedFilePath)
                                   throws PdfSignatureException,
                                          iaik.tsp.TspVerificationException,
                                          java.io.IOException

Add the validation data contained in params to this document's DSS (document security store) as defined by PAdES-LTV (PAdES - long term validation). This validation data (certificates, CRLs, OCSP responses) shall be used at a later date to verify the included signatures, when external sources may no longer be available. After adding this data a document timestamp (requested from the given timestamp authority) is added, in order to protect the validation data.

Parameters:

tsaUrl - URL of the timestamp authority

username - username for authorization

password - password for authorization

params - parameters including the validation data to be added

newTimestampedFilePath - the file path where the new document containing the data and timestamp shall be saved

Throws:

PdfSignatureException - if the validation data can't be encoded or the timestamp can't be created

iaik.tsp.TspVerificationException - if errors occur when requesting and verifying the timestamp

java.io.IOException - if the validation data or the document timestamp can't be written

addArchivalTimestamp

public abstract void addArchivalTimestamp(java.lang.String tsaUrl,
                                          java.lang.String username,
                                          java.lang.String password,
                                          PadesLTVParameters params,
                                          java.lang.String newTimestampedFilePath,
                                          java.lang.String digestAlgorithm)
                                   throws PdfSignatureException,
                                          iaik.tsp.TspVerificationException,
                                          java.io.IOException

Add the validation data contained in params to this document's DSS (document security store) as defined by PAdES-LTV (PAdES - long term validation). This validation data (certificates, CRLs, OCSP responses) shall be used at a later date to verify the included signatures, when external sources may no longer be available. After adding this data a document timestamp (requested from the given timestamp authority) is added, in order to protect the validation data.

Parameters:

tsaUrl - URL of the timestamp authority

username - username for authorization

password - password for authorization

params - parameters including the validation data to be added

newTimestampedFilePath - the file path where the new document containing the data and timestamp shall be saved

digestAlgorithm - digest algorithm used to digest the timestamped data (timestamp imprint)

Throws:

PdfSignatureException - if the validation data can't be encoded or the timestamp can't be created

iaik.tsp.TspVerificationException - if errors occur when requesting and verifying the timestamp

java.io.IOException - if the validation data or the document timestamp can't be written

closeDocument

public abstract void closeDocument()

Close document instances that may still be open. Call this function, if this signature instance will not be used any more.

setCmsSecurityProvider

public static void setCmsSecurityProvider(iaik.cms.SecurityProvider cmsSecProvider)

Only calls SecurityProvider.setSecurityProvider(cmsSecProvider); to tell IAIK CMS which provider to use for signing. To use the PKCS#11 Provider, set the iaikPkcs11SecurityProvider delivered with the PKCS#11 Provider in the iaikPkcs11Provider_cms.jar file. To use the ECCelerate provider set the ECCelerateProvider contained in the iaik_eccelerate_cms.jar file of the ECCelerate package.

Parameters:

cmsSecProvider - the security provider to use

certificateInfosToText

public static java.lang.String certificateInfosToText(iaik.x509.X509Certificate cert,
                                                      java.util.Calendar signDate,
                                                      java.lang.String reason,
                                                      java.lang.String location)

Create a String of certificate and signature details.

Parameters:

cert - certificate of the signer

signDate - date of signature

reason - reason for signature

location - location of signature

Returns:

String with details about the signature