iaik.x509.attr.attributes

Class Clearance

java.lang.Object

iaik.asn1.structures.AttributeValue

iaik.x509.attr.attributes.Clearance

All Implemented Interfaces:

ASN1Type

public class Clearance
extends AttributeValue

The Clearance attribute.

The X.509 Attribute Certificate profile (RFC 5755) specifies the Clearance attribute to be included as attribute in an AttributeCertificate for providing clearance (associated with security labeling) information about the AC holder.

Each attribute is associated with a specific attribute type object identifier. The OID for the Clearance attribute is defined as follows:

 id-at-clearance  OBJECT IDENTIFIER ::=
          { joint-iso-ccitt(2) ds(5) module(1)
 selected-attribute-types(5) clearance (55) }
 

which corresponds to the OID string "2.5.1.5.55".

The ASN.1 structure of the Clearance attribute is as follows (see RFC 5755):

 Clearance  ::=  SEQUENCE {
   policyId   OBJECT IDENTIFIER,
   classList  ClassList DEFAULT {unclassified},
   securityCategories
              SET OF SecurityCategory OPTIONAL
 }

 ClassList  ::=  BIT STRING {
   unmarked       (0),
   unclassified   (1),
   restricted     (2)
   confidential   (3),
   secret         (4),
   topSecret      (5)
 }

 SecurityCategory ::= SEQUENCE {
   type      [0]  OBJECT IDENTIFIER,
   value     [1]  ANY DEFINED BY type
 }
 

Note that the previous AttributeCertificate specification (RFC 3281) has tagged the components of the Clearance attribute context specific:

 Clearance  ::=  SEQUENCE {
   policyId  [0] OBJECT IDENTIFIER,
   classList [1] ClassList DEFAULT {unclassified},
   securityCategories
             [2] SET OF SecurityCategory OPTIONAL
 }
 

This implementation can parse both Clearance attribute encoding styles, but (by default) returns the new (RFC 5755 style) encoding when calling method toASN1Object.

Any Clearance object is associated with a policyId identifying the security policy which defines how to interprete the contents of the classList and securityCategories fields.
The classList field maybe used for access control decisions. The default security classification hierachy is: unmarked (bit 0), unclassified (bit 1), restricted (bit 2), confidential (bit 3), secret (bit 4), topSecret (bit 5). The security policy may define additional security classification values and their position and meaning in the hierachy, however, it must not override the values of the basic classificaion hierachy above. An application may use static method #setSecurityClassificationName(int, String) setSecurityClassificationName} for introducing a new security classification by its name and position in the classList bit string. For instance, a security classification with name "high confidential" indicated by bit 6 (integer 64) may be registered by calling:

 Clearance.setSecurityClassificationName(64, "high confidential");
 

Security categories, if included, provide further authorization information as specified by security policy in force. Any SecurityCategory consists of two components: an object identifier giving the type of the SecurityCategory and an value that may have any ASN.1 representation:

 SecurityCategory ::= SEQUENCE {
   type  [0] OBJECT IDENTIFIER,
   value [1] ANY DEFINED BY type 
 }
 

The ASN.1 representation of the value generally may be different for different types of SecurityCategories. For that reason applications may implement their own SecurityCategories by extending the abstract class SecurityCategory and registering their implementation to may be recognized when parsing a Clearance attribute, e.g.:

 public class MySecurityCategory extends SecurityCategory {
 ...
 // the MySecurityCategory type:
   public static final ObjectID type = ...;
 ...
 }
 ...
 // register the implementation:
 SecurityCategory.register(MySecurityCategory.type, MySecurityCategory.class);
 

When calling method getSecurityCategories for getting the SecurityCategories included in a Clearance attribute, any SecurityCategory for which no implementation has been registered will be returned as an UnknownSecurityCategory allowing to get as much information as possible from the unknown security category.

When creating a new Clearance the security policy identifier for the security policy in used has to be supplied. Subsequently method setClassList and/or method setSecurityCategories may be used for specifying a particular class list and security categories for the Clearance attribute. If no classList is exlicitly specified the default security classification value (unclassified) is assumed. For examlpe:

 ObjectID policyId = ...; 
 Clearance clearance = new Clearance(policyId);
 int classList = Clearance.TOP_SECRET;
 clearance.setClassList(classList);
 SecurityCategory[] categories = ...;
 clearance.setSecurityCategories(categories);
 

Finally use method addAttribute of class AttributeCertificate to add the Clearance object as attribute to an AttributeCertificate:

 // create attribute certificate
 AttributeCertificate ac = new AttributeCertificate();
 ...
 // set holder, issuer, validity,...
 ...
 // add Clearance attribute
 ac.addAttribute(new Attribute(clearance));
 ...
 // sign and encode certificate
 ac.sign(...);
 byte[] encodedAc = ac.getEncoded(); 
 

On the receiving side use method getAttribute of class AttributeCertificate to get a Clearance attribute -- if included -- from an Attribute Certificate:

 // the AttributeCertificate:
 AttributeCertificate ac = new AttributeCertificate(encodedAc);
 ...
 // verify signature, check validity,...
 ...
 // query for Clearance attribute:
 Attribute clearanceAttribute = ac.getAttribute(Clearance.oid);
 if (clearanceAttribute != null) {
   // in our example we know that we have a single-valued Clearance attribute only
   Clearance clearance = (Clearance)clearanceAttribute.getAttributeValue();
   // get PolicyId
   ObjectID policyId = clearance.getPolicyId();
   // class list
   System.out.println("Class list: " + clearance.getClassListBitNames());
   // topSecret?
   if (clearance.isSecurityClassificationValueSet(Clearance.TOP_SECRET)) {
     ...
   }
   // get security categories
   SecurityCategory[] securityCategories = clearance.getSecurityCategories();
   for (int i = 0; i < securityCategories.length; i++) {
     System.out.println("SecurityCategory " + securityCategories[i].getName() + ":");
     ...
     // application specific processing of security category
     ...
   }
 }  
 

See Also:

AttributeCertificate, SecurityCategory, UnknownSecurityCategory, Attribute, BIT_STRING, ObjectID

Field Summary

Fields

Modifier and Type	Field and Description
static int	CONFIDENTIAL Predefined classList value "confidential" (3);
static ObjectID	oid The attributeType object identifier of the Clearance attribute.
static int	RESTRICTED Predefined classList value "restricted" (2);
static int	SECRET Predefined classList value "secret" (4);
static int	TOP_SECRET Predefined classList value "top-secret" (5);
static int	UNCLASSIFIED Predefined classList value "unclassified" (1);
static int	UNMARKED Predefined classList value "unmarked" (0);

Constructor Summary

Constructors

Constructor and Description
Clearance() Empty default constructor.
Clearance(ASN1Object obj) Crerates an Clearance from its ASN.1 representation.
Clearance(ObjectID policyId) Creates an Clearance for the given policy id.

Method Summary

Methods

Modifier and Type	Method and Description
void	decode(ASN1Object obj) Decodes the given ASN.1 Clearance object for parsing the internal structure.
ObjectID	getAttributeType() Returns the OID identifying the Clearance attribute type.
int	getClassList() Returns the classList value as an integer.
java.lang.String	getClassListAsBinaryString() Returns the classList as a binary string.
boolean[]	getClassListAsBooleanArray() Returns the classList as a boolean array.
java.lang.String	getClassListBitNames() Returns the names of the set classList bits of this Clearance (if names are registered).
ObjectID	getPolicyId() Returns the policy id of this Clearance object.
SecurityCategory[]	getSecurityCategories() Returns the SecurityCategories that may be included in this Clearance.
static java.lang.String	getSecurityClassificationName(int securityClassificationValue) Gets the name registered for a particular security classification value.
boolean	isClassListBitSet(int bitPosition) Asks whether the bit at the given position is set in the classList bit string.
boolean	isSecurityClassificationValueSet(int securityClassificationValue) Asks whether the specified security classification value is set.
void	setClassList(int classList) Sets the class list.
void	setSecurityCategories(SecurityCategory[] securityCategories) Sets the SecurityCategories of this Clearance.
static void	setSecurityClassificationName(int securityClassificationValue, java.lang.String securityClassficationName) Allows to allocate a String name to a security classificatoin value.
ASN1Object	toASN1Object() Returns this Clearance as ASN1Object.
ASN1Object	toASN1Object(boolean tagComponents) Returns this Clearance as ASN1Object.
java.lang.String	toString() Returns a string representation of this Clearance.
java.lang.String	toString(boolean detailed) Returns a string representation of this Clearance.

Methods inherited from class iaik.asn1.structures.AttributeValue

getName, multipleAllowed

Methods inherited from class java.lang.Object

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

Field Detail

oid

public static final ObjectID oid

The attributeType object identifier of the Clearance attribute. The corresponding OID string is "2.5.1.5.55".

UNMARKED

public static final int UNMARKED

Predefined classList value "unmarked" (0);

See Also:

Constant Field Values

UNCLASSIFIED

public static final int UNCLASSIFIED

Predefined classList value "unclassified" (1);

See Also:

Constant Field Values

RESTRICTED

public static final int RESTRICTED

Predefined classList value "restricted" (2);

See Also:

Constant Field Values

CONFIDENTIAL

public static final int CONFIDENTIAL

Predefined classList value "confidential" (3);

See Also:

Constant Field Values

SECRET

public static final int SECRET

Predefined classList value "secret" (4);

See Also:

Constant Field Values

TOP_SECRET

public static final int TOP_SECRET

Predefined classList value "top-secret" (5);

See Also:

Constant Field Values

Constructor Detail

Clearance

public Clearance()

Empty default constructor. Required for dynamic object creation. Shall not be used by an application!

Clearance

public Clearance(ObjectID policyId)

Creates an Clearance for the given policy id.

The policyID identifies the security policy which defines how to interprete the contents of the classList and securityCategories fields.

Parameters:

policyId - the OID identifying the security policy in force

Throws:

java.lang.NullPointerException - if null is specified as policy id

Clearance

public Clearance(ASN1Object obj)
          throws CodingException

Crerates an Clearance from its ASN.1 representation.

Parameters:

obj - the Clearance as ASN1Object

Throws:

CodingException - if an error occurs when parsing the ASN1Object

Method Detail

setSecurityClassificationName

public static void setSecurityClassificationName(int securityClassificationValue,
                                 java.lang.String securityClassficationName)

Allows to allocate a String name to a security classificatoin value.

Per default names are registered for the reserved basic security classification hierachy ("unmarked" (0), "unclassified" (1), "restricted" (2), "confidential" (3), "secret" (4), and "topSecret" (5)). When, for instance, having a Clearance attribute with a classList field where bit 5 is set only (security classification value "100000", integer 32), the String "topSecret" is returned when calling method getClassListBitNames():

 System.out.println("Class list: " + clearance.getClassListBitNames());
 

An application that uses security classification values beyound the basic security classification hierachy may want to register names for the additional security classification values. A new security classification value can be registered by its name and position in the classList bit string. For instance, a security classification with name "high confidential" indicated by bit 6 ("1000000", integer 64) may be registered by calling:

 Clearance.setSecurityClassificationName(64, "high confidential");
 

When now calling method getClassListBitNames() of a Clearance object with a classList field where bit 6 is set only (security classification value "1000000", integer 64), the String "high confidential" is returned.

For asking for the registerd name of a particular security classification value use static methog getSecurityClassificationName, e.g.:

 System.out.println(Clearance.getClassListName(Clearance.TOP_SECRET));
 

Parameters:

securityClassificationValue - the security classification value for which a name shall be registered (the given value is the integer representation of the security classification bit-string, e.g. 64 for "1000000")

securityClassficationName - the name of the security classification value

Throws:

java.lang.IllegalArgumentException - if the given security classifaction value belongs to the reserved basic hierachy

getSecurityClassificationName

public static java.lang.String getSecurityClassificationName(int securityClassificationValue)

Gets the name registered for a particular security classification value.

Per default names are registered for the reserved basic security classification hierachy ("unmarked" (0), "unclassified" (1), "restricted" (2), "confidential" (3), "secret" (4), and "topSecret" (5)). When, for instance, having a Clearance attribute with a classList field where bit 5 is set only (security classification value "100000", integer 32), the String "topSecret" is returned when calling method getClassListBitNames():

 System.out.println("Class list: " + clearance.getClassListBitNames());
 

An application that uses security classification values beyound the basic security classification hierachy may want to register names for the additional security classification values.

Parameters:

securityClassificationValue - the security classification value for which to get the registered name (the given value is the integer representation of the security classification bit-string, e.g. 32 for "100000")

Returns:

the name of the given security classification value, e.g. "topSecret" for security classification value 32, or null if no name is registered for the specified value

getPolicyId

public ObjectID getPolicyId()

Returns the policy id of this Clearance object.

The policyID identifies the security policy which defines how to interprete the contents of the classList and securityCategories fields. return the OID identifying the security policy in force

setClassList

public void setClassList(int classList)
                  throws java.lang.IllegalArgumentException

Sets the class list.

The classList field maybe used for access control decisions. The default security classification hierachy is: unmarked (bit 0), unclassified (bit 1), restricted (bit 2), confidential (bit 3), secret (bit 4), topSecret (bit 5). The security policy may define additional security classification values and their position and meaning in the hierachy, however, it must not override the values of the basic classificaion hierachy above. An application may use static method #setSecurityClassificationName(int, String) setSecurityClassificationName} for introducing a new security classification by its name and position in the classList bit string. For instance, a security classification with name "high confidential" indicated by bit 6 (integer 64) may be registered by calling:

 Clearance.setSecurityClassificationName(64, "high confidential");
 

Note the "big endian" representation of the BIT STRING representing the classList value: the least significant bit indicates the purpose with the lowest bit value, meaning that the integer value 1 specifies the "unmarked" bit, and the integer value 32 (binary 100000, hexadecimal 20) specifies the "topSecret" value, assuming the default classList hierachy as specified by RFC 5755:

 ClassList ::= BIT STRING {
   unmarked (0),
   unclassified (1),
   restricted (2),
   confidential (3),
   secret (4),
   topSecret (5) } 
 

Parameters:

classList - the class list as integer representation

Throws:

java.lang.IllegalArgumentException - if the supplied class list is invalid (less than 1)

See Also:

getClassList()

getClassList

public int getClassList()

Returns the classList value as an integer.

Note the "big endian" representation of the BIT STRING representing the classList value: the least significant bit indicates the purpose with the lowest bit value, meaning that the integer value 1 specifies the "unmarked" bit, and the integer value 32 (binary 100000, hexadecimal 20) specifies the "topSecret" value, assuming the default classList hierachy as specified by RFC 5755:

 ClassList ::= BIT STRING {
   unmarked (0),
   unclassified (1),
   restricted (2),
   confidential (3),
   secret (4),
   topSecret (5) } 
 

Use method getClassListAsBinaryString() for get a binary string representation of the class list, or method getClassListAsBooleanArray for getting a boolean array where each true indicates a set bit in the class list bit-string. Method getClassListBitNames() returns the names of the set classList bits (if names are registered for the set bits), and method isSecurityClassificationValueSet may be used to query if some specific security classification value is set.

Returns:

the classList value as integer representation

See Also:

setClassList(int), getClassListAsBinaryString(), getClassListAsBooleanArray(), getClassListBitNames(), isSecurityClassificationValueSet(int)

isSecurityClassificationValueSet

public boolean isSecurityClassificationValueSet(int securityClassificationValue)

Asks whether the specified security classification value is set. For example, clearance.isSecurityClassificationValueSet(Clerance.SECRET) returns true if the SECRET (4) security classification value is set:

 ClassList ::= BIT STRING {
   unmarked (0),
   unclassified (1),
   restricted (2),
   confidential (3),
   secret (4),
   topSecret (5) } 
 

Note that the supplied securityClassificationValue does not reflect the bit position in the bit string, rather it is the value of the integer representation of this bit-string value. For instance, when asking if the security classification value SECRET is set, do not specify the bit position (4), rather the corresponding integer value (16):

 if (clearance.isSecurityClassificationValueSet(Clearance.SECRET)) {
   ...
 }
 

is the same as

 if (clearance.isSecurityClassificationValueSet(16)) {
  ...
 }
 

Use method is isClassListBitSet if you want to ask if a bit at a particular position is set.

Returns:

true if the specified security classification value is set, false if it is not set

isClassListBitSet

public boolean isClassListBitSet(int bitPosition)

Asks whether the bit at the given position is set in the classList bit string. For example, clearance.isClassListBitSet(4) returns true if the SECRET (4) security classification value is set:

 ClassList ::= BIT STRING {
   unmarked (0),
   unclassified (1),
   restricted (2),
   confidential (3),
   secret (4),
   topSecret (5) } 
 

Note that the supplied securityClassificationValue does not reflect the integer representation of the corrseponding security classification value. Rather it is the bit position in the classList bit string. Use method is isSecurityClassificationValueSet if you want to ask if particular security classification value is set.

Returns:

true if the specified classList bit is set, false if it is not set

getClassListAsBooleanArray

public boolean[] getClassListAsBooleanArray()

Returns the classList as a boolean array.
The boolean array will contain at least 6 elements, corresponding to the number of pre-defined classList values (see RFC 5755):

 ClassList ::= BIT STRING {
   unmarked (0),
   unclassified (1),
   restricted (2),
   confidential (3),
   secret (4),
   topSecret (5) } 
 

Element 0 is unmarked, element 1 unclassified, etc. For instance, if classList is "restricted (2)", the boolean array will look like:

 { false, false, true, false, false, false }
 

Returns:

the class list as boolean array indicating which class bits are set

getClassListAsBinaryString

public java.lang.String getClassListAsBinaryString()

Returns the classList as a binary string.
The length of the binary string will at least be 6, corresponding to the number of pre-defined classList values (see RFC 5755):

 ClassList ::= BIT STRING {
   unmarked (0),
   unclassified (1),
   restricted (2),
   confidential (3),
   secret (4),
   topSecret (5) } 
 

The leftmost character indicates the unmarked value, the next character the unclassified value, etc. For instance, if classList is "restricted (2)", the binary string will look like:

 "001000"
 

The string output is in "little endian" fashion in order to correspond with the output of method getClassListAsBooleanArray() and to allow queries for checking if some particular bit is set.

Returns:

the class list as binary string indicating which class bits are set

getClassListBitNames

public java.lang.String getClassListBitNames()

Returns the names of the set classList bits of this Clearance (if names are registered). By default names are registered for the six classList bits defined by RFC 5755:

 ClassList ::= BIT STRING {
   unmarked (0),
   unclassified (1),
   restricted (2),
   confidential (3),
   secret (4),
   topSecret (5) } 
 

For instance, if classList is "restricted (2) and secret (4)", the string returned by this method will look like:

 "restricted, secret"
 

Returns:

the names of the classList bits (e.g. "restricted, secret"), or null if no names are registered

setSecurityCategories

public void setSecurityCategories(SecurityCategory[] securityCategories)

Sets the SecurityCategories of this Clearance.

If present, the security-categories provide further authorization information. How to interpret the SecurityCategories may be specified by the security policy in force.
Any SecurityCategory consists of two components: an object identifier giving the type of the SecurityCategory and an value that may have any ASN.1 representation:

 SecurityCategory ::= SEQUENCE {
   type  [0] OBJECT IDENTIFIER,
   value [1] ANY DEFINED BY type 
 }
 

The ASN.1 representation of the value generally may be different for different types of SecurityCategories. For that reason applications may implement their own SecurityCategories by extending the abstract class SecurityCategory and registering their implementation to may be recognized when parsing a Clearance attribute, e.g.:

 public class MySecurityCategory extends SecurityCategory {
 ...
 // the MySecurityCategory type:
   public static final ObjectID type = ...;
 ...
 }
 ...
 // register the implementation:
 SecurityCategory.register(MySecurityCategory.type, MySecurityCategory.class);
 

When calling method getSecurityCategories for getting the SecurityCategories included in a Clearance attribute, any SecurityCategory for which no implementation has been registered will be returned as an UnknownSecurityCategory allowing to get as much information as possible from the unknown security category.

Parameters:

securityCategories - the security categories to be set

getSecurityCategories

public SecurityCategory[] getSecurityCategories()

Returns the SecurityCategories that may be included in this Clearance.

If present, the security-categories provide further authorization information. How to interpret the SecurityCategories may be specified by the security policy in force.
Any SecurityCategory consists of two components: an object identifier giving the type of the SecurityCategory and an value that may have any ASN.1 representation:

 SecurityCategory ::= SEQUENCE {
   type  [0] OBJECT IDENTIFIER,
   value [1] ANY DEFINED BY type 
 }
 

The ASN.1 representation of the value generally may be different for different types of SecurityCategories. For that reason applications may implement their own SecurityCategories by extending the abstract class SecurityCategory and registering their implementation to may be recognized when parsing a Clearance attribute, e.g.:

 public class MySecurityCategory extends SecurityCategory {
 ...
 // the MySecurityCategory type:
   public static final ObjectID type = ...;
 ...
 }
 ...
 // register the implementation:
 SecurityCategory.register(MySecurityCategory.type, MySecurityCategory.class);
 

When calling method getSecurityCategories for getting the SecurityCategories included in a Clearance attribute, any SecurityCategory for which no implementation has been registered will be returned as an UnknownSecurityCategory allowing to get as much information as possible from the unknown security category.

Returns:

the security categories included in this Clearance; the array maybe empty if no security categories are included

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes the given ASN.1 Clearance object for parsing the internal structure.

Parameters:

obj - the Clearance as ASN1Object

Throws:

CodingException - if the encoding is invalid

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns this Clearance as ASN1Object.

The ASN.1 representation returned by this method follows the new (RFC 5755 style) syntax where the Clearance attribute components are not tagged. You may call method toASN1Object(true) if you want to use the old (RFC 3281 style) syntax where the components are tagged.

Returns:

this Clearance as ASN1Object

Throws:

CodingException - if an error occurs when building the ASN1Object

toASN1Object

public ASN1Object toASN1Object(boolean tagComponents)
                        throws CodingException

Returns this Clearance as ASN1Object.

Parameters:

tagComponents - whether to tag the Clearance components according to the old (RFC 5755 style) syntax

Returns:

this Clearance as ASN1Object

Throws:

CodingException - if an error occurs when building the ASN1Object

getAttributeType

public ObjectID getAttributeType()

Returns the OID identifying the Clearance attribute type.

Specified by:

getAttributeType in class AttributeValue

Returns:

the OID ("2.5.1.5.55") identifying the Clearance attribute type.

toString

public java.lang.String toString()

Returns a string representation of this Clearance.

Specified by:

toString in class AttributeValue

Returns:

this Clearance as string

toString

public java.lang.String toString(boolean detailed)

Returns a string representation of this Clearance.

Parameters:

detailed - whether to give some more detailed information

Returns:

this Clearance as string