com.ibm.security.pkcs7
Class RecipientInfo

java.lang.Object
  |
  +--com.ibm.security.pkcsutil.PKCSDerObject
        |
        +--com.ibm.security.pkcs7.RecipientInfo

public final class RecipientInfo
extends PKCSDerObject
implements Cloneable

Implements the ASN.1 RecipientInfo type. It is specified in PKCS #7 and was later refined in S/MIME.

This class contains per-recipient information in a Certificate, for example, the version number, the issuer and issuer serial number, the key encryption algorithm ID and the encrypted session key.

PKCS #7 defines RecipientInfo as follows:

RecipientInfo ::= SEQUENCE { version Version, issuerAndSerialNumber IssuerAndSerialNumber, keyEncryptionAlgorithm KeyEncryptionAlgorithmIdentifier, encryptedKey EncryptedKey }

S/MIME defines RecipientInfo as follows:

RecipientInfo ::= SEQUENCE { version Version, rid RecipientIdentifier, originatorCert [0] EXPLICIT EntityIdentifier OPTIONAL, keyEncryptionAlgorithm KeyEncryptionAlgorithmIdentifier, encryptedKey EncryptedKey }

S/MIME also defines the following types:

KeyEncryptionAlgorithmIdentifier ::= AlgorithmIdentifier EncryptedKey ::= OCTET STRING

RecipientInfo objects are immutable; they cannot be changed once created.

See Also:
RecipientIdentifier, EntityIdentifier, AlgorithmId

Fields inherited from class com.ibm.security.pkcsutil.PKCSDerObject
provider
 
Constructor Summary
RecipientInfo(byte[] der)
          Create a RecipientInfo object with a DER-encoded byte array.
RecipientInfo(byte[] key, Certificate cert)
          Create a RecipientInfo object with the specified key and certificate.
RecipientInfo(byte[] key, Certificate cert, String provider)
          Create a RecipientInfo object with the specified key and certificate.
RecipientInfo(byte[] der, String provider)
          Create a RecipientInfo object with a DER-encoded byte array.
RecipientInfo(RecipientIdentifier rid, EntityIdentifier ei, AlgorithmId alg, byte[] key)
          Create a RecipientInfo object with the specified values.
RecipientInfo(RecipientIdentifier rid, EntityIdentifier ei, AlgorithmId alg, byte[] key, String provider)
          Create a RecipientInfo object with the specified values.
RecipientInfo(String filename, boolean base64)
          Create a RecipientInfo with the filename of the DER-encoded or BASE64-encoded object.
RecipientInfo(String filename, boolean base64, String provider)
          Create a RecipientInfo with the filename of the DER-encoded or BASE64-encoded object.
 
Method Summary
 Object clone()
          Creates a clone of this RecipientInfo object.
protected  void decode(com.ibm.security.pkcs7.DerValue encoding)
          Initializes a RecipientInfo object from a DerValue.
 byte[] decryptKey(PrivateKey key)
          Decrypts the encrypted symmetric key with the input private key.
 void encode(OutputStream os)
          Encodes this object to an OutputStream.
 boolean equals(Object other)
          Determines if this RecipientInfo object is equivalent to the input object.
protected  void finalize()
          Ensures that the encryptedKey bytes are nulled out when there are no more references to this object.
 byte[] getEncryptedKey()
          Returns a copy of the symmetric key which was encrypted with the public key of this recipient.
 EntityIdentifier getEntityIdentifier()
          Returns a copy of the EntityIdentifier.
 AlgorithmId getKeyEncryptionAlgorithm()
          Returns a copy of the algorithm, represented as an AlgorithmId, that was used to encrypt the symmetric key.
 RecipientIdentifier getRecipientIdentifier()
          Returns a copy of the RecipientIdentifier.
 BigInteger getVersion()
          Returns the syntax version number of this RecipientInfo object.
 boolean identifies(Certificate cert)
          Determines if the recipient represented by this object is identified by the input certificate.
 String toString()
          Returns a string representation of this RecipientInfo object.
 
Methods inherited from class com.ibm.security.pkcsutil.PKCSDerObject
decode, decode, encode, getObjectIdentifier, hashCode, read, readBASE64, write, write, writeBASE64
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RecipientInfo

public RecipientInfo(byte[] der)
              throws IOException
Create a RecipientInfo object with a DER-encoded byte array.
Parameters:
der - a byte array containing the DER-encoded encoding of a RecipientInfo object.
Throws:
IOException - on decoding errors.

RecipientInfo

public RecipientInfo(byte[] der,
                     String provider)
              throws IOException
Create a RecipientInfo object with a DER-encoded byte array.
Parameters:
der - a byte array containing the DER-encoded encoding of a RecipientInfo object.
provider - the name of the java security provider to use
Throws:
IOException - on decoding errors.

RecipientInfo

public RecipientInfo(byte[] key,
                     Certificate cert)
              throws IOException,
                     PKCSException
Create a RecipientInfo object with the specified key and certificate. Only X.509 certificates are supported at this time. The recipient identifier in the object is of type IssuerAndSerialNumber based on the X.500 name in the certificate and there is no optional originator identifier.
Parameters:
key - the encoded symmetric key to be encrypted with the recipient's public key.
cert - the X.509 certificate containing the recipient's identity and public key.
Throws:
IOException - if extraction of the recipient identifier from the certificate fails.
PKCSException - key encryption error.

RecipientInfo

public RecipientInfo(byte[] key,
                     Certificate cert,
                     String provider)
              throws IOException,
                     PKCSException
Create a RecipientInfo object with the specified key and certificate. Only X.509 certificates are supported at this time. The recipient identifier in the object is of type IssuerAndSerialNumber based on the X.500 name in the certificate and there is no optional originator identifier.
Parameters:
key - the encoded symmetric key to be encrypted with the recipient's public key.
cert - the X.509 certificate containing the recipient's identity and public key.
provider - the name of the java security provider to use
Throws:
IOException - if extraction of the recipient identifier from the certificate fails.
PKCSException - key encryption error.

RecipientInfo

public RecipientInfo(RecipientIdentifier rid,
                     EntityIdentifier ei,
                     AlgorithmId alg,
                     byte[] key)
Create a RecipientInfo object with the specified values.
Parameters:
rid - RecipientIdentifier
ei - EntityIdentifier
alg - key encryption algorithm
key - encrypted secret key bytes

RecipientInfo

public RecipientInfo(RecipientIdentifier rid,
                     EntityIdentifier ei,
                     AlgorithmId alg,
                     byte[] key,
                     String provider)
Create a RecipientInfo object with the specified values.
Parameters:
rid - RecipientIdentifier
ei - EntityIdentifier
alg - key encryption algorithm
key - encrypted secret key bytes
provider - the name of the java security provider to use

RecipientInfo

public RecipientInfo(String filename,
                     boolean base64)
              throws IOException
Create a RecipientInfo with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
Throws:
IOException - on decoding errors.

RecipientInfo

public RecipientInfo(String filename,
                     boolean base64,
                     String provider)
              throws IOException
Create a RecipientInfo with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
provider - the name of the java security provider to use
Throws:
IOException - on decoding errors.
Method Detail

encode

public void encode(OutputStream os)
            throws IOException
Encodes this object to an OutputStream.
Overrides:
encode in class PKCSDerObject
Parameters:
os - the OutputStream to write the encoded data to.
Throws:
IOException - on encoding error.

decode

protected void decode(com.ibm.security.pkcs7.DerValue encoding)
               throws IOException
Initializes a RecipientInfo object from a DerValue. The DER encoding must be in the format specified by the RecipientInfo ASN.1 notation.
Parameters:
encoding - a DER-encoded RecipientInfo object.
Throws:
IOException - on parsing error.

equals

public boolean equals(Object other)
Determines if this RecipientInfo object is equivalent to the input object.
Overrides:
equals in class PKCSDerObject
Parameters:
other - the object to compare this one to.
Returns:
true, if the two objects are equivalent, false otherwise.

toString

public String toString()
Returns a string representation of this RecipientInfo object.
Overrides:
toString in class PKCSDerObject
Returns:
a string representation of this object.

clone

public Object clone()
Creates a clone of this RecipientInfo object.
Overrides:
clone in class Object
Returns:
clone of this RecipientInfo object.

getVersion

public BigInteger getVersion()
Returns the syntax version number of this RecipientInfo object. If the originator identifier is absent and the recipient identifier is of type IssuerAndSerialNumber, then the version is 0. If the originator identifier is present or the recipient identifier is type RecipientKeyIdentifier or MailListKeyIdentifier, then the version is 2.

This method returns a reference to the BigInteger version. BigInteger is an immutable object.

Returns:
the syntax version number of this object.

getEncryptedKey

public byte[] getEncryptedKey()
Returns a copy of the symmetric key which was encrypted with the public key of this recipient.
Returns:
the symmetric key encrypted with the recipient's public key.

getKeyEncryptionAlgorithm

public AlgorithmId getKeyEncryptionAlgorithm()
                                      throws IOException
Returns a copy of the algorithm, represented as an AlgorithmId, that was used to encrypt the symmetric key.
Returns:
the algorithm used to encrypt the symmetric key.

getRecipientIdentifier

public RecipientIdentifier getRecipientIdentifier()
Returns a copy of the RecipientIdentifier.
Returns:
the RecipientIdentifier

getEntityIdentifier

public EntityIdentifier getEntityIdentifier()
Returns a copy of the EntityIdentifier.
Returns:
the EntityIdentifier

identifies

public boolean identifies(Certificate cert)
                   throws IOException
Determines if the recipient represented by this object is identified by the input certificate. Only X.509 certificates are supported at this time.
Parameters:
cert - an X.509 certificate.
Returns:
true, if the certificate identifies this recipient, false otherwise.

decryptKey

public byte[] decryptKey(PrivateKey key)
                  throws PKCSException
Decrypts the encrypted symmetric key with the input private key.
Parameters:
key - the private key used for decryption.
Returns:
the decrypted symmetric key.
Throws:
PKCSException - key decryption error.

finalize

protected void finalize()
Ensures that the encryptedKey bytes are nulled out when there are no more references to this object.
Overrides:
finalize in class Object