com.ibm.security.pkcs7
Class AuthenticatedData

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

public final class AuthenticatedData
extends Content
implements Cloneable

Implements the ASN.1 AuthenticatedData type.

AuthenticatedData ::= SEQUENCE { version CMSVersion, originatorInfo [0] IMPLICIT OriginatorInfo OPTIONAL, recipientInfos RecipientInfos, macAlgorithm MessageAuthenticationCodeAlgorithm, digestAlgorithm [1] DigestAlgorithmIdentifier OPTIONAL, encapContentInfo EncapsulatedContentInfo, authenticatedAttributes [2] IMPLICIT AuthAttributes OPTIONAL, mac MessageAuthenticationCode, unauthenticatedAttributes [3] IMPLICIT UnauthAttributes OPTIONAL }

This definition reflects PKCS #7 version 1.5 specifications with selected enhancements from the Cryptographic Message Syntax (CMS) RFC 2630 specifications.

Only X509Certificate objects are supported for recipient certificates.

AuthenticatedData objects are not immutable; they can be changed once created. After construction of the AuthenticatedData object, users can add additional recipients of the object as well as remove the contents of this object.


Fields inherited from class com.ibm.security.pkcsutil.PKCSDerObject
provider
 
Constructor Summary
AuthenticatedData(byte[] der)
          Create an AuthenticatedData object with a DER-encoded byte array.
AuthenticatedData(byte[] der, String provider)
          Create an AuthenticatedData object with a DER-encoded byte array.
AuthenticatedData(javax.crypto.SecretKey secretKey, OriginatorInfo originator, Certificate[] recipientCerts, String macAlgorithm, String digestAlgorithm, EncapsulatedContentInfo encapsulatedContent, PKCSAttributes authAttribs, PKCSAttributes unauthAttribs)
          Create an AuthenticatedData object using recipient certificates instead of RecipientInfo objects.
AuthenticatedData(javax.crypto.SecretKey secretKey, OriginatorInfo originator, Certificate[] recipientCerts, String macAlgorithm, String digestAlgorithm, EncapsulatedContentInfo encapsulatedContent, PKCSAttributes authAttribs, PKCSAttributes unauthAttribs, String provider)
          Create an AuthenticatedData object using recipient certificates instead of RecipientInfo objects.
AuthenticatedData(javax.crypto.SecretKey secretKey, OriginatorInfo originator, RecipientInfo[] recipientInfos, String macAlgorithm, String digestAlgorithm, EncapsulatedContentInfo encapsulatedContent, PKCSAttributes authAttribs, PKCSAttributes unauthAttribs)
          Create an AuthenticatedData object with the specified values that match the ASN.1 definition of AuthenticatedData.
AuthenticatedData(javax.crypto.SecretKey secretKey, OriginatorInfo originator, RecipientInfo[] recipientInfos, String macAlgorithm, String digestAlgorithm, EncapsulatedContentInfo encapsulatedContent, PKCSAttributes authAttribs, PKCSAttributes unauthAttribs, String provider)
           
AuthenticatedData(String filename, boolean base64)
          Create an AuthenticatedData with the filename of the DER-encoded or BASE64-encoded object.
AuthenticatedData(String filename, boolean base64, String provider)
          Create an AuthenticatedData with the filename of the DER-encoded or BASE64-encoded object.
 
Method Summary
 void addRecipient(Certificate[] certs)
          Adds a group of recipients, as identified by their certificates, to the AuthenticatedData object.
 Object clone()
          Creates a clone of this AuthenticatedData.
protected  void decode(com.ibm.security.pkcs7.DerValue encoding)
          Initializes an AuthenticatedData object from a DerValue.
 void encode(OutputStream os)
          Encodes this object to an OutputStream.
 boolean equals(Object other)
          Determines if this AuthenticatedData object is equivalent to the input object.
protected  void finalize()
          Ensures that the contentEncryptionKey bytes are nulled out when there are no more references to this object.
 PKCSAttribute getAuthAttribute(ObjectIdentifier oid)
          Returns a reference to an authenticated attribute from the authenticated attribute set based on an ObjectIdentifier.
 PKCSAttributes getAuthAttributes()
          Returns a reference to the PKCSAttributes authenticated attributes for this object.
 AlgorithmId getDigestAlgorithm()
          Returns a copy of the Message Digest AlgorithmId for this object, or null if the Message Digest algorithm has not been set.
 EncapsulatedContentInfo getEncapsulatedContent()
          Returns a copy of the EncapsulatedContentInfo for this object, or null if the EncapsulatedContentInfo has not been set.
 byte[] getMac()
          Returns a copy the MAC byte array for this object, or null if the MAC byte array has not been set.
 AlgorithmId getMacAlgorithm()
          Returns a copy of the MAC algorithm for this object, or null if the MAC algorithm has not been set.
 ObjectIdentifier getObjectIdentifier()
          Returns a reference to the ObjectIdentifer for the AuthenticateData object.
 OriginatorInfo getOriginator()
          Returns a copy of the OriginatorInfo for this object, or null if the OriginatorInfo has not been set.
 RecipientInfo[] getRecipientInfos()
          Returns a copy of the array of recipientInfos for this object, or null if the recipientInfos have not been set.
 PKCSAttribute getUnauthAttribute(ObjectIdentifier oid)
          Returns a reference to an unauthenticated attribute from the unauthenticated attribute set based on an ObjectIdentifier.
 PKCSAttributes getUnauthAttributes()
          Returns a reference to the PKCSAttributes unauthenticated attributes for this object.
 BigInteger getVersion()
          Returns a reference to the version for this object.
 boolean hasAuthenticatedAttribute(ObjectIdentifier oid)
          Determine if this AuthenticatedData has the authenticated attribute specified by the ObjectIdentifier.
 boolean hasUnauthenticatedAttribute(ObjectIdentifier oid)
          Determine if this AuthenticatedData has the unauthenticated attribute specified by the ObjectIdentifier.
 void removeContent()
          Removes the content from the EncapsulatedContentInfo.
 String toString()
          Returns a string representation of this AuthenticatedData object.
 boolean verify(javax.crypto.SecretKey secretKey)
          Verify the stored Message Authentication Code (MAC) based on the AuthenticateData values and the specified secret key.
 boolean verify(javax.crypto.SecretKey secretKey, byte[] msg)
          Verify the stored Message Authentication Code (MAC) based on the AuthenticateData values and the specified secret key and message byte array.
 
Methods inherited from class com.ibm.security.pkcsutil.PKCSDerObject
decode, decode, encode, hashCode, read, readBASE64, write, write, writeBASE64
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AuthenticatedData

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

AuthenticatedData

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

AuthenticatedData

public AuthenticatedData(javax.crypto.SecretKey secretKey,
                         OriginatorInfo originator,
                         RecipientInfo[] recipientInfos,
                         String macAlgorithm,
                         String digestAlgorithm,
                         EncapsulatedContentInfo encapsulatedContent,
                         PKCSAttributes authAttribs,
                         PKCSAttributes unauthAttribs)
                  throws IOException,
                         PKCSException,
                         NoSuchAlgorithmException
Create an AuthenticatedData object with the specified values that match the ASN.1 definition of AuthenticatedData.
Parameters:
secretKey - used in the MAC calculation.
originator - the originator of the AuthenticatedData.
recipientInfos - an array of all the recipients of this AuthenticatedData.
macAlgorithm - MAC algorithm string.
digestAlgorithm - Message Digest algorithm string.
encapsulatedContent - EncapsulatedContentInfo on which to apply the MAC.
authAttrs - authenticated attribute set.
unauthAttrs - unauthenticated attribute set.
Throws:
IOException - MAC error.
NoSuchAlgorithmException - MAC error.
PKCSException - MAC error.

AuthenticatedData

public AuthenticatedData(javax.crypto.SecretKey secretKey,
                         OriginatorInfo originator,
                         RecipientInfo[] recipientInfos,
                         String macAlgorithm,
                         String digestAlgorithm,
                         EncapsulatedContentInfo encapsulatedContent,
                         PKCSAttributes authAttribs,
                         PKCSAttributes unauthAttribs,
                         String provider)
                  throws IOException,
                         PKCSException,
                         NoSuchAlgorithmException
Parameters:
secretKey - used in the MAC calculation.
originator - the originator of the AuthenticatedData.
recipientInfos - an array of all the recipients of this AuthenticatedData.
macAlgorithm - MAC algorithm string.
digestAlgorithm - Message Digest algorithm string.
encapsulatedContent - EncapsulatedContentInfo on which to apply the MAC.
authAttrs - authenticated attribute set.
unauthAttrs - unauthenticated attribute set.
provname - the name of the provider to use
Throws:
IOException - MAC error.
NoSuchAlgorithmException - MAC error.
PKCSException - MAC error.

AuthenticatedData

public AuthenticatedData(javax.crypto.SecretKey secretKey,
                         OriginatorInfo originator,
                         Certificate[] recipientCerts,
                         String macAlgorithm,
                         String digestAlgorithm,
                         EncapsulatedContentInfo encapsulatedContent,
                         PKCSAttributes authAttribs,
                         PKCSAttributes unauthAttribs)
                  throws IOException,
                         PKCSException,
                         NoSuchAlgorithmException
Create an AuthenticatedData object using recipient certificates instead of RecipientInfo objects.
Parameters:
secretKey - used in the MAC calculation.
originator - the originator of the AuthenticatedData.
recipientCerts - array of all the recipient certificates of this AuthenticatedData.
macAlgorithm - MAC algorithm string.
digestAlgorithm - Message Digest algorithm string.
encapsulatedContent - EncapsulatedContentInfo on which to apply the MAC.
authAttrs - authenticated attribute set.
unauthAttrs - unauthenticated attribute set.
Throws:
IOException - MAC error.
NoSuchAlgorithmException - MAC error.
PKCSException - MAC error.

AuthenticatedData

public AuthenticatedData(javax.crypto.SecretKey secretKey,
                         OriginatorInfo originator,
                         Certificate[] recipientCerts,
                         String macAlgorithm,
                         String digestAlgorithm,
                         EncapsulatedContentInfo encapsulatedContent,
                         PKCSAttributes authAttribs,
                         PKCSAttributes unauthAttribs,
                         String provider)
                  throws IOException,
                         PKCSException,
                         NoSuchAlgorithmException
Create an AuthenticatedData object using recipient certificates instead of RecipientInfo objects.
Parameters:
secretKey - used in the MAC calculation.
originator - the originator of the AuthenticatedData.
recipientCerts - array of all the recipient certificates of this AuthenticatedData.
macAlgorithm - MAC algorithm string.
digestAlgorithm - Message Digest algorithm string.
encapsulatedContent - EncapsulatedContentInfo on which to apply the MAC.
authAttrs - authenticated attribute set.
unauthAttrs - unauthenticated attribute set.
provname - the name of the java security provider to use
Throws:
IOException - MAC error.
NoSuchAlgorithmException - MAC error.
PKCSException - MAC error.

AuthenticatedData

public AuthenticatedData(String filename,
                         boolean base64)
                  throws IOException
Create an AuthenticatedData 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.

AuthenticatedData

public AuthenticatedData(String filename,
                         boolean base64,
                         String provider)
                  throws IOException
Create an AuthenticatedData 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
provname - the name of the java security provider to use
Throws:
IOException - on decoding errors.
Method Detail

clone

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

addRecipient

public void addRecipient(Certificate[] certs)
                  throws PKCSException,
                         IOException
Adds a group of recipients, as identified by their certificates, to the AuthenticatedData object.
Parameters:
certs - the X509Certificates representing the recipients to add.
Throws:
IOException - if extraction of a recipient identifier from an input certificate fails.
PKCSException - key encryption error.

verify

public boolean verify(javax.crypto.SecretKey secretKey)
               throws PKCSException,
                      IOException
Verify the stored Message Authentication Code (MAC) based on the AuthenticateData values and the specified secret key. This method also independently computes the message digest and compares it against the Message Digest authenticated attribute. As part of the verification process, this method will use the content stored in the EncapsulatedContentInfo to independently compute the message digest.
Parameters:
secretKey - used in the MAC calculation.
Returns:
true if mac verified, otherwise false.
Throws:
IOException - on verification errors.
PKCSException - on verification errors.

verify

public boolean verify(javax.crypto.SecretKey secretKey,
                      byte[] msg)
               throws IOException,
                      PKCSException
Verify the stored Message Authentication Code (MAC) based on the AuthenticateData values and the specified secret key and message byte array. This method also independently computes the message digest and compares it against the Message Digest authenticated attribute.

This method allows callers to verify a detached mac, where the contents is not part of the AuthenticatedData object.

Parameters:
secretKey - used in the MAC calculation.
msg - byte array to compute the message digest comparision. If not specified, this method will use the content stored in the EncapsulatedContentInfo to independently compute the message digest.
Returns:
true if mac verified, otherwise false.
Throws:
PKCSException - on verification errors.
IOException - on verification errors.

removeContent

public void removeContent()
                   throws IOException
Removes the content from the EncapsulatedContentInfo. This method can be called on a completed AuthenticatedData object to create an AuthenticatedData object with a detached mac value. To verify an AuthenticatedData object with a detached mac value, call the verify method, passing in the secret key and contents.

getObjectIdentifier

public ObjectIdentifier getObjectIdentifier()
Returns a reference to the ObjectIdentifer for the AuthenticateData object.
Overrides:
getObjectIdentifier in class PKCSDerObject
Returns:
an ObjectIdentifer for the AuthenticateData object.

getVersion

public BigInteger getVersion()
Returns a reference to the version for this object. BigInteger is an immutable object.
Returns:
the version for this object.

getOriginator

public OriginatorInfo getOriginator()
Returns a copy of the OriginatorInfo for this object, or null if the OriginatorInfo has not been set.
Returns:
the OriginatorInfo for this object, or null if it has not been set.

getRecipientInfos

public RecipientInfo[] getRecipientInfos()
Returns a copy of the array of recipientInfos for this object, or null if the recipientInfos have not been set.
Returns:
the recipientInfos info for this object, or null if it has not been set.

getMacAlgorithm

public AlgorithmId getMacAlgorithm()
                            throws IOException
Returns a copy of the MAC algorithm for this object, or null if the MAC algorithm has not been set.
Returns:
the MAC algorithm for this object, or null if it has not been set.

getDigestAlgorithm

public AlgorithmId getDigestAlgorithm()
                               throws IOException
Returns a copy of the Message Digest AlgorithmId for this object, or null if the Message Digest algorithm has not been set.
Returns:
the Message Digest algorithm for this object, or null if it has not been set.

getEncapsulatedContent

public EncapsulatedContentInfo getEncapsulatedContent()
Returns a copy of the EncapsulatedContentInfo for this object, or null if the EncapsulatedContentInfo has not been set.
Returns:
the EncapsulatedContentInfo for this object, or null if it has not been set.

getMac

public byte[] getMac()
Returns a copy the MAC byte array for this object, or null if the MAC byte array has not been set.
Returns:
the MAC byte array for this object, or null if it has not been set.

getAuthAttributes

public PKCSAttributes getAuthAttributes()
Returns a reference to the PKCSAttributes authenticated attributes for this object.
Returns:
PKCSAttributes authenticated attributes

getUnauthAttributes

public PKCSAttributes getUnauthAttributes()
Returns a reference to the PKCSAttributes unauthenticated attributes for this object.
Returns:
PKCSAttributes unauthenticated attributes

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 errors.

decode

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

equals

public boolean equals(Object other)
Determines if this AuthenticatedData 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.

getAuthAttribute

public PKCSAttribute getAuthAttribute(ObjectIdentifier oid)
Returns a reference to an authenticated attribute from the authenticated attribute set based on an ObjectIdentifier.
Parameters:
oid - ObjectIdentifier to match
Returns:
authenticated attribute matching the oid, null otherwise.

getUnauthAttribute

public PKCSAttribute getUnauthAttribute(ObjectIdentifier oid)
Returns a reference to an unauthenticated attribute from the unauthenticated attribute set based on an ObjectIdentifier.
Parameters:
oid - ObjectIdentifier to match
Returns:
unauthenticated attribute matching the oid, null otherwise.

hasAuthenticatedAttribute

public boolean hasAuthenticatedAttribute(ObjectIdentifier oid)
Determine if this AuthenticatedData has the authenticated attribute specified by the ObjectIdentifier.
Parameters:
oid - ObjectIdentifier to match
Returns:
true if the oid exists in the authenticated attribute set, false otherwise.

hasUnauthenticatedAttribute

public boolean hasUnauthenticatedAttribute(ObjectIdentifier oid)
Determine if this AuthenticatedData has the unauthenticated attribute specified by the ObjectIdentifier.
Parameters:
oid - ObjectIdentifier to match
Returns:
true if the oid exists in the unauthenticated attribute set, false otherwise.

toString

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

finalize

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