PdfPKCS7 (iText 7 7.1.19 API)

java.lang.Object
- com.itextpdf.signatures.PdfPKCS7

```
public class PdfPKCS7
extends Object
```
This class does all the processing related to signing and verifying a PKCS#7 signature.

Constructor Summary

Constructors
Constructor and Description
`PdfPKCS7(byte[] contentsKey, byte[] certsKey, String provider)` Use this constructor if you want to verify a signature using the sub-filter adbe.x509.rsa_sha1.
`PdfPKCS7(byte[] contentsKey, PdfName filterSubtype, String provider)` Use this constructor if you want to verify a signature.
`PdfPKCS7(PrivateKey privKey, Certificate[] certChain, String hashAlgorithm, String provider, IExternalDigest interfaceDigest, boolean hasRSAdata)` Assembles all the elements needed to create a signature, except for the data.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`byte[]`	`getAuthenticatedAttributeBytes(byte[] secondDigest, byte[] ocsp, Collection crlBytes, PdfSigner.CryptoStandard sigtype)` Deprecated. This method overload is deprecated. Please use `getAuthenticatedAttributeBytes(byte[], PdfSigner.CryptoStandard, Collection, Collection)`
`byte[]`	`getAuthenticatedAttributeBytes(byte[] secondDigest, PdfSigner.CryptoStandard sigtype, Collection ocsp, Collection crlBytes)` When using authenticatedAttributes the authentication process is different.
`Certificate[]`	`getCertificates()` Get all the X.509 certificates associated with this PKCS#7 object in no particular order.
`Collection<CRL>`	`getCRLs()` Get the X.509 certificate revocation lists associated with this PKCS#7 object
`String`	`getDigestAlgorithm()` Get the algorithm used to calculate the message digest, e.g.
`String`	`getDigestAlgorithmOid()` Getter for the ID of the digest algorithm, e.g.
`String`	`getDigestEncryptionAlgorithmOid()` Getter for the digest encryption algorithm.
`byte[]`	`getEncodedPKCS1()` Gets the bytes for the PKCS#1 object.
`byte[]`	`getEncodedPKCS7()` Gets the bytes for the PKCS7SignedData object.
`byte[]`	`getEncodedPKCS7(byte[] secondDigest)` Gets the bytes for the PKCS7SignedData object.
`byte[]`	`getEncodedPKCS7(byte[] secondDigest, ITSAClient tsaClient, byte[] ocsp, Collection crlBytes, PdfSigner.CryptoStandard sigtype)` Deprecated. This overload is deprecated, use `getEncodedPKCS7(byte[], PdfSigner.CryptoStandard, ITSAClient, Collection, Collection)` instead.
`byte[]`	`getEncodedPKCS7(byte[] secondDigest, PdfSigner.CryptoStandard sigtype, ITSAClient tsaClient, Collection ocsp, Collection crlBytes)` Gets the bytes for the PKCS7SignedData object.
`String`	`getEncryptionAlgorithm()` Returns the encryption algorithm
`PdfName`	`getFilterSubtype()` Getter for the filter subtype.
`String`	`getHashAlgorithm()` Returns the name of the digest algorithm, e.g.
`String`	`getLocation()` Getter for property location.
`org.bouncycastle.cert.ocsp.BasicOCSPResp`	`getOcsp()` Gets the OCSP basic response if there is one.
`String`	`getReason()` Getter for property reason.
`Certificate[]`	`getSignCertificateChain()` Get the X.509 sign certificate chain associated with this PKCS#7 object.
`Calendar`	`getSignDate()` Getter for property signDate.
`X509Certificate`	`getSigningCertificate()` Get the X.509 certificate actually used to sign the digest.
`int`	`getSigningInfoVersion()` Get the version of the PKCS#7 "SignerInfo" object.
`String`	`getSignName()` Getter for property sigName.
`Calendar`	`getTimeStampDate()` Gets the timestamp date.
`org.bouncycastle.tsp.TimeStampToken`	`getTimeStampToken()` Gets the timestamp token if there is one.
`int`	`getVersion()` Get the version of the PKCS#7 object.
`boolean`	`isRevocationValid()` Checks if OCSP revocation refers to the document signing certificate.
`boolean`	`isTsp()` Check if it's a PAdES-LTV time stamp.
`void`	`setExternalDigest(byte[] digest, byte[] rsaData, String digestEncryptionAlgorithm)` Sets the digest/signature to an external calculated value.
`void`	`setLocation(String location)` Setter for property location.
`void`	`setReason(String reason)` Setter for property reason.
`void`	`setSignaturePolicy(org.bouncycastle.asn1.esf.SignaturePolicyIdentifier signaturePolicy)`
`void`	`setSignaturePolicy(SignaturePolicyInfo signaturePolicy)`
`void`	`setSignDate(Calendar signDate)` Setter for property signDate.
`void`	`setSignName(String signName)` Setter for property sigName.
`void`	`update(byte[] buf, int off, int len)` Update the digest with the specified bytes.
`boolean`	`verify()` Deprecated. This method will be removed in future versions. Please use `verifySignatureIntegrityAndAuthenticity()` instead.
`boolean`	`verifySignatureIntegrityAndAuthenticity()` Verifies that signature integrity is intact (or in other words that signed data wasn't modified) by checking that embedded data digest corresponds to the calculated one.
`boolean`	`verifyTimestampImprint()` Checks if the timestamp refers to this document.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - PdfPKCS7
```
public PdfPKCS7(PrivateKey privKey,
                Certificate[] certChain,
                String hashAlgorithm,
                String provider,
                IExternalDigest interfaceDigest,
                boolean hasRSAdata)
         throws InvalidKeyException,
                NoSuchProviderException,
                NoSuchAlgorithmException
```
    Assembles all the elements needed to create a signature, except for the data.
    
    Parameters:
    
    privKey - the private key
    
    certChain - the certificate chain
    
    interfaceDigest - the interface digest
    
    hashAlgorithm - the hash algorithm
    
    provider - the provider or null for the default provider
    
    hasRSAdata - true if the sub-filter is adbe.pkcs7.sha1
    
    Throws:
    
    InvalidKeyException - on error
    
    NoSuchProviderException - on error
    
    NoSuchAlgorithmException - on error
  - PdfPKCS7
```
public PdfPKCS7(byte[] contentsKey,
                byte[] certsKey,
                String provider)
```
    Use this constructor if you want to verify a signature using the sub-filter adbe.x509.rsa_sha1.
    
    Parameters:
    
    contentsKey - the /Contents key
    
    certsKey - the /Cert key
    
    provider - the provider or null for the default provider
  - PdfPKCS7
```
public PdfPKCS7(byte[] contentsKey,
                PdfName filterSubtype,
                String provider)
```
    Use this constructor if you want to verify a signature.
    
    Parameters:
    
    contentsKey - the /Contents key
    
    filterSubtype - the filtersubtype
    
    provider - the provider or null for the default provider
- Method Detail
  - setSignaturePolicy
```
public void setSignaturePolicy(SignaturePolicyInfo signaturePolicy)
```
  - setSignaturePolicy
```
public void setSignaturePolicy(org.bouncycastle.asn1.esf.SignaturePolicyIdentifier signaturePolicy)
```
  - getSignName
```
public String getSignName()
```
    Getter for property sigName.
    
    Returns:
    
    Value of property sigName.
  - setSignName
```
public void setSignName(String signName)
```
    Setter for property sigName.
    
    Parameters:
    
    signName - New value of property sigName.
  - getReason
```
public String getReason()
```
    Getter for property reason.
    
    Returns:
    
    Value of property reason.
  - setReason
```
public void setReason(String reason)
```
    Setter for property reason.
    
    Parameters:
    
    reason - New value of property reason.
  - getLocation
```
public String getLocation()
```
    Getter for property location.
    
    Returns:
    
    Value of property location.
  - setLocation
```
public void setLocation(String location)
```
    Setter for property location.
    
    Parameters:
    
    location - New value of property location.
  - getSignDate
```
public Calendar getSignDate()
```
    Getter for property signDate.
    
    Returns:
    
    Value of property signDate.
  - setSignDate
```
public void setSignDate(Calendar signDate)
```
    Setter for property signDate.
    
    Parameters:
    
    signDate - New value of property signDate.
  - getVersion
```
public int getVersion()
```
    Get the version of the PKCS#7 object.
    
    Returns:
    
    the version of the PKCS#7 object.
  - getSigningInfoVersion
```
public int getSigningInfoVersion()
```
    Get the version of the PKCS#7 "SignerInfo" object.
    
    Returns:
    
    the version of the PKCS#7 "SignerInfo" object.
  - getDigestAlgorithmOid
```
public String getDigestAlgorithmOid()
```
    Getter for the ID of the digest algorithm, e.g. "2.16.840.1.101.3.4.2.1". See ISO-32000-1, section 12.8.3.3 PKCS#7 Signatures as used in ISO 32000
    
    Returns:
    
    the ID of the digest algorithm
  - getHashAlgorithm
```
public String getHashAlgorithm()
```
    Returns the name of the digest algorithm, e.g. "SHA256".
    
    Returns:
    
    the digest algorithm name, e.g. "SHA256"
  - getDigestEncryptionAlgorithmOid
```
public String getDigestEncryptionAlgorithmOid()
```
    Getter for the digest encryption algorithm. See ISO-32000-1, section 12.8.3.3 PKCS#7 Signatures as used in ISO 32000
    
    Returns:
    
    the encryption algorithm
  - getDigestAlgorithm
```
public String getDigestAlgorithm()
```
    Get the algorithm used to calculate the message digest, e.g. "SHA1withRSA". See ISO-32000-1, section 12.8.3.3 PKCS#7 Signatures as used in ISO 32000
    
    Returns:
    
    the algorithm used to calculate the message digest
  - setExternalDigest
```
public void setExternalDigest(byte[] digest,
                              byte[] rsaData,
                              String digestEncryptionAlgorithm)
```
    Sets the digest/signature to an external calculated value.
    
    Parameters:
    
    digest - the digest. This is the actual signature
    
    rsaData - the extra data that goes into the data tag in PKCS#7
    
    digestEncryptionAlgorithm - the encryption algorithm. It may must be null if the digest is also null. If the digest is not null then it may be "RSA" or "DSA"
  - update
```
public void update(byte[] buf,
                   int off,
                   int len)
            throws SignatureException
```
    Update the digest with the specified bytes. This method is used both for signing and verifying
    
    Parameters:
    
    buf - the data buffer
    
    off - the offset in the data buffer
    
    len - the data length
    
    Throws:
    
    SignatureException - on error
  - getEncodedPKCS1
```
public byte[] getEncodedPKCS1()
```
    Gets the bytes for the PKCS#1 object.
    
    Returns:
    
    a byte array
  - getEncodedPKCS7
```
public byte[] getEncodedPKCS7()
```
    Gets the bytes for the PKCS7SignedData object.
    
    Returns:
    
    the bytes for the PKCS7SignedData object
  - getEncodedPKCS7
```
public byte[] getEncodedPKCS7(byte[] secondDigest)
```
    Gets the bytes for the PKCS7SignedData object. Optionally the authenticatedAttributes in the signerInfo can also be set. If either of the parameters is null, none will be used.
    
    Parameters:
    
    secondDigest - the digest in the authenticatedAttributes
    
    Returns:
    
    the bytes for the PKCS7SignedData object
  - getEncodedPKCS7
```
@Deprecated
public byte[] getEncodedPKCS7(byte[] secondDigest,
                                          ITSAClient tsaClient,
                                          byte[] ocsp,
                                          Collection crlBytes,
                                          PdfSigner.CryptoStandard sigtype)
```
    Deprecated. This overload is deprecated, use getEncodedPKCS7(byte[], PdfSigner.CryptoStandard, ITSAClient, Collection, Collection) instead.
    
    Gets the bytes for the PKCS7SignedData object. Optionally the authenticatedAttributes in the signerInfo can also be set, and/or a time-stamp-authority client may be provided.
    Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder, only the DER-encoded BasicOCSPResponse value contained in the response data.
    
    Parameters:
    
    secondDigest - the digest in the authenticatedAttributes
    
    tsaClient - TSAClient - null or an optional time stamp authority client
    
    ocsp - DER-encoded BasicOCSPResponse for the first certificate in the signature certificates chain, or null if OCSP revocation data is not to be added.
    
    crlBytes - collection of DER-encoded CRL for certificates from the signature certificates chain, or null if CRL revocation data is not to be added.
    
    sigtype - specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
    
    Returns:
    
    byte[] the bytes for the PKCS7SignedData object
    
    See Also:
    
    RFC 6960 § 4.2.1
  - getEncodedPKCS7
```
public byte[] getEncodedPKCS7(byte[] secondDigest,
                              PdfSigner.CryptoStandard sigtype,
                              ITSAClient tsaClient,
                              Collection ocsp,
                              Collection crlBytes)
```
    Gets the bytes for the PKCS7SignedData object. Optionally the authenticatedAttributes in the signerInfo can also be set, and/or a time-stamp-authority client may be provided.
    Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder, only the DER-encoded BasicOCSPResponse value contained in the response data.
    
    Parameters:
    
    secondDigest - the digest in the authenticatedAttributes
    
    sigtype - specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
    
    tsaClient - TSAClient - null or an optional time stamp authority client
    
    ocsp - collection of DER-encoded BasicOCSPResponses for the certificate in the signature certificates chain, or null if OCSP revocation data is not to be added.
    
    crlBytes - collection of DER-encoded CRL for certificates from the signature certificates chain, or null if CRL revocation data is not to be added.
    
    Returns:
    
    byte[] the bytes for the PKCS7SignedData object
    
    See Also:
    
    RFC 6960 § 4.2.1
  - getAuthenticatedAttributeBytes
```
@Deprecated
public byte[] getAuthenticatedAttributeBytes(byte[] secondDigest,
                                                         byte[] ocsp,
                                                         Collection crlBytes,
                                                         PdfSigner.CryptoStandard sigtype)
```
    Deprecated. This method overload is deprecated. Please use getAuthenticatedAttributeBytes(byte[], PdfSigner.CryptoStandard, Collection, Collection)
    When using authenticatedAttributes the authentication process is different. The document digest is generated and put inside the attribute. The signing is done over the DER encoded authenticatedAttributes. This method provides that encoding and the parameters must be exactly the same as in getEncodedPKCS7(byte[]).
    Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder, only the DER-encoded BasicOCSPResponse value contained in the response data.
    
    A simple example:
```
 Calendar cal = Calendar.getInstance();
 PdfPKCS7 pk7 = new PdfPKCS7(key, chain, null, "SHA1", null, false);
 MessageDigest messageDigest = MessageDigest.getInstance("SHA1");
 byte[] buf = new byte[8192];
 int n;
 InputStream inp = sap.getRangeStream();
 while ((n = inp.read(buf)) > 0) {
    messageDigest.update(buf, 0, n);
 }
 byte[] hash = messageDigest.digest();
 byte[] sh = pk7.getAuthenticatedAttributeBytes(hash, cal);
 pk7.update(sh, 0, sh.length);
 byte[] sg = pk7.getEncodedPKCS7(hash, cal);
 
```
    Parameters:
    
    secondDigest - the content digest
    
    ocsp - collection of DER-encoded BasicOCSPResponses for the certificate in the signature certificates chain, or null if OCSP revocation data is not to be added.
    
    crlBytes - collection of DER-encoded CRL for certificates from the signature certificates chain, or null if CRL revocation data is not to be added.
    
    sigtype - specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
    
    Returns:
    
    the byte array representation of the authenticatedAttributes ready to be signed
    
    See Also:
    
    RFC 6960 § 4.2.1
  - getAuthenticatedAttributeBytes
```
public byte[] getAuthenticatedAttributeBytes(byte[] secondDigest,
                                             PdfSigner.CryptoStandard sigtype,
                                             Collection ocsp,
                                             Collection crlBytes)
```
    When using authenticatedAttributes the authentication process is different. The document digest is generated and put inside the attribute. The signing is done over the DER encoded authenticatedAttributes. This method provides that encoding and the parameters must be exactly the same as in getEncodedPKCS7(byte[]).
    Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder, only the DER-encoded BasicOCSPResponse value contained in the response data.
    
    A simple example:
```
 Calendar cal = Calendar.getInstance();
 PdfPKCS7 pk7 = new PdfPKCS7(key, chain, null, "SHA1", null, false);
 MessageDigest messageDigest = MessageDigest.getInstance("SHA1");
 byte[] buf = new byte[8192];
 int n;
 InputStream inp = sap.getRangeStream();
 while ((n = inp.read(buf)) > 0) {
    messageDigest.update(buf, 0, n);
 }
 byte[] hash = messageDigest.digest();
 byte[] sh = pk7.getAuthenticatedAttributeBytes(hash, cal);
 pk7.update(sh, 0, sh.length);
 byte[] sg = pk7.getEncodedPKCS7(hash, cal);
 
```
    Parameters:
    
    secondDigest - the content digest
    
    sigtype - specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
    
    ocsp - collection of DER-encoded BasicOCSPResponses for the certificate in the signature certificates chain, or null if OCSP revocation data is not to be added.
    
    crlBytes - collection of DER-encoded CRL for certificates from the signature certificates chain, or null if CRL revocation data is not to be added.
    
    Returns:
    
    the byte array representation of the authenticatedAttributes ready to be signed
    
    See Also:
    
    RFC 6960 § 4.2.1
  - verify
```
@Deprecated
public boolean verify()
                           throws GeneralSecurityException
```
    Deprecated. This method will be removed in future versions. Please use verifySignatureIntegrityAndAuthenticity() instead.
    
    Verify the digest.
    
    Returns:
    
    true if the signature checks out, false otherwise
    
    Throws:
    
    GeneralSecurityException - if this signature object is not initialized properly, the passed-in signature is improperly encoded or of the wrong type, if this signature algorithm is unable to process the input data provided, if the public key is invalid or if security provider or signature algorithm are not recognized, etc.
  - verifySignatureIntegrityAndAuthenticity
```
public boolean verifySignatureIntegrityAndAuthenticity()
                                                throws GeneralSecurityException
```
    Verifies that signature integrity is intact (or in other words that signed data wasn't modified) by checking that embedded data digest corresponds to the calculated one. Also ensures that signature is genuine and is created by the owner of private key that corresponds to the declared public certificate.
    Even though signature can be authentic and signed data integrity can be intact, one shall also always check that signed data is not only a part of PDF contents but is actually a complete PDF file. In order to check that given signature covers the current PdfDocument please use SignatureUtil.signatureCoversWholeDocument(String) method.
    
    Returns:
    
    true if the signature checks out, false otherwise
    
    Throws:
    
    GeneralSecurityException - if this signature object is not initialized properly, the passed-in signature is improperly encoded or of the wrong type, if this signature algorithm is unable to process the input data provided, if the public key is invalid or if security provider or signature algorithm are not recognized, etc.
  - verifyTimestampImprint
```
public boolean verifyTimestampImprint()
                               throws GeneralSecurityException
```
    Checks if the timestamp refers to this document.
    
    Returns:
    
    true if it checks false otherwise
    
    Throws:
    
    GeneralSecurityException - on error
  - getCertificates
```
public Certificate[] getCertificates()
```
    Get all the X.509 certificates associated with this PKCS#7 object in no particular order. Other certificates, from OCSP for example, will also be included.
    
    Returns:
    
    the X.509 certificates associated with this PKCS#7 object
  - getSignCertificateChain
```
public Certificate[] getSignCertificateChain()
```
    Get the X.509 sign certificate chain associated with this PKCS#7 object. Only the certificates used for the main signature will be returned, with the signing certificate first.
    
    Returns:
    
    the X.509 certificates associated with this PKCS#7 object
  - getSigningCertificate
```
public X509Certificate getSigningCertificate()
```
    Get the X.509 certificate actually used to sign the digest.
    
    Returns:
    
    the X.509 certificate actually used to sign the digest
  - getCRLs
```
public Collection<CRL> getCRLs()
```
    Get the X.509 certificate revocation lists associated with this PKCS#7 object
    
    Returns:
    
    the X.509 certificate revocation lists associated with this PKCS#7 object
  - getOcsp
```
public org.bouncycastle.cert.ocsp.BasicOCSPResp getOcsp()
```
    Gets the OCSP basic response if there is one.
    
    Returns:
    
    the OCSP basic response or null
  - isRevocationValid
```
public boolean isRevocationValid()
```
    Checks if OCSP revocation refers to the document signing certificate.
    
    Returns:
    
    true if it checks, false otherwise
  - isTsp
```
public boolean isTsp()
```
    Check if it's a PAdES-LTV time stamp.
    
    Returns:
    
    true if it's a PAdES-LTV time stamp, false otherwise
  - getTimeStampToken
```
public org.bouncycastle.tsp.TimeStampToken getTimeStampToken()
```
    Gets the timestamp token if there is one.
    
    Returns:
    
    the timestamp token or null
  - getTimeStampDate
```
public Calendar getTimeStampDate()
```
    Gets the timestamp date. In case the signed document doesn't contain timestamp, TimestampConstants.UNDEFINED_TIMESTAMP_DATE will be returned.
    
    Returns:
    
    the timestamp date
  - getFilterSubtype
```
public PdfName getFilterSubtype()
```
    Getter for the filter subtype.
    
    Returns:
    
    the filter subtype
  - getEncryptionAlgorithm
```
public String getEncryptionAlgorithm()
```
    Returns the encryption algorithm
    
    Returns:
    
    the name of an encryption algorithm

Class PdfPKCS7

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PdfPKCS7

PdfPKCS7

PdfPKCS7

Method Detail

setSignaturePolicy

setSignaturePolicy

getSignName

setSignName

getReason

setReason

getLocation

setLocation

getSignDate

setSignDate

getVersion

getSigningInfoVersion

getDigestAlgorithmOid

getHashAlgorithm

getDigestEncryptionAlgorithmOid

getDigestAlgorithm

setExternalDigest

update

getEncodedPKCS1

getEncodedPKCS7

getEncodedPKCS7

getEncodedPKCS7

getEncodedPKCS7

getAuthenticatedAttributeBytes

getAuthenticatedAttributeBytes

verify

verifySignatureIntegrityAndAuthenticity

verifyTimestampImprint

getCertificates

getSignCertificateChain

getSigningCertificate

getCRLs

getOcsp

isRevocationValid

isTsp

getTimeStampToken

getTimeStampDate

getFilterSubtype

getEncryptionAlgorithm