public class Clearance extends AttributeValue
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 ... } }
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 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.
|
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.
|
getName, multipleAllowed
public static final ObjectID oid
public static final int UNMARKED
public static final int UNCLASSIFIED
public static final int RESTRICTED
public static final int CONFIDENTIAL
public static final int SECRET
public static final int TOP_SECRET
public Clearance()
public Clearance(ObjectID policyId)
The policyID identifies the security policy which defines how to
interprete the contents of the classList
and securityCategories
fields.
policyId
- the OID identifying the security policy in forcejava.lang.NullPointerException
- if null
is specified
as policy idpublic Clearance(ASN1Object obj) throws CodingException
obj
- the Clearance as ASN1ObjectCodingException
- if an error occurs when parsing the
ASN1Objectpublic static void setSecurityClassificationName(int securityClassificationValue, java.lang.String securityClassficationName)
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));
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
valuejava.lang.IllegalArgumentException
- if the given security classifaction value
belongs to the reserved basic hierachypublic static java.lang.String getSecurityClassificationName(int securityClassificationValue)
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.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")null
if no name is registered for the
specified valuepublic ObjectID getPolicyId()
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
public void setClassList(int classList) throws java.lang.IllegalArgumentException
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) }
classList
- the class list as integer representationjava.lang.IllegalArgumentException
- if the supplied class list is invalid
(less than 1)getClassList()
public int getClassList()
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.setClassList(int)
,
getClassListAsBinaryString()
,
getClassListAsBooleanArray()
,
getClassListBitNames()
,
isSecurityClassificationValueSet(int)
public boolean isSecurityClassificationValueSet(int securityClassificationValue)
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.true
if the specified security classification
value is set, false
if it is not setpublic boolean isClassListBitSet(int bitPosition)
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.true
if the specified classList bit
is set, false
if it is not setpublic boolean[] getClassListAsBooleanArray()
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 }
public java.lang.String getClassListAsBinaryString()
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.public java.lang.String getClassListBitNames()
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"
null
if no names are registeredpublic void setSecurityCategories(SecurityCategory[] securityCategories)
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.securityCategories
- the security categories to be setpublic SecurityCategory[] getSecurityCategories()
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.public void decode(ASN1Object obj) throws CodingException
Clearance
object for parsing
the internal structure.obj
- the Clearance as ASN1ObjectCodingException
- if the encoding is invalidpublic ASN1Object toASN1Object() throws CodingException
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.
CodingException
- if an error occurs when building the ASN1Objectpublic ASN1Object toASN1Object(boolean tagComponents) throws CodingException
tagComponents
- whether to tag the Clearance components according to the
old (RFC 5755 style) syntaxCodingException
- if an error occurs when building the ASN1Objectpublic ObjectID getAttributeType()
getAttributeType
in class AttributeValue
public java.lang.String toString()
toString
in class AttributeValue
public java.lang.String toString(boolean detailed)
detailed
- whether to give some more detailed information