PKCS7DecodeStream ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- java.io.InputStream
- - java.io.FilterInputStream
  - - com.entrust.toolkit.PKCS7DecodeStream

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable
```
public class PKCS7DecodeStream
extends java.io.FilterInputStream
```
The PKCS7DecodeStream class decodes data that has been signed and/or encrypted according to the PKCS#7 standard.
PKCS7DecodeStream verifies all signatures when the internal stream is closed. Use this stream to read data written with PKCS7EncodeStream.

Note

To make sure that the signature is verified you must call close after you have finished reading from the stream.

This class is not thread safe.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CLEAR_SIGN` Operation constant for signing without including the data
`static int`	`ENCRYPT_ONLY` Operation constant for encrypting the data without signing it
`static int`	`EXPORT_CERTIFICATES` Operation constant for exporting certificates
`static int`	`SIGN_AND_ENCRYPT` Operation constant for signing and encrypting the data
`static int`	`SIGN_ONLY` Operation constant for signing the data without encrypting it

Fields inherited from class java.io.FilterInputStream
in

Constructor Summary

Constructors
Constructor and Description
`PKCS7DecodeStream(KeyAndCertificateSource keyAndCertificateSource, java.io.InputStream inputStream)` Creates a new `PKCS7DecodeStream` object to decrypt data, to verify data, or to retrieve exported certificates.
`PKCS7DecodeStream(KeyAndCertificateSource keyAndCertificateSource, java.io.InputStream data, java.io.InputStream signature)` Creates a new `DecodeStream` to decode and verify clear signed data.
`PKCS7DecodeStream(User user, java.io.InputStream inputStream)` Creates a new `PKCS7DecodeStream` object to decrypt data, to verify data, or to retrieve exported certificates.
`PKCS7DecodeStream(User user, java.io.InputStream data, java.io.InputStream signature)` Creates a new `DecodeStream` to decode and verify clear signed data.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`available()` Returns `1` if at least one byte can be read from this input stream without blocking.
`void`	`close()` Closes this input stream and releases any system resources associated with the stream.
`byte[]`	`getDigest(int index)` Returns the digest from a signature that exists over the data that was extracted during a verification operation.
`AlgorithmID`	`getDigestAlgorithm(int index)` Returns the message digest algorithm used to sign the data.
`AlgorithmID`	`getEncryptionAlgorithm()` Returns the algorithm used to encrypt the data.
`CertificateSet`	`getIncludedCertificates()` Returns the certificates included in the PKCS#7 message.
`int`	`getNumberOfSignatures()` Returns the number of signatures on the data.
`int`	`getOperation()` Returns the security operation that was performed on the data read from this stream.
`java.util.Iterator`	`getRevocationWarnings()` Returns any revocation warnings that occurred during the verification and validation of signed PKCS7 data.
`X509Certificate`	`getSignerCertificate(int index)` Returns the certificate that is used to verify the signature.
`SignerInfo`	`getSignerInfo(int index)` Returns the signer information of the signature indicated by `index`.
`void`	`mark(int readlimit)` `mark()` is not supported.
`boolean`	`markSupported()` The `mark` and `reset` methods are not supported.
`int`	`read()` Reads the next byte of data from the input stream.
`int`	`read(byte[] b, int off, int len)` Reads up to `len` bytes of data from the current input stream into an array of bytes.
`void`	`reset()` `reset()` is not supported.
`long`	`skip(long n)` Skips over and discards `n` bytes of data from the input stream.

Methods inherited from class java.io.FilterInputStream
read

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

- Field Detail
  - SIGN_AND_ENCRYPT
```
public static final int SIGN_AND_ENCRYPT
```
    Operation constant for signing and encrypting the data
    
    See Also:
    
    Constant Field Values
  - ENCRYPT_ONLY
```
public static final int ENCRYPT_ONLY
```
    Operation constant for encrypting the data without signing it
    
    See Also:
    
    Constant Field Values
  - SIGN_ONLY
```
public static final int SIGN_ONLY
```
    Operation constant for signing the data without encrypting it
    
    See Also:
    
    Constant Field Values
  - EXPORT_CERTIFICATES
```
public static final int EXPORT_CERTIFICATES
```
    Operation constant for exporting certificates
    
    See Also:
    
    Constant Field Values
  - CLEAR_SIGN
```
public static final int CLEAR_SIGN
```
    Operation constant for signing without including the data
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - PKCS7DecodeStream
```
public PKCS7DecodeStream(User user,
                         java.io.InputStream inputStream)
                  throws InvalidUserException,
                         java.lang.NullPointerException,
                         java.io.IOException,
                         java.security.NoSuchAlgorithmException
```
    Creates a new PKCS7DecodeStream object to decrypt data, to verify data, or to retrieve exported certificates.
    The user must be logged in before your application calls this constructor.
    
    If the data is clear signed, you can pass this object as the signature argument in PKCS7DecodeStream(User, InputStream, InputStream).
    
    Parameters:
    
    user - the user trying to decrypt the data and verify the certificates
    
    inputStream - the underlying input stream from which PKCS7 encoded data is read.
    
    Throws:
    
    java.lang.NullPointerException - thrown if either user or data is null
    
    java.io.IOException - if there is a problem reading from the stream.
    
    InvalidUserException - thrown if the user is not logged in
    
    java.security.NoSuchAlgorithmException - thrown if one of the algorithms in the PKCS#7 message is not recognized or supported in the user's environment
    
    NotARecipientException - thrown if the message was not encrypted for user
    
    FormatException - thrown if signature is not a signature without data, or if the PKCS#7 or ASN.1 encoding is corrupt
  - PKCS7DecodeStream
```
public PKCS7DecodeStream(KeyAndCertificateSource keyAndCertificateSource,
                         java.io.InputStream inputStream)
                  throws java.lang.NullPointerException,
                         java.io.IOException,
                         java.security.NoSuchAlgorithmException
```
    Creates a new PKCS7DecodeStream object to decrypt data, to verify data, or to retrieve exported certificates.
    If the message is encrypted, keyAndCertificateSource must contain a private key that is on the recipient list of the message to be able to decrypt it. If it is not encrypted, no private keys are required.
    
    If the data is clear signed, you can pass this object as the signature argument in PKCS7DecodeStream(User, InputStream, InputStream).
    
    Parameters:
    
    keyAndCertificateSource - the source of the certificate verifier and private decryption keys.
    
    inputStream - the underlying input stream from which PKCS7 encoded data is read.
    
    Throws:
    
    java.lang.NullPointerException - thrown if either keyAndCertificateSource or data is null
    
    java.io.IOException - if there is a problem reading from the stream.
    
    java.security.NoSuchAlgorithmException - thrown if one of the algorithms in the PKCS#7 message is not recognized or supported in the user's environment
    
    NotARecipientException - thrown if the message was not encrypted for user
    
    FormatException - thrown if signature is not a signature without data, or if the PKCS#7 or ASN.1 encoding is corrupt
    
    Since:
    
    7.0
  - PKCS7DecodeStream
```
public PKCS7DecodeStream(User user,
                         java.io.InputStream data,
                         java.io.InputStream signature)
                  throws InvalidUserException,
                         java.lang.NullPointerException,
                         java.io.IOException,
                         java.security.NoSuchAlgorithmException
```
    Creates a new DecodeStream to decode and verify clear signed data.
    The user must be logged in before your application can call this constructor.
    
    You can put the signature parameter into any input stream, including a PKCS7DecodeStream.
    
    Parameters:
    
    user - the user trying to decrypt the data and verify the certificates
    
    data - the underlying input stream from which data is read.
    
    signature - the input stream to read the signature from
    
    Throws:
    
    java.lang.NullPointerException - thrown if user, data, or signature is null
    
    java.io.IOException - if there is a problem reading from the streams.
    
    InvalidUserException - thrown if the user is not logged on
    
    FormatException - thrown if signature is not a signature without data, or if the PKCS#7 or ASN.1 encoding is corrupt
    
    java.security.NoSuchAlgorithmException - thrown if one of the algorithms in the PKCS#7 message is not recognized or supported in the user's environment
  - PKCS7DecodeStream
```
public PKCS7DecodeStream(KeyAndCertificateSource keyAndCertificateSource,
                         java.io.InputStream data,
                         java.io.InputStream signature)
                  throws java.lang.NullPointerException,
                         java.io.IOException,
                         java.security.NoSuchAlgorithmException
```
    Creates a new DecodeStream to decode and verify clear signed data.
    You can put the signature parameter into any input stream, including a PKCS7DecodeStream.
    
    Parameters:
    
    keyAndCertificateSource - the source of the certificate verifier.
    
    data - the underlying input stream from which data is read.
    
    signature - the input stream to read the signature from
    
    Throws:
    
    java.lang.NullPointerException - thrown if user, data, or signature is null
    
    java.io.IOException - if there is a problem reading from the streams.
    
    FormatException - thrown if signature is not a signature without data, or if the PKCS#7 or ASN.1 encoding is corrupt
    
    java.security.NoSuchAlgorithmException - thrown if one of the algorithms in the PKCS#7 message is not recognized or supported in the user's environment
    
    Since:
    
    7.0
- Method Detail
  - getOperation
```
public int getOperation()
```
    Returns the security operation that was performed on the data read from this stream.
    The return value can be one of the following:
    - SIGN_AND_ENCRYPT
    - ENCRYPT_ONLY
    - SIGN_ONLY
    - EXPORT_CERTIFICATES
    - CLEAR_SIGN
    Returns:
    
    the security operation performed on the data
  - getEncryptionAlgorithm
```
public AlgorithmID getEncryptionAlgorithm()
```
    Returns the algorithm used to encrypt the data.
    If the data is not encrypted, this method returns null.
    
    Returns:
    
    the algorithm used to encrypt the data, or null if the data is not encrypted
  - getNumberOfSignatures
```
public int getNumberOfSignatures()
```
    Returns the number of signatures on the data.
    Note
    
    This method can be called only after the end of the stream has been reached.
    
    Returns:
    
    the number of signatures on the data
  - getDigestAlgorithm
```
public AlgorithmID getDigestAlgorithm(int index)
```
    Returns the message digest algorithm used to sign the data.
    The index specifies the signature for which the digest algorithm should be returned. The first signature has index 0, the last has index getNumberOfSignatures()-1.
    
    Note
    
    You can call this method only after the end of the stream has been reached.
    
    Parameters:
    
    index - the signature for which the digest algorithm should be returned
    
    Returns:
    
    the algorithm with which the data was hashed, or null if the data is not signed
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - thrown if index < 0 or index >= getNumberOfSignatures()
  - getSignerCertificate
```
public X509Certificate getSignerCertificate(int index)
```
    Returns the certificate that is used to verify the signature.
    The index specifies the signature for which the verification certificate should be returned. The first certificate has index 0, the last has index getNumberOfSignatures()-1.
    
    Note
    
    You can call this method only after the end of the stream has been reached.
    
    Parameters:
    
    index - the signature for which the verification certificate should be returned
    
    Returns:
    
    the verification certificate with which the data was verified, or null if the data is not signed
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - thrown if index < 0 or index >= getNumberOfSignatures()
  - getSignerInfo
```
public SignerInfo getSignerInfo(int index)
```
    Returns the signer information of the signature indicated by index.
    The first signature has index 0, the last has index getNumberOfSignatures()-1.
    
    Note
    
    You can call this method only after the end of the stream has been reached.
    
    Parameters:
    
    index - the signature for which the signer info should be returned
    
    Returns:
    
    the signer information associated with the specified signature
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if index < 0 or index >= getNumberOfSignatures()
  - getIncludedCertificates
```
public CertificateSet getIncludedCertificates()
```
    Returns the certificates included in the PKCS#7 message.
    If the data is not signed, this method returns null.
    
    If the data is signed, but no certificates are included, this method returns an array with length 0.
    
    Returns:
    
    all included X.509 certificates
  - getRevocationWarnings
```
public java.util.Iterator getRevocationWarnings()
```
    Returns any revocation warnings that occurred during the verification and validation of signed PKCS7 data.
    When validating each signer certificate that was used to create a signature in the PKCS7 signed data, time-stamps must be considered. When, a signature is time-stamped, the time-stamp token is decoded, verified and validated, and then the signer's certificate is validated at the time specified in the time-stamp.
    
    During the validation of the signer's certificate at the time specified in the time-stamp, a revocation warning can occur. This happens when the signer's certificate has been revoked, but was revoked after the time specified in the time-stamp. When this occurs, the signer's certificate can still be considered valid, depending on the policy surrounding time-stamping and the reason it was revoked. This causes a revocation warning to be created.
    
    This API provides access to all the revocation warnings that occurred. It returns an Iterator that contains Map.Entry objects. Each Map.Entry object contains an Integer key that represents the signer index in the signed data for which the revocation warning occurred, and a RevocationWarningException value that contains all the revocation warning information.
    
    For each revocation warning, it is then up to the caller to decide whether the warning should be ignored, or acted upon.
    
    Returns:
    
    the revocation warnings as an Iterator over Map.Entry objects
    
    Since:
    
    7.0
  - read
```
public int read()
         throws java.io.IOException
```
    Reads the next byte of data from the input stream.
    The value byte is returned as an int in the range 0 to 255. The value -1 is returned when no byte is available because one of the following conditions applies:
    - the end of the stream has been reached
    - the data is the signature of a clear signed message
    - the data comprises exported signatures
    This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.
    
    When the end of a signed message is reached, all signatures and the signers' certificates are validated. This may cause a Directory to be contacted, which could cause this call to block for a long time if the Directory is slow to respond. Eventually these exceptions would be wrapped in a CertNotTrustedException. See JNDIDirectory.getAttr(java.lang.String, java.lang.String) for details on which exceptions may be thrown if the Directory is not responding.
    Overrides:
    
    read in class java.io.FilterInputStream
    
    Returns:
    
    the next byte of data, or -1 if the end of the stream is reached.
    
    Throws:
    
    SignatureException - thrown if the signature is invalid
    
    NoSuchSignerException - thrown if a signer's certificate cannot be found
    
    CertNotTrustedException - thrown if the signature is valid, but the signer's certificate cannot be validated
    
    InvalidUserException - thrown if the user is not logged in
    
    java.io.IOException - thrown if an I/O error occurs
  - read
```
public int read(byte[] b,
                int off,
                int len)
         throws java.io.IOException
```
    Reads up to len bytes of data from the current input stream into an array of bytes.
    This method blocks until some input is available. When the end of a signed message is reached, all signatures and the signers' certificates are validated. This may cause a Directory to be contacted, which could cause this call to block for a long time if the Directory is slow to respond. Eventually these exceptions would be wrapped in a CertNotTrustedException. See JNDIDirectory.getAttr(java.lang.String, java.lang.String) for details on which exceptions may be thrown if the Directory is not responding.
    
    Overrides:
    
    read in class java.io.FilterInputStream
    
    Parameters:
    
    b - the buffer into which the data is read
    
    off - the start offset of the data
    
    len - the maximum number of bytes read
    
    Returns:
    
    the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached
    
    Throws:
    
    SignatureException - thrown if the signature is invalid
    
    NoSuchSignerException - if a signer's certificate cannot be found
    
    CertNotTrustedException - thrown if the signature is valid, but the signer's certificate cannot be validated
    
    InvalidUserException - thrown if the user is not logged in
    
    java.io.IOException - thrown if an I/O error occurs
  - skip
```
public long skip(long n)
          throws java.io.IOException
```
    Skips over and discards n bytes of data from the input stream.
    The skip method might skip over a smaller number of bytes, possibly 0. There are a number of reasons for this, but the method returns the number of bytes actually skipped.
    
    The skip() method calls read with an array of size n, and returns the number of read bytes.
    
    Overrides:
    
    skip in class java.io.FilterInputStream
    
    Parameters:
    
    n - the number of bytes to be skipped
    
    Returns:
    
    the actual number of bytes skipped
    
    Throws:
    
    SignatureException - thrown if the signature is invalid
    
    NoSuchSignerException - if a signer's certificate cannot be found
    
    CertNotTrustedException - thrown if the signature is valid, but the signer's certificate cannot be validated
    
    java.io.IOException - thrown if an I/O error occurs
  - available
```
public int available()
              throws java.io.IOException
```
    Returns 1 if at least one byte can be read from this input stream without blocking.
    
    Overrides:
    
    available in class java.io.FilterInputStream
    
    Returns:
    
    1 if at least one byte can be read from this input stream without blocking
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
  - close
```
public void close()
           throws java.io.IOException
```
    Closes this input stream and releases any system resources associated with the stream.
    
    Specified by:
    
    close in interface java.io.Closeable
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Overrides:
    
    close in class java.io.FilterInputStream
    
    Throws:
    
    SignatureException - thrown if the signature is invalid and has not been verified by read or skip yet
    
    java.io.IOException - if an I/O error occurs
  - mark
```
public void mark(int readlimit)
```
    mark() is not supported. This method does nothing.
    
    Overrides:
    
    mark in class java.io.FilterInputStream
    
    Parameters:
    
    readlimit - ignored
  - reset
```
public void reset()
           throws java.io.IOException
```
    reset() is not supported. This method always throws an IOException.
    
    Overrides:
    
    reset in class java.io.FilterInputStream
    
    Throws:
    
    java.io.IOException - always
  - markSupported
```
public boolean markSupported()
```
    The mark and reset methods are not supported. Therefore, markSupported always returns false.
    
    Overrides:
    
    markSupported in class java.io.FilterInputStream
    
    Returns:
    
    false
  - getDigest
```
public byte[] getDigest(int index)
```
    Returns the digest from a signature that exists over the data that was extracted during a verification operation.
    This is only accessible following a verification signing operation, and only after the stream has been closed. If the stream has not been closed, an error occurred during the P7 operation, or the P7 operation did not involve verification, null is returned.
    
    The index specifies the signature from which the digest should be returned. The first signature has index 0, the last has index getNumberOfSignatures() - 1.
    
    Parameters:
    
    index - the index of the signature
    
    Returns:
    
    the digest
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - if index < 0 or index >= getNumberOfSignatures()
    
    Since:
    
    7.0

Class PKCS7DecodeStream

Field Summary

Fields inherited from class java.io.FilterInputStream

Constructor Summary

Method Summary

Methods inherited from class java.io.FilterInputStream

Methods inherited from class java.lang.Object

Field Detail

SIGN_AND_ENCRYPT

ENCRYPT_ONLY

SIGN_ONLY

EXPORT_CERTIFICATES

CLEAR_SIGN

Constructor Detail

PKCS7DecodeStream

PKCS7DecodeStream

PKCS7DecodeStream

PKCS7DecodeStream

Method Detail

getOperation

getEncryptionAlgorithm

getNumberOfSignatures

getDigestAlgorithm

getSignerCertificate

getSignerInfo

getIncludedCertificates

getRevocationWarnings

read

read

skip

available

close

mark

reset

markSupported

getDigest