iText 8.0.5 API
iText.Signatures.PdfPKCS7 Class Reference

This class does all the processing related to signing and verifying a PKCS#7 / CMS signature. More...

Public Member Functions

  PdfPKCS7 (IPrivateKey privKey, IX509Certificate[] certChain, String hashAlgorithm, IExternalDigest interfaceDigest, bool hasEncapContent)
  Assembles all the elements needed to create a signature, except for the data. More...
 
  PdfPKCS7 (IPrivateKey privKey, IX509Certificate[] certChain, String hashAlgorithm, bool hasEncapContent)
  Assembles all the elements needed to create a signature, except for the data. More...
 
  PdfPKCS7 (byte[] contentsKey, byte[] certsKey)
  Use this constructor if you want to verify a signature using the sub-filter adbe.x509.rsa_sha1. More...
 
  PdfPKCS7 (byte[] contentsKey, PdfName filterSubtype)
  Use this constructor if you want to verify a signature. More...
 
virtual void  SetSignaturePolicy (SignaturePolicyInfo signaturePolicy)
  Set signature policy identifier to be used during signature creation. More...
 
virtual void  SetSignaturePolicy (ISignaturePolicyIdentifier signaturePolicy)
  Set signature policy identifier to be used during signature creation. More...
 
virtual String  GetSignName ()
  Getter for property sigName. More...
 
virtual void  SetSignName (String signName)
  Setter for property sigName. More...
 
virtual String  GetReason ()
  Getter for property reason. More...
 
virtual void  SetReason (String reason)
  Setter for property reason. More...
 
virtual String  GetLocation ()
  Getter for property location. More...
 
virtual void  SetLocation (String location)
  Setter for property location. More...
 
virtual DateTime  GetSignDate ()
  Getter for property signDate. More...
 
virtual void  SetSignDate (DateTime signDate)
  Setter for property signDate. More...
 
virtual int  GetVersion ()
  Get the version of the PKCS#7 object. More...
 
virtual int  GetSigningInfoVersion ()
  Get the version of the PKCS#7 "SignerInfo" object. More...
 
virtual String  GetDigestAlgorithmOid ()
  Getter for the ID of the digest algorithm, e.g. "2.16.840.1.101.3.4.2.1". More...
 
virtual String  GetDigestAlgorithmName ()
  Returns the name of the digest algorithm, e.g. "SHA256". More...
 
virtual String  GetSignatureMechanismOid ()
  Getter for the signature algorithm OID. More...
 
virtual String  GetSignatureMechanismName ()
  Get the signature mechanism identifier, including both the digest function and the signature algorithm, e.g. "SHA1withRSA". More...
 
virtual String  GetSignatureAlgorithmName ()
  Returns the name of the signature algorithm only (disregarding the digest function, if any). More...
 
virtual void  SetExternalSignatureValue (byte[] signatureValue, byte[] signedMessageContent, String signatureAlgorithm)
  Sets the signature to an externally calculated value. More...
 
virtual void  SetExternalSignatureValue (byte[] signatureValue, byte[] signedMessageContent, String signatureAlgorithm, ISignatureMechanismParams signatureMechanismParams)
  Sets the signature to an externally calculated value. More...
 
virtual void  Update (byte[] buf, int off, int len)
  Update the digest with the specified bytes. More...
 
virtual byte[]  GetEncodedPKCS1 ()
  Gets the bytes for the PKCS#1 object. More...
 
virtual byte[]  GetEncodedPKCS7 ()
  Gets the bytes for the PKCS7SignedData object. More...
 
virtual byte[]  GetEncodedPKCS7 (byte[] secondDigest)
  Gets the bytes for the PKCS7SignedData object. More...
 
virtual byte[]  GetEncodedPKCS7 (byte[] secondDigest, PdfSigner.CryptoStandard sigtype, ITSAClient tsaClient, ICollection< byte[]> ocsp, ICollection< byte[]> crlBytes)
  Gets the bytes for the PKCS7SignedData object. More...
 
virtual byte[]  GetAuthenticatedAttributeBytes (byte[] secondDigest, PdfSigner.CryptoStandard sigtype, ICollection< byte[]> ocsp, ICollection< byte[]> crlBytes)
  When using authenticatedAttributes the authentication process is different. More...
 
virtual bool  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. More...
 
virtual bool  VerifyTimestampImprint ()
  Checks if the timestamp refers to this document. More...
 
virtual IX509Certificate[]  GetCertificates ()
  Get all the X.509 certificates associated with this PKCS#7 object in no particular order. More...
 
virtual IX509Certificate[]  GetTimestampCertificates ()
  Get all X.509 certificates associated with this PKCS#7 object timestamp in no particular order. More...
 
virtual IX509Certificate[]  GetSignCertificateChain ()
  Get the X.509 sign certificate chain associated with this PKCS#7 object. More...
 
virtual IX509Certificate  GetSigningCertificate ()
  Get the X.509 certificate actually used to sign the digest. More...
 
virtual ICollection< IX509Crl GetCRLs ()
  Get the X.509 certificate revocation lists associated with this PKCS#7 object (stored in Signer Info). More...
 
virtual ICollection< IX509Crl GetSignedDataCRLs ()
  Get the X.509 certificate revocation lists associated with this PKCS#7 Signed Data object. More...
 
virtual ICollection< IBasicOcspResponse GetSignedDataOcsps ()
  Gets the OCSP basic response collection retrieved from SignedData structure. More...
 
virtual IBasicOcspResponse  GetOcsp ()
  Gets the OCSP basic response from the SignerInfo if there is one. More...
 
virtual bool  IsRevocationValid ()
  Checks if OCSP revocation refers to the document signing certificate. More...
 
virtual bool  IsTsp ()
  Check if it's a PAdES-LTV time stamp. More...
 
virtual iText.Signatures.PdfPKCS7  GetTimestampSignatureContainer ()
  Retrieves inner timestamp signature container if there is one. More...
 
virtual ITstInfo  GetTimeStampTokenInfo ()
  Gets the timestamp token info if there is one. More...
 
virtual DateTime  GetTimeStampDate ()
  Gets the timestamp date. More...
 
virtual PdfName  GetFilterSubtype ()
  Getter for the filter subtype. More...
 

Detailed Description

This class does all the processing related to signing and verifying a PKCS#7 / CMS signature.

Constructor & Destructor Documentation

◆ PdfPKCS7() [1/4]

iText.Signatures.PdfPKCS7.PdfPKCS7 ( IPrivateKey  privKey,
IX509Certificate[]  certChain,
String  hashAlgorithm,
IExternalDigest  interfaceDigest,
bool  hasEncapContent 
)
inline

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
hasEncapContent true if the sub-filter is adbe.pkcs7.sha1

◆ PdfPKCS7() [2/4]

iText.Signatures.PdfPKCS7.PdfPKCS7 ( IPrivateKey  privKey,
IX509Certificate[]  certChain,
String  hashAlgorithm,
bool  hasEncapContent 
)
inline

Assembles all the elements needed to create a signature, except for the data.

Parameters
privKey the private key
certChain the certificate chain
hashAlgorithm the hash algorithm
provider the provider or null for the default provider
hasEncapContent true if the sub-filter is adbe.pkcs7.sha1

◆ PdfPKCS7() [3/4]

iText.Signatures.PdfPKCS7.PdfPKCS7 ( byte[]  contentsKey,
byte[]  certsKey 
)
inline

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() [4/4]

iText.Signatures.PdfPKCS7.PdfPKCS7 ( byte[]  contentsKey,
PdfName  filterSubtype 
)
inline

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

Member Function Documentation

◆ GetAuthenticatedAttributeBytes()

virtual byte [] iText.Signatures.PdfPKCS7.GetAuthenticatedAttributeBytes ( byte[]  secondDigest,
PdfSigner.CryptoStandard  sigtype,
ICollection< byte[]>  ocsp,
ICollection< byte[]>  crlBytes 
)
inlinevirtual

When using authenticatedAttributes the authentication process is different.

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 IBasicOCSPResponse 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

RFC 6960 § 4.2.1

◆ GetCertificates()

virtual IX509Certificate [] iText.Signatures.PdfPKCS7.GetCertificates ( )
inlinevirtual

Get all the X.509 certificates associated with this PKCS#7 object in no particular order.

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

◆ GetCRLs()

virtual ICollection<IX509Crl> iText.Signatures.PdfPKCS7.GetCRLs ( )
inlinevirtual

Get the X.509 certificate revocation lists associated with this PKCS#7 object (stored in Signer Info).

Returns
the X.509 certificate revocation lists associated with this PKCS#7 object.

◆ GetDigestAlgorithmName()

virtual String iText.Signatures.PdfPKCS7.GetDigestAlgorithmName ( )
inlinevirtual

Returns the name of the digest algorithm, e.g. "SHA256".

Returns
the digest algorithm name, e.g. "SHA256"

◆ GetDigestAlgorithmOid()

virtual String iText.Signatures.PdfPKCS7.GetDigestAlgorithmOid ( )
inlinevirtual

Getter for the ID of the digest algorithm, e.g. "2.16.840.1.101.3.4.2.1".

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

◆ GetEncodedPKCS1()

virtual byte [] iText.Signatures.PdfPKCS7.GetEncodedPKCS1 ( )
inlinevirtual

Gets the bytes for the PKCS#1 object.

Returns
a byte array

◆ GetEncodedPKCS7() [1/3]

virtual byte [] iText.Signatures.PdfPKCS7.GetEncodedPKCS7 ( )
inlinevirtual

Gets the bytes for the PKCS7SignedData object.

Returns
the bytes for the PKCS7SignedData object

◆ GetEncodedPKCS7() [2/3]

virtual byte [] iText.Signatures.PdfPKCS7.GetEncodedPKCS7 ( byte[]  secondDigest )
inlinevirtual

Gets the bytes for the PKCS7SignedData object.

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() [3/3]

virtual byte [] iText.Signatures.PdfPKCS7.GetEncodedPKCS7 ( byte[]  secondDigest,
PdfSigner.CryptoStandard  sigtype,
ITSAClient  tsaClient,
ICollection< byte[]>  ocsp,
ICollection< byte[]>  crlBytes 
)
inlinevirtual

Gets the bytes for the PKCS7SignedData object.

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.

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

RFC 6960 § 4.2.1

◆ GetFilterSubtype()

virtual PdfName iText.Signatures.PdfPKCS7.GetFilterSubtype ( )
inlinevirtual

Getter for the filter subtype.

Returns
the filter subtype

◆ GetLocation()

virtual String iText.Signatures.PdfPKCS7.GetLocation ( )
inlinevirtual

Getter for property location.

Returns
Value of property location.

◆ GetOcsp()

virtual IBasicOcspResponse iText.Signatures.PdfPKCS7.GetOcsp ( )
inlinevirtual

Gets the OCSP basic response from the SignerInfo if there is one.

Returns
the OCSP basic response or null.

◆ GetReason()

virtual String iText.Signatures.PdfPKCS7.GetReason ( )
inlinevirtual

Getter for property reason.

Returns
Value of property reason.

◆ GetSignatureAlgorithmName()

virtual String iText.Signatures.PdfPKCS7.GetSignatureAlgorithmName ( )
inlinevirtual

Returns the name of the signature algorithm only (disregarding the digest function, if any).

Returns
the name of an encryption algorithm

◆ GetSignatureMechanismName()

virtual String iText.Signatures.PdfPKCS7.GetSignatureMechanismName ( )
inlinevirtual

Get the signature mechanism identifier, including both the digest function and the signature algorithm, e.g. "SHA1withRSA".

Get the signature mechanism identifier, including both the digest function and the signature algorithm, 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 signature

◆ GetSignatureMechanismOid()

virtual String iText.Signatures.PdfPKCS7.GetSignatureMechanismOid ( )
inlinevirtual

Getter for the signature algorithm OID.

Getter for the signature algorithm OID. See ISO-32000-1, section 12.8.3.3 PKCS#7 Signatures as used in ISO 32000

Returns
the signature algorithm OID

◆ GetSignCertificateChain()

virtual IX509Certificate [] iText.Signatures.PdfPKCS7.GetSignCertificateChain ( )
inlinevirtual

Get the X.509 sign certificate chain associated with this PKCS#7 object.

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

◆ GetSignDate()

virtual DateTime iText.Signatures.PdfPKCS7.GetSignDate ( )
inlinevirtual

Getter for property signDate.

Returns
Value of property signDate.

◆ GetSignedDataCRLs()

virtual ICollection<IX509Crl> iText.Signatures.PdfPKCS7.GetSignedDataCRLs ( )
inlinevirtual

Get the X.509 certificate revocation lists associated with this PKCS#7 Signed Data object.

Returns
the X.509 certificate revocation lists associated with this PKCS#7 Signed Data object.

◆ GetSignedDataOcsps()

virtual ICollection<IBasicOcspResponse> iText.Signatures.PdfPKCS7.GetSignedDataOcsps ( )
inlinevirtual

Gets the OCSP basic response collection retrieved from SignedData structure.

Returns
the OCSP basic response collection.

◆ GetSigningCertificate()

virtual IX509Certificate iText.Signatures.PdfPKCS7.GetSigningCertificate ( )
inlinevirtual

Get the X.509 certificate actually used to sign the digest.

Returns
the X.509 certificate actually used to sign the digest

◆ GetSigningInfoVersion()

virtual int iText.Signatures.PdfPKCS7.GetSigningInfoVersion ( )
inlinevirtual

Get the version of the PKCS#7 "SignerInfo" object.

Returns
the version of the PKCS#7 "SignerInfo" object.

◆ GetSignName()

virtual String iText.Signatures.PdfPKCS7.GetSignName ( )
inlinevirtual

Getter for property sigName.

Returns
Value of property sigName.

◆ GetTimestampCertificates()

virtual IX509Certificate [] iText.Signatures.PdfPKCS7.GetTimestampCertificates ( )
inlinevirtual

Get all X.509 certificates associated with this PKCS#7 object timestamp in no particular order.

Returns

Certificate[]

array

◆ GetTimeStampDate()

virtual DateTime iText.Signatures.PdfPKCS7.GetTimeStampDate ( )
inlinevirtual

Gets the timestamp date.

Gets the timestamp date.

In case the signed document doesn't contain timestamp, TimestampConstants.UNDEFINED_TIMESTAMP_DATE will be returned.

Returns
the timestamp date

◆ GetTimestampSignatureContainer()

virtual iText.Signatures.PdfPKCS7 iText.Signatures.PdfPKCS7.GetTimestampSignatureContainer ( )
inlinevirtual

Retrieves inner timestamp signature container if there is one.

Returns
timestamp signature container or null.

◆ GetTimeStampTokenInfo()

virtual ITstInfo iText.Signatures.PdfPKCS7.GetTimeStampTokenInfo ( )
inlinevirtual

Gets the timestamp token info if there is one.

Returns
the timestamp token info or null

◆ GetVersion()

virtual int iText.Signatures.PdfPKCS7.GetVersion ( )
inlinevirtual

Get the version of the PKCS#7 object.

Returns
the version of the PKCS#7 object.

◆ IsRevocationValid()

virtual bool iText.Signatures.PdfPKCS7.IsRevocationValid ( )
inlinevirtual

Checks if OCSP revocation refers to the document signing certificate.

Returns
true if it checks, false otherwise

◆ IsTsp()

virtual bool iText.Signatures.PdfPKCS7.IsTsp ( )
inlinevirtual

Check if it's a PAdES-LTV time stamp.

Returns
true if it's a PAdES-LTV time stamp, false otherwise

◆ SetExternalSignatureValue() [1/2]

virtual void iText.Signatures.PdfPKCS7.SetExternalSignatureValue ( byte[]  signatureValue,
byte[]  signedMessageContent,
String  signatureAlgorithm 
)
inlinevirtual

Sets the signature to an externally calculated value.

Parameters
signatureValue the signature value
signedMessageContent the extra data that goes into the data tag in PKCS#7
signatureAlgorithm the signature algorithm. It must be null if the signatureValue is also null. If the signatureValue is not null, possible values include "RSA", "DSA", "ECDSA", "Ed25519" and "Ed448".

◆ SetExternalSignatureValue() [2/2]

virtual void iText.Signatures.PdfPKCS7.SetExternalSignatureValue ( byte[]  signatureValue,
byte[]  signedMessageContent,
String  signatureAlgorithm,
ISignatureMechanismParams  signatureMechanismParams 
)
inlinevirtual

Sets the signature to an externally calculated value.

Parameters
signatureValue the signature value
signedMessageContent the extra data that goes into the data tag in PKCS#7
signatureAlgorithm the signature algorithm. It must be null if the signatureValue is also null. If the signatureValue is not null, possible values include "RSA", "RSASSA-PSS", "DSA", "ECDSA", "Ed25519" and "Ed448".
signatureMechanismParams parameters for the signature mechanism, if required

◆ SetLocation()

virtual void iText.Signatures.PdfPKCS7.SetLocation ( String  location )
inlinevirtual

Setter for property location.

Parameters
location New value of property location.

◆ SetReason()

virtual void iText.Signatures.PdfPKCS7.SetReason ( String  reason )
inlinevirtual

Setter for property reason.

Parameters
reason New value of property reason.

◆ SetSignaturePolicy() [1/2]

virtual void iText.Signatures.PdfPKCS7.SetSignaturePolicy ( ISignaturePolicyIdentifier  signaturePolicy )
inlinevirtual

Set signature policy identifier to be used during signature creation.

Parameters
signaturePolicy

iText.Commons.Bouncycastle.Asn1.Esf.ISignaturePolicyIdentifier to be used during signature creation

◆ SetSignaturePolicy() [2/2]

virtual void iText.Signatures.PdfPKCS7.SetSignaturePolicy ( SignaturePolicyInfo  signaturePolicy )
inlinevirtual

Set signature policy identifier to be used during signature creation.

Parameters
signaturePolicy

SignaturePolicyInfo to be used during signature creation

◆ SetSignDate()

virtual void iText.Signatures.PdfPKCS7.SetSignDate ( DateTime  signDate )
inlinevirtual

Setter for property signDate.

Parameters
signDate New value of property signDate.

◆ SetSignName()

virtual void iText.Signatures.PdfPKCS7.SetSignName ( String  signName )
inlinevirtual

Setter for property sigName.

Parameters
signName New value of property sigName.

◆ Update()

virtual void iText.Signatures.PdfPKCS7.Update ( byte[]  buf,
int  off,
int  len 
)
inlinevirtual

Update the digest with the specified bytes.

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

◆ VerifySignatureIntegrityAndAuthenticity()

virtual bool iText.Signatures.PdfPKCS7.VerifySignatureIntegrityAndAuthenticity ( )
inlinevirtual

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.

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 iText.Kernel.Pdf.PdfDocument please use SignatureUtil.SignatureCoversWholeDocument(System.String) method.

Returns
true if the signature checks out, false otherwise

◆ VerifyTimestampImprint()

virtual bool iText.Signatures.PdfPKCS7.VerifyTimestampImprint ( )
inlinevirtual

Checks if the timestamp refers to this document.

Returns
true if it checks false otherwise