issrg.ac
Class AttributeCertificate

java.lang.Object
  issrg.ac.AttributeCertificate

All Implemented Interfaces:

java.lang.Cloneable

public class AttributeCertificate
extends java.lang.Object
implements java.lang.Cloneable

This is the class representing AttributeCertificate ASN.1 construct as per X.509(2000) draft v6. All other constructs are taken from it as well.

According to various versions of the draft, there can be ACs with explicit and implicit BER encoding. This class and all of its components are designed to support the difference.

This implementation extensively uses IAIK ASN.1 classes, so you may need to know their documentation before you can use or update the AC classes provided.

Note that all of the components are validating encoders and decoders and throw exceptions if the values specified are unacceptable (invalid BER encoding, unacceptable combination of values, etc checking syntax). However, it is your responsibility to verify that the AC includes only features allowed by the version specified (checking semantics).

The classes can decode any Attributes and Extensions. However, to automatically create the objects representing the specific attribute values or extensions, you need to register the object extending AttributeValue or Extension, using Attribute.registerAttribute(String, Class) or Extensions.registerExtension(String, Class) method respectively. In this way the instances of the corresponding classes will be created directly during the decoding process. If an unknown attribute or extension is encountered, the value will remain a generic AttributeValue or Extension respectively, and should be decoded by your code.

See Also:

Attribute.registerAttribute(String,Class), Extensions.registerExtension(String,Class)

Field Summary

protected AttributeCertificateInfo	acinfo
protected AlgorithmID	signatureAlgorithm
protected BIT_STRING	signatureValue
protected static boolean	USE_IMPLICIT_ENCODING This value specifies whether implicit or explicit tagging should be used when performing BER encoding or decoding.

Constructor Summary

protected	AttributeCertificate() The constructor is protected, because you shouldn't really be able to create empty ACs.
	AttributeCertificate(ASN1Object ao) This constructor decodes the X.509 AC from the given ASN1Object.
	AttributeCertificate(AttributeCertificateInfo aci, AlgorithmID sa, BIT_STRING sv) This constructor builds the Attribute Certificate out of its components.

Method Summary

protected static java.io.InputStream	acAsInputStream(java.lang.Object acBytes) This is a utility method that returns an InputStream for the given Object.
java.lang.Object	clone() This method clones the Attribute Certificate.
void	decode(ASN1Object ao) This method decodes X.509 Attribute Certificate from a given ASN1Object construct.
AttributeCertificateInfo	getACInfo() Returns the ACInfo component of the AC.
byte[]	getEncoded() This method returns a DER encoded Attribute Certificate so you can store it onto a disk or LDAP directory.
static java.lang.String	getHolderDN(java.lang.Object ac) This is a utility method that returns the holder of the given Attribute Certificate, or null, if it is not an Attribute Certificate.
AlgorithmID	getSignatureAlgorithm() Returns the SignatureAlgorithm component of the AC.
BIT_STRING	getSignatureValue() Returns the SignatureValue component of the AC.
static byte[]	getToBeSignedByteArray(java.lang.Object acBytes) This method returns a byte array of the ACInfo taken from the BER encoding of the AC as is, so you can check the signature.
static AttributeCertificate	guessEncoding(byte[] ac) This method lets you decode the byte array independent of the actual encoding of the AC in it.
static AttributeCertificate	guessEncoding(java.io.InputStream is) This method does the same as guessEncoding(byte[]), but operates on an InputStream.
static AttributeCertificate	guessEncoding(java.lang.Object ac) This method allows to parse either byte[] or Base64 encoded ACs (String must be passed in that case)
static boolean	isImplicit() Returns true if Implicit encoding of tags will be used.
void	setACInfo(AttributeCertificateInfo acinfo) Sets the ACInfo component of the AC.
static void	setImplicitEncoding(boolean implicit) This method sets the encoding of the AC to be implicit or explicit, depending on the value.
void	setSignatureAlgorithm(AlgorithmID signatureAlgorithm) Sets the SignatureAlgorithm component of the AC.
void	setSignatureValue(BIT_STRING signatureValue) Sets the SignatureValue component of the AC.
ASN1Object	toASN1Object() This method generates a ASN1Object.
java.lang.String	toString() This method generates a string representation of the Attribute Certificate.
java.lang.String	toString(java.lang.String ident) This method will use the specified indent to output the AC text.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

USE_IMPLICIT_ENCODING

protected static boolean USE_IMPLICIT_ENCODING

This value specifies whether implicit or explicit tagging should be used when performing BER encoding or decoding.

This value is being referred to by all ASN.1 objects when delivering toASN1Object result. By default it is set to true.

External code should not rely on this value while the AC is being decoded, when guessEncoding method is used.

acinfo

protected AttributeCertificateInfo acinfo

signatureAlgorithm

protected AlgorithmID signatureAlgorithm

signatureValue

protected BIT_STRING signatureValue

Constructor Detail

AttributeCertificate

protected AttributeCertificate()

The constructor is protected, because you shouldn't really be able to create empty ACs.

AttributeCertificate

public AttributeCertificate(ASN1Object ao)
                     throws CodingException

This constructor decodes the X.509 AC from the given ASN1Object.

Parameters:

ao - - the parsed ASN.1 structure

Throws:

CodingException, - if the ASN.1 does not represent a valid X.509 AC construct

CodingException

AttributeCertificate

public AttributeCertificate(AttributeCertificateInfo aci,
                            AlgorithmID sa,
                            BIT_STRING sv)

This constructor builds the Attribute Certificate out of its components. It is your responsibility to make sure that the signature algorithm is the same as inside AttributeCertificateInfo, and that the signature is computed over the BER encoding of the same AttributeCertificateInfo, encoded using IAIK library. Note that if you compute the signature using an encoding produced by a different library, the signature may not validate since there are multiple valid BER encodings and different libraries may produce different binary for the same ASN.1 construct.

Parameters:

aci - - the AttributeCertificateInfo with the contents of the X.509 Attribute Certificate

sa - - the AlgorithmID of the signature algorithm used to sign the X.509 Attribute Certificate

sv - - the BIT_STRING of the signature

Method Detail

isImplicit

public static boolean isImplicit()

Returns true if Implicit encoding of tags will be used. Note that the flag is static and affects all instances of AttributeCertificate.

getACInfo

public AttributeCertificateInfo getACInfo()

Returns the ACInfo component of the AC.

Returns:

AttributeCertificateInfo with the content of the Attribute Certificate

setACInfo

public void setACInfo(AttributeCertificateInfo acinfo)

Sets the ACInfo component of the AC.

Parameters:

acinfo - - the AttributeCertificateInfo with the contents of the AC

getSignatureAlgorithm

public AlgorithmID getSignatureAlgorithm()

Returns the SignatureAlgorithm component of the AC.

Returns:

AlgorithmID of the algorithm used to sign the AC

setSignatureAlgorithm

public void setSignatureAlgorithm(AlgorithmID signatureAlgorithm)

Sets the SignatureAlgorithm component of the AC. You should make sure that this is the same as in AttributeCertificateInfo.

Parameters:

signatureAlgorithm - - the AlgorithmID of the algorithm used to sign the AC

getSignatureValue

public BIT_STRING getSignatureValue()

Returns the SignatureValue component of the AC.

Returns:

BIT_STRING of the signature

setSignatureValue

public void setSignatureValue(BIT_STRING signatureValue)

Sets the SignatureValue component of the AC.

Parameters:

signatureValue - - the BIT_STRING containing the signature bytes

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

This method generates a ASN1Object. It can be encoded as BER using IAIK library.

Returns:

ASN1Object that is the X.509 AC construct

Throws:

CodingException - if there was an error encoding the AC

decode

public void decode(ASN1Object ao)
            throws CodingException

This method decodes X.509 Attribute Certificate from a given ASN1Object construct. This object will represent the AC that has been decoded.

Parameters:

ao - - the ASN1Object, as decoded by IAIK library

Throws:

CodingException - if the provided ASN1Object is not a v1 or v2 X.509 Attribute Certificate

toString

public java.lang.String toString()

This method generates a string representation of the Attribute Certificate. It will indent structures, so it will look nicer.

Overrides:

toString in class java.lang.Object

Returns:

the String representation of the AC.

toString

public java.lang.String toString(java.lang.String ident)

This method will use the specified indent to output the AC text.

Returns:

the String representation of the AC with the given indent

clone

public java.lang.Object clone()

This method clones the Attribute Certificate. It returns an identical copy of the Attribute Certificate.

Overrides:

clone in class java.lang.Object

Returns:

Object that can be cast to AttributeCertificate, or null, if there was a problem when creating the clone.

getEncoded

public byte[] getEncoded()
                  throws CodingException

This method returns a DER encoded Attribute Certificate so you can store it onto a disk or LDAP directory.

Returns:

byte[] filled in with the bytes of the DER encoding

Throws:

iaik.asn1.CodingException - if an encoding error occurred

CodingException

getToBeSignedByteArray

public static byte[] getToBeSignedByteArray(java.lang.Object acBytes)
                                     throws CodingException

This method returns a byte array of the ACInfo taken from the BER encoding of the AC as is, so you can check the signature.

This method does not verify that it actually gets the BER encoded AC, and not just an arbitrary byte array.

Parameters:

acBytes - is the array of bytes of the BER encoded AC, or a String of the Base-64 encoded BER encoded AC

Returns:

byte array from the acBytes, corresponding to the ACInfo part of it

Throws:

CodingException - in some cases when it can detect that the AC is malformed; note that proper checks are left to the caller to speed up: the caller may have constructed the AttributeCertificate object already

acAsInputStream

protected static java.io.InputStream acAsInputStream(java.lang.Object acBytes)

This is a utility method that returns an InputStream for the given Object. It assumes that if it is a byte[], then it is a BER-encoded AC; if it is a String, it is a Base-64 encoding of that; no other Object are supported

Parameters:

acBytes - is the array of bytes of the BER encoded AC, or a String of the Base-64 encoded BER encoded AC

Returns:

InputStream to read the BER-encoded AC

setImplicitEncoding

public static void setImplicitEncoding(boolean implicit)

This method sets the encoding of the AC to be implicit or explicit, depending on the value. The encoding will be enforced for all components of the AC after calling this method.

Also the value of the flag is used when decoding an AC. If the AC is encoded with Explicit encoding, but the flag says to use Implicit encoding, an AC decoding error will occur at run-time. It is advised that guessEncoding method is used to decode an AC independent of whether it is Implicitly or Explicitly encoded.

Parameters:

implicit - specifies if the AC should be encoded implicitly or not

guessEncoding

public static AttributeCertificate guessEncoding(byte[] ac)
                                          throws CodingException

This method lets you decode the byte array independent of the actual encoding of the AC in it. It will sequentially attempt to decode using USE_IMPLICIT_ENCODING flag value, then, if that fails with an exception, to decode using the opposite value of the flag.

Note that the value of the USE_IMPLICIT_ENCODING flag changes during execution of this method, so external code should not access the flag while decoding, only the AC objects should.

Parameters:

ac - is the BER encoding of an X.509 Attribute Certificate

Returns:

issrg.ac.AttributeCertificate object

Throws:

CodingException - if neither encoding helped to decode the AC

guessEncoding

public static AttributeCertificate guessEncoding(java.lang.Object ac)
                                          throws CodingException

This method allows to parse either byte[] or Base64 encoded ACs (String must be passed in that case)

Parameters:

ac - - the Attribute Certificate, either as a byte array or as a Base64 String

Returns:

the decoded AttributeCertificate

Throws:

CodingException, - if it is neither implicitly, nor explicitly encoded Attribute Certificate

CodingException

guessEncoding

public static AttributeCertificate guessEncoding(java.io.InputStream is)
                                          throws CodingException,
                                                 java.io.IOException

This method does the same as guessEncoding(byte[]), but operates on an InputStream.

Parameters:

is - - the InputStream containing the BER encoded Attribute Certificate

Returns:

the decoded AttributeCertificate

Throws:

CodingException, - if it is neither implicitly, nor explicitly encoded Attribute Certificate

CodingException

java.io.IOException

getHolderDN

public static java.lang.String getHolderDN(java.lang.Object ac)

This is a utility method that returns the holder of the given Attribute Certificate, or null, if it is not an Attribute Certificate.

Parameters:

ac - - the AttributeCertificate, either as a byte array or a Base64 encoded String

Returns:

String representation of the Holder DN, or null, if it is not an AC