Table of Contents

Class PdfPKCS7

Namespace
iText.Signatures
Assembly
itext.sign.dll

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

public class PdfPKCS7
Inheritance
PdfPKCS7
Inherited Members

Constructors

PdfPKCS7(byte[], byte[])

Use this constructor if you want to verify a signature using the sub-filter adbe.x509.rsa_sha1.

public PdfPKCS7(byte[] contentsKey, byte[] certsKey)

Parameters

contentsKey byte[]

the /Contents key

certsKey byte[]

the /Cert key

PdfPKCS7(byte[], PdfName)

Use this constructor if you want to verify a signature.

public PdfPKCS7(byte[] contentsKey, PdfName filterSubtype)

Parameters

contentsKey byte[]

the /Contents key

filterSubtype PdfName

the filtersubtype

PdfPKCS7(IPrivateKey, IX509Certificate[], string, bool)

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

public PdfPKCS7(IPrivateKey privKey, IX509Certificate[] certChain, string hashAlgorithm, bool hasEncapContent)

Parameters

privKey IPrivateKey

the private key

certChain IX509Certificate[]

the certificate chain

hashAlgorithm string

the hash algorithm

hasEncapContent bool

true if the sub-filter is adbe.pkcs7.sha1

PdfPKCS7(IPrivateKey, IX509Certificate[], string, IExternalDigest, bool)

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

public PdfPKCS7(IPrivateKey privKey, IX509Certificate[] certChain, string hashAlgorithm, IExternalDigest interfaceDigest, bool hasEncapContent)

Parameters

privKey IPrivateKey

the private key

certChain IX509Certificate[]

the certificate chain

hashAlgorithm string

the hash algorithm

interfaceDigest IExternalDigest

the interface digest

hasEncapContent bool

true if the sub-filter is adbe.pkcs7.sha1

Methods

GetAuthenticatedAttributeBytes(byte[], CryptoStandard, ICollection<byte[]>, ICollection<byte[]>)

When using authenticatedAttributes the authentication process is different.

public virtual byte[] GetAuthenticatedAttributeBytes(byte[] secondDigest, PdfSigner.CryptoStandard sigtype, ICollection<byte[]> ocsp, ICollection<byte[]> crlBytes)

Parameters

secondDigest byte[]

the content digest

sigtype PdfSigner.CryptoStandard

specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES

ocsp ICollection<byte[]>

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 ICollection<byte[]>

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 byte array representation of the authenticatedAttributes ready to be signed

Remarks

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);

GetCRLs()

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

public virtual ICollection<IX509Crl> GetCRLs()

Returns

ICollection<IX509Crl>

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

GetCertificates()

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

public virtual IX509Certificate[] GetCertificates()

Returns

IX509Certificate[]

the X.509 certificates associated with this PKCS#7 object

Remarks

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.

GetDigestAlgorithmName()

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

public virtual string GetDigestAlgorithmName()

Returns

string

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

GetDigestAlgorithmOid()

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

public virtual string GetDigestAlgorithmOid()

Returns

string

the ID of the digest algorithm

Remarks

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

GetEncodedPKCS1()

Gets the bytes for the PKCS#1 object.

public virtual byte[] GetEncodedPKCS1()

Returns

byte[]

a byte array

GetEncodedPKCS7()

Gets the bytes for the PKCS7SignedData object.

public virtual byte[] GetEncodedPKCS7()

Returns

byte[]

the bytes for the PKCS7SignedData object

GetEncodedPKCS7(byte[])

Gets the bytes for the PKCS7SignedData object.

public virtual byte[] GetEncodedPKCS7(byte[] secondDigest)

Parameters

secondDigest byte[]

the digest in the authenticatedAttributes

Returns

byte[]

the bytes for the PKCS7SignedData object

Remarks

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.

GetEncodedPKCS7(byte[], CryptoStandard, ITSAClient, ICollection<byte[]>, ICollection<byte[]>)

Gets the bytes for the PKCS7SignedData object.

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

Parameters

secondDigest byte[]

the digest in the authenticatedAttributes

sigtype PdfSigner.CryptoStandard

specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES

tsaClient ITSAClient

TSAClient - null or an optional time stamp authority client

ocsp ICollection<byte[]>

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 ICollection<byte[]>

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[]

byte[] the bytes for the PKCS7SignedData object

Remarks

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.

GetFilterSubtype()

Getter for the filter subtype.

public virtual PdfName GetFilterSubtype()

Returns

PdfName

the filter subtype

GetLocation()

Getter for property location.

public virtual string GetLocation()

Returns

string

Value of property location.

GetOcsp()

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

public virtual IBasicOcspResponse GetOcsp()

Returns

IBasicOcspResponse

the OCSP basic response or null.

GetReason()

Getter for property reason.

public virtual string GetReason()

Returns

string

Value of property reason.

GetSignCertificateChain()

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

public virtual IX509Certificate[] GetSignCertificateChain()

Returns

IX509Certificate[]

the X.509 certificates associated with this PKCS#7 object

Remarks

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.

GetSignDate()

Getter for property signDate.

public virtual DateTime GetSignDate()

Returns

DateTime

Value of property signDate.

GetSignName()

Getter for property sigName.

public virtual string GetSignName()

Returns

string

Value of property sigName.

GetSignatureAlgorithmName()

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

public virtual string GetSignatureAlgorithmName()

Returns

string

the name of an encryption algorithm

GetSignatureMechanismName()

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

public virtual string GetSignatureMechanismName()

Returns

string

the algorithm used to calculate the signature

Remarks

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

GetSignatureMechanismOid()

Getter for the signature algorithm OID.

public virtual string GetSignatureMechanismOid()

Returns

string

the signature algorithm OID

Remarks

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

GetSignedDataCRLs()

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

public virtual ICollection<IX509Crl> GetSignedDataCRLs()

Returns

ICollection<IX509Crl>

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

GetSignedDataOcsps()

Gets the OCSP basic response collection retrieved from SignedData structure.

public virtual ICollection<IBasicOcspResponse> GetSignedDataOcsps()

Returns

ICollection<IBasicOcspResponse>

the OCSP basic response collection.

GetSigningCertificate()

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

public virtual IX509Certificate GetSigningCertificate()

Returns

IX509Certificate

the X.509 certificate actually used to sign the digest

GetSigningInfoVersion()

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

public virtual int GetSigningInfoVersion()

Returns

int

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

GetTimeStampDate()

Gets the timestamp date.

public virtual DateTime GetTimeStampDate()

Returns

DateTime

the timestamp date

Remarks

Gets the timestamp date.

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

GetTimeStampTokenInfo()

Gets the timestamp token info if there is one.

public virtual ITstInfo GetTimeStampTokenInfo()

Returns

ITstInfo

the timestamp token info or null

GetTimestampCertificates()

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

public virtual IX509Certificate[] GetTimestampCertificates()

Returns

IX509Certificate[]

Certificate[] array

GetTimestampSignatureContainer()

Retrieves inner timestamp signature container if there is one.

public virtual PdfPKCS7 GetTimestampSignatureContainer()

Returns

PdfPKCS7

timestamp signature container or null.

GetVersion()

Get the version of the PKCS#7 object.

public virtual int GetVersion()

Returns

int

the version of the PKCS#7 object.

IsRevocationValid()

Checks if OCSP revocation refers to the document signing certificate.

public virtual bool IsRevocationValid()

Returns

bool

true if it checks, false otherwise

IsTsp()

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

public virtual bool IsTsp()

Returns

bool

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

SetExternalSignatureValue(byte[], byte[], string)

Sets the signature to an externally calculated value.

public virtual void SetExternalSignatureValue(byte[] signatureValue, byte[] signedMessageContent, string signatureAlgorithm)

Parameters

signatureValue byte[]

the signature value

signedMessageContent byte[]

the extra data that goes into the data tag in PKCS#7

signatureAlgorithm string

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(byte[], byte[], string, ISignatureMechanismParams)

Sets the signature to an externally calculated value.

public virtual void SetExternalSignatureValue(byte[] signatureValue, byte[] signedMessageContent, string signatureAlgorithm, ISignatureMechanismParams signatureMechanismParams)

Parameters

signatureValue byte[]

the signature value

signedMessageContent byte[]

the extra data that goes into the data tag in PKCS#7

signatureAlgorithm string

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 ISignatureMechanismParams

parameters for the signature mechanism, if required

SetLocation(string)

Setter for property location.

public virtual void SetLocation(string location)

Parameters

location string

New value of property location.

SetReason(string)

Setter for property reason.

public virtual void SetReason(string reason)

Parameters

reason string

New value of property reason.

SetSignDate(DateTime)

Setter for property signDate.

public virtual void SetSignDate(DateTime signDate)

Parameters

signDate DateTime

New value of property signDate.

SetSignName(string)

Setter for property sigName.

public virtual void SetSignName(string signName)

Parameters

signName string

New value of property sigName.

SetSignaturePolicy(ISignaturePolicyIdentifier)

Set signature policy identifier to be used during signature creation.

public virtual void SetSignaturePolicy(ISignaturePolicyIdentifier signaturePolicy)

Parameters

signaturePolicy ISignaturePolicyIdentifier

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

SetSignaturePolicy(SignaturePolicyInfo)

Set signature policy identifier to be used during signature creation.

public virtual void SetSignaturePolicy(SignaturePolicyInfo signaturePolicy)

Parameters

signaturePolicy SignaturePolicyInfo

SignaturePolicyInfo to be used during signature creation

Update(byte[], int, int)

Update the digest with the specified bytes.

public virtual void Update(byte[] buf, int off, int len)

Parameters

buf byte[]

the data buffer

off int

the offset in the data buffer

len int

the data length

Remarks

Update the digest with the specified bytes. This method is used both for signing and verifying

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.

public virtual bool VerifySignatureIntegrityAndAuthenticity()

Returns

bool

true if the signature checks out, false otherwise

Remarks

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 SignatureCoversWholeDocument(string) method.

VerifyTimestampImprint()

Checks if the timestamp refers to this document.

public virtual bool VerifyTimestampImprint()

Returns

bool

true if it checks false otherwise