Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

iaik.smime.ess
Class ESSSecurityLabel

java.lang.Object
  extended by iaik.asn1.structures.AttributeValue
      extended by iaik.smime.ess.ESSAttributeValue
          extended by iaik.smime.ess.ESSSecurityLabel
All Implemented Interfaces:
ASN1Type
public class ESSSecurityLabel
extends ESSAttributeValue

The S/MIMEv3 ESS ESSSecurityLabel attribute.

The Enhanced Security Services for S/MIMEv3 (ESS) (RFC 2634) specifies the ESSSecurityLabel attribute to may be included as signed attribute in a SignerInfo for providing some kind of "access control" mechanism for the contents of a message: 

 ESSSecurityLabel ::= SET {
   security-policy-identifier SecurityPolicyIdentifier,
   security-classification SecurityClassification OPTIONAL,
   privacy-mark ESSPrivacyMark OPTIONAL,
   security-categories SecurityCategories OPTIONAL }

 id-aa-securityLabel OBJECT IDENTIFIER ::= { iso(1) member-body(2)
    us(840) rsadsi(113549) pkcs(1) pkcs-9(9) smime(16) id-aa(2) 2}

 SecurityPolicyIdentifier ::= OBJECT IDENTIFIER

 SecurityClassification ::= INTEGER {
   unmarked (0),
   unclassified (1),
   restricted (2),
   confidential (3),
   secret (4),
   top-secret (5) } (0..ub-integer-options)

 ub-integer-options INTEGER ::= 256

 ESSPrivacyMark ::= CHOICE {
   pString      PrintableString (SIZE (1..ub-privacy-mark-length)),
   utf8String   UTF8String (SIZE (1..MAX))
 }

 ub-privacy-mark-length INTEGER ::= 128
 
 SecurityCategories ::= SET SIZE (1..ub-security-categories) OF SecurityCategory

 ub-security-categories INTEGER ::= 64
 
 SecurityCategory ::= SEQUENCE {
   type  [0] OBJECT IDENTIFIER,
   value [1] ANY DEFINED BY type -- defined by type
 }
Any ESSSecurityLabel is associated with a security-policy-identifier identifying the security policy in force to which the security label relates. It indicates the semantics of the other security label components. A security policy is a set of criteria for the provision of security services.
An ESSSecurityLabel optionaly may contain a security-classification component providing the possibility to "classify" the kind of access an entity is allowed to have to the contents of the message. If present, a security-classification may have one of a hierarchical list of values. The basic security-classification hierarchy is defined in ESS, but the use of these values is defined by the security-policy in force. Additional values of security-classification, and their position in the hierarchy, may also be defined by a security-policy as a local matter or by bilateral agreement. The basic security-classification hierarchy is, in ascending order: unmarked, unclassified, restricted, confidential, secret, top-secret. However, in any case, the security policy in force (identified by the eSSSecurityLabel security-policy-identifier) defines the SecurityClassification integer values and their meanings.
If present, the eSSSecurityLabel privacy-mark is not used for access control. The content of the eSSSecurityLabel privacy-mark may be defined by the security policy in force (identified by the eSSSecurityLabel security-policy-identifier) which may define a list of values to be used. Alternately, the value may be determined by the originator of the security-label.
security-categories, if included, provide further granularity for the sensitivity of the message. The security policy in force (identified by the eSSSecurityLabel security-policy-identifier) is used to indicate the syntaxes that are allowed to be present in the eSSSecurityLabel security-categories. Alternately, the security-categories and their values may be defined by bilateral agreement. Any SecurityCategory consists of two components: an object identifier giving the type of the SecurityCategory and an value that may habe any ASN.1 representation: 
 SecurityCategory ::= SEQUENCE {
   type  [0] OBJECT IDENTIFIER,
   value [1] ANY DEFINED BY type -- 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 an ESSSecurityLabel, e.g.: 
 public class MySecurityCategory extends SecurityCategory {
 ...
 // the MySecurityCategory type:
   public static final ObjectID type = ...;
 ...
 }
 ...
 // register the implementation:
 ESSSecurityLabel.register(MySecurityCategory.type, MySecurityCategory.class);
When calling method getSecurityCategories for getting the SecurityCategories included in an ESSSecurityLabel, 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 ESSSecurityLabel the security-policy-identifier associated with the label has to be supplied. Subsequently the optional security-classification, privacy-mark or security-categories components may be set as required, e.g.: 

 ObjectID securityPolicyID = ...; 
 ESSSecurityLabel label = new ESSSecurityLabel(securityPolicyID);
 int securityClassifiaction = ...;
 label.setSecurityClassification(securityClassifiaction);
 PrintableString privacyMark = ...;
 label.setPrivacyMark(us);
 SecurityCategory[] categories = ...;
 label.setSecurityCategories(categories);

See Also:
SecurityCategory, UnknownSecurityCategory

Field Summary
static int CONFIDENTIAL
          Predefined security classification "confidential" (3);
static ObjectID oid
          The attributeType object identifier of this ESSSecurityLabel attribute.
static int RESTRICTED
          Predefined security classification "restricted" (2);
static int SECRET
          Predefined security classification "secret" (4);
static int TOP_SECRET
          Predefined security classification "top-secret" (4);
static int UB_INTEGER_OPTIONS
          Upper bound (64) for security classification value.
static int UB_PRIVACY_MARK_LENGTH
          Maximum allowed length (128) for PrintableString choice of ESSPrivacyMark.
static int UB_SECURITY_CATEGORIES
          Maximum allowed number (64) of security categories included.
static int UNCLASSIFIED
          Predefined security classification "unclassified" (1);
static int UNMARKED
          Predefined security classification "unmarked" (0);
 
Constructor Summary
ESSSecurityLabel()
          Empty default constructor.
ESSSecurityLabel(ASN1Object obj)
          Crerates an ESSSecurityLabel from its ASN.1 representation.
ESSSecurityLabel(ObjectID securityPolicyIdentifier)
          Creates an ESSSecurityLabel for the given security policy identifier.
 
Method Summary
static SecurityCategory create(ObjectID type)
          Returns the implementation of the requested SecurityCategory defined through an ASN.1 ObjectID (the SecurityCategory type).
 void decode(ASN1Object obj)
          Decodes the given ASN.1 ESSSecurityLabel object for parsing the internal structure.
 boolean equals(java.lang.Object obj)
          Compares this ESSSecurityLabel to the specified object.
 ObjectID getAttributeType()
          Returns the OID identifying the ESSSecurityLabel attribute type.
 ASN1Object getPrivacyMark()
          Returns the ESSPrivacyMark of this ESSSecurityLabel.
 java.lang.String getPrivacyMarkString()
          Returns the ESSPrivacyMark as String.
 SecurityCategory[] getSecurityCategories()
          Returns the SecurityCategories that may be included in this ESSSecurityLabel.
 int getSecurityClassification()
          Returns the security classification value of this ESSSecurityLabel.
 java.lang.String getSecurityClassificationName()
          Returns the security classification name of this ESSSecurityLabel (if registered).
static java.lang.String getSecurityClassificationName(int securityClassification)
          Returns the name of the given security classification.
 ObjectID getSecurityPolicyIdentifier()
          Returns the security policy identifier of this ESSSecurity.
 int hashCode()
          Returns a hashcode for this object.
static void register(ObjectID type, java.lang.Class cl)
          Registers a class for implementing a particular SecurityCategory value.
 void setPrivacyMark(ASN1Object essPrivacyMark)
          Sets the ESSPrivacyMark of this ESSSecurityLabel.
 void setPrivacyMarkString(java.lang.String essPrivacyMark)
          Sets the ESSPrivacyMark of this ESSSecurityLabel.
 void setSecurityCategories(SecurityCategory[] securityCategories)
          Sets the SecurityCategories of this ESSSecurityLabel.
 void setSecurityClassification(int securityClassification)
          Sets the security classification.
static void setSecurityClassificationNames(java.util.Hashtable names)
          Allows to allocate String names to security classificatoins.
 ASN1Object toASN1Object()
          Returns this ESSSecurityLabel as ASN1Object.
 java.lang.String toString()
          Returns a string representation of this ESSSecurityLabel.
 java.lang.String toString(boolean detailed)
          Returns a string representation of this ESSSecurityLabel.
 
Methods inherited from class iaik.smime.ess.ESSAttributeValue
multipleAllowed
 
Methods inherited from class iaik.asn1.structures.AttributeValue
getName
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

oid

public static final ObjectID oid
The attributeType object identifier of this ESSSecurityLabel attribute. The corresponding OID string is "1.2.840.113549.1.9.16.2.2".

UNMARKED

public static final int UNMARKED
Predefined security classification "unmarked" (0);

See Also:
Constant Field Values

UNCLASSIFIED

public static final int UNCLASSIFIED
Predefined security classification "unclassified" (1);

See Also:
Constant Field Values

RESTRICTED

public static final int RESTRICTED
Predefined security classification "restricted" (2);

See Also:
Constant Field Values

CONFIDENTIAL

public static final int CONFIDENTIAL
Predefined security classification "confidential" (3);

See Also:
Constant Field Values

SECRET

public static final int SECRET
Predefined security classification "secret" (4);

See Also:
Constant Field Values

TOP_SECRET

public static final int TOP_SECRET
Predefined security classification "top-secret" (4);

See Also:
Constant Field Values

UB_INTEGER_OPTIONS

public static final int UB_INTEGER_OPTIONS
Upper bound (64) for security classification value.

See Also:
Constant Field Values

UB_PRIVACY_MARK_LENGTH

public static final int UB_PRIVACY_MARK_LENGTH
Maximum allowed length (128) for PrintableString choice of ESSPrivacyMark.

See Also:
Constant Field Values

UB_SECURITY_CATEGORIES

public static final int UB_SECURITY_CATEGORIES
Maximum allowed number (64) of security categories included.

See Also:
Constant Field Values
Constructor Detail

ESSSecurityLabel

public ESSSecurityLabel()
Empty default constructor. Requred for dynamic object creation. Shall not be used by an application!

ESSSecurityLabel

public ESSSecurityLabel(ObjectID securityPolicyIdentifier)
Creates an ESSSecurityLabel for the given security policy identifier.

A security policy is a set of criteria for the provision of security services. The eSSSecurityLabel security-policy-identifier is used to identify the security policy in force to which the security label relates. It indicates the semantics of the other security label components.

Parameters:
securityPolicyIdentifier - the OID identifying the policy to which the security label relates
Throws:
java.lang.NullPointerException - if securityPolicyIdentifier is null

ESSSecurityLabel

public ESSSecurityLabel(ASN1Object obj)
                 throws CodingException
Crerates an ESSSecurityLabel from its ASN.1 representation.

Parameters:
obj - the ESSSecurityLabel as ASN1Object
Throws:
CodingException - if the encoding is invalid
Method Detail

create

public static SecurityCategory create(ObjectID type)
                               throws java.lang.InstantiationException
Returns the implementation of the requested SecurityCategory defined through an ASN.1 ObjectID (the SecurityCategory type).

Parameters:
type - the OID identifying the SecurityCategory type the SecurityCategory value belongs to
Returns:
the implementation of the SecurityCategory value identified by the given SecurityCategory type
Throws:
java.lang.InstantiationException - if the internal factory could not create an instance of requested type

register

public static void register(ObjectID type,
                            java.lang.Class cl)
                     throws java.lang.IllegalArgumentException
Registers a class for implementing a particular SecurityCategory value.

Parameters:
type - the OID identifying the SecurityCategory type the SecurityCategory value implementing class belongs to
cl - the class which implements the SecurityCategory value in mind
Throws:
java.lang.IllegalArgumentException

setSecurityClassificationNames

public static void setSecurityClassificationNames(java.util.Hashtable names)
Allows to allocate String names to security classificatoins.

Per default no names are registered. When calling method toString for getting a String representation of an ESSSecurityLabel, only the integer value of the security classification component is printed, if set, e.g.: 

 security-policy-identifier: 1.3.6.1.4.1.2706.2.1.7.123.2  
 security-classification: 4
For allocating names to the predefined ESS security classifications you may create and set hashtable with names for classifications "unmarked" (0), "unclassified" (1), "restricted" (2), "confidential" (3), "secret" (4), and "top-secret" (5). The keys for the hashtable have to be Integers representing the classification values: 
 Hashtable names = new Hashtable();
 names.put(new Integer(0), "unmarked");
 names.put(new Integer(1), "unclassified");
 names.put(new Integer(2), "restricted");
 names.put(new Integer(3), "confidential");
 names.put(new Integer(4), "secret");
 names.put(new Integer(5), "top-secret");
 ESSSecurityLabel.setSecurityClassificationNames(names);
When now calling method toString additionally the security classification name is printed: 
 security-policy-identifier: 1.3.6.1.4.1.2706.2.1.7.123.2  
 security-classification: 4 (secret)
You also may call method getSecurityClassificationName for explicitly getting the name of the security classification of an ESSSecurityLabel: 
 ESSSecurityLabel essSecurityLabel = ...;
 int classification = essSecurityLabel.getSecurityClassification();
 System.out.println(ESSSecurityLabel.getSecurityClassificationName(classification));

Parameters:
names - a hashtable mapping classification values to names

getSecurityClassificationName

public static java.lang.String getSecurityClassificationName(int securityClassification)
Returns the name of the given security classification.

If no classification names have been allocated this method returns null anytime. If names have been allocated this method returns the name belonging to the supplied classification value if a name for this classification has been + allocated. When, for instance, having allocated names for the predefined ESS security classifications "unmarked" (0), "unclassified" (1), "restricted" (2), "confidential" (3), "secret" (4), and "top-secret" (5), this method will return "secret" when quering for the name of a classification with value 4: 

 ESSSecurityLabel essSecurityLabel = ...;
 int classification = essSecurityLabel.getSecurityClassification();
 System.out.println(ESSSecurityLabel.getSecurityClassificationName(classification));

Parameters:
securityClassification - the security classification for which to get the name

getSecurityPolicyIdentifier

public ObjectID getSecurityPolicyIdentifier()
Returns the security policy identifier of this ESSSecurity.

A security policy is a set of criteria for the provision of security services. The eSSSecurityLabel security-policy-identifier is used to identify the security policy in force to which the security label relates. It indicates the semantics of the other security label components

Returns:
the OID identifying the policy to which the security label relates

setSecurityClassification

public void setSecurityClassification(int securityClassification)
                               throws java.lang.IllegalArgumentException
Sets the security classification.

If present, a security-classification may have one of a hierarchical list of values. The basic security-classification hierarchy is defined in ESS, but the use of these values is defined by the security-policy in force. Additional values of security-classification, and their position in the hierarchy, may also be defined by a security-policy as a local matter or by bilateral agreement. The basic security-classification hierarchy is, in ascending order: unmarked, unclassified, restricted, confidential, secret, top-secret. However, in any case, the security policy in force (identified by the eSSSecurityLabel security-policy-identifier) defines the SecurityClassification integer values and their meanings.

Parameters:
securityClassification - the security classification
Throws:
java.lang.IllegalArgumentException - if the supplied security classification is invalid (out of range, greater than 256)

getSecurityClassification

public int getSecurityClassification()
Returns the security classification value of this ESSSecurityLabel.

If present, a security-classification may have one of a hierarchical list of values. The basic security-classification hierarchy is defined in ESS, but the use of these values is defined by the security-policy in force. Additional values of security-classification, and their position in the hierarchy, may also be defined by a security-policy as a local matter or by bilateral agreement. The basic security-classification hierarchy is, in ascending order: unmarked, unclassified, restricted, confidential, secret, top-secret. However, in any case, the security policy in force (identified by the eSSSecurityLabel security-policy-identifier) defines the SecurityClassification integer values and their meanings.

Returns:
the security classification value, or -1 if not set

getSecurityClassificationName

public java.lang.String getSecurityClassificationName()
Returns the security classification name of this ESSSecurityLabel (if registered).

Returns:
the security classification name (e.g. "unmarked", or ... "top-secret"), or null if no names are registered

setPrivacyMark

public void setPrivacyMark(ASN1Object essPrivacyMark)
                    throws java.lang.IllegalArgumentException
Sets the ESSPrivacyMark of this ESSSecurityLabel.

If present, the eSSSecurityLabel privacy-mark is not used for access control. The content of the eSSSecurityLabel privacy-mark may be defined by the security policy in force (identified by the eSSSecurityLabel security-policy-identifier) which may define a list of values to be used. Alternately, the value may be determined by the originator of the security-label. The privacy mark is defined as CHOICE of PrintableString or UTF8String: 

 ESSPrivacyMark ::= CHOICE {
   pString      PrintableString (SIZE (1..ub-privacy-mark-length)),
    utf8String   UTF8String (SIZE (1..MAX))
 }
 
 ub-privacy-mark-length INTEGER ::= 128

Parameters:
essPrivacyMark - the privacy mark as PrintableString or UTF8String
Throws:
java.lang.IllegalArgumentException - if the supplied ASN1Object is not a PrintableString or UTF8String, or the string value of a PrintableString choice is has an invalid length (not between 1 ... 128)

setPrivacyMarkString

public void setPrivacyMarkString(java.lang.String essPrivacyMark)
Sets the ESSPrivacyMark of this ESSSecurityLabel.

If present, the eSSSecurityLabel privacy-mark is not used for access control. The content of the eSSSecurityLabel privacy-mark may be defined by the security policy in force (identified by the eSSSecurityLabel security-policy-identifier) which may define a list of values to be used. Alternately, the value may be determined by the originator of the security-label. The privacy mark is defined as CHOICE of PrintableString or UTF8String: 

 ESSPrivacyMark ::= CHOICE {
   pString      PrintableString (SIZE (1..ub-privacy-mark-length)),
    utf8String   UTF8String (SIZE (1..MAX))
 }
 
 ub-privacy-mark-length INTEGER ::= 128
When using this method the PrivacyMark will be encoded as UTF8String.

Parameters:
essPrivacyMark - the privacy mark

getPrivacyMark

public ASN1Object getPrivacyMark()
Returns the ESSPrivacyMark of this ESSSecurityLabel.

If present, the eSSSecurityLabel privacy-mark is not used for access control. The content of the eSSSecurityLabel privacy-mark may be defined by the security policy in force (identified by the eSSSecurityLabel security-policy-identifier) which may define a list of values to be used. Alternately, the value may be determined by the originator of the security-label. The privacy mark is defined as CHOICE of PrintableString or UTF8String: 

 ESSPrivacyMark ::= CHOICE {
   pString      PrintableString (SIZE (1..ub-privacy-mark-length)),
    utf8String   UTF8String (SIZE (1..MAX))
 }
 
 ub-privacy-mark-length INTEGER ::= 128

Returns:
the privacy mark as PrintableString or UTF8String, or null if not included

getPrivacyMarkString

public java.lang.String getPrivacyMarkString()
Returns the ESSPrivacyMark as String.

If present, the eSSSecurityLabel privacy-mark is not used for access control. The content of the eSSSecurityLabel privacy-mark may be defined by the security policy in force (identified by the eSSSecurityLabel security-policy-identifier) which may define a list of values to be used. Alternately, the value may be determined by the originator of the security-label. The privacy mark is defined as CHOICE of PrintableString or UTF8String: 

 ESSPrivacyMark ::= CHOICE {
   pString      PrintableString (SIZE (1..ub-privacy-mark-length)),
    utf8String   UTF8String (SIZE (1..MAX))
 }
 
 ub-privacy-mark-length INTEGER ::= 128

Returns:
the privacy mark as String, or null if not included

setSecurityCategories

public void setSecurityCategories(SecurityCategory[] securityCategories)
                           throws java.lang.IllegalArgumentException
Sets the SecurityCategories of this ESSSecurityLabel.

If present, the eSSSecurityLabel security-categories provide further granularity for the sensitivity of the message. The security policy in force (identified by the eSSSecurityLabel security-policy- identifier) is used to indicate the syntaxes that are allowed to be present in the eSSSecurityLabel security-categories. Alternately, the security-categories and their values may be defined by bilateral agreement.

Parameters:
securityCategories - the security categories to be set
Throws:
java.lang.IllegalArgumentException - if more than 64 (allowed upper bound) security categories should be included

getSecurityCategories

public SecurityCategory[] getSecurityCategories()
Returns the SecurityCategories that may be included in this ESSSecurityLabel.

If present, the eSSSecurityLabel security-categories provide further granularity for the sensitivity of the message. The security policy in force (identified by the eSSSecurityLabel security-policy- identifier) is used to indicate the syntaxes that are allowed to be present in the eSSSecurityLabel security-categories. Alternately, the security-categories and their values may be defined by bilateral agreement.

Returns:
the security categories included in this ESSSecurityLabel, or null if no security categories are included

decode

public void decode(ASN1Object obj)
            throws CodingException
Decodes the given ASN.1 ESSSecurityLabel object for parsing the internal structure.

Parameters:
obj - the ESSSecurityLabel as ASN1Object
Throws:
CodingException - if the encoding is invalid

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException
Returns this ESSSecurityLabel as ASN1Object.

Returns:
this ESSSecurityLabel as ASN1Object
Throws:
CodingException - if an error occurs when building the ASN1Object

getAttributeType

public ObjectID getAttributeType()
Returns the OID identifying the ESSSecurityLabel attribute type.

Specified by:
getAttributeType in class AttributeValue
Returns:
the OID identifying the ESSSecurityLabel attribute type.

equals

public boolean equals(java.lang.Object obj)
Compares this ESSSecurityLabel to the specified object.

Specified by:
equals in class ESSAttributeValue
Parameters:
obj - the object to compare this ESSSecurityLabel against.
Returns:
true, if the given object is equal to this ESSSecurityLabel, false otherwise

hashCode

public int hashCode()
Returns a hashcode for this object.

Overrides:
hashCode in class ESSAttributeValue
Returns:
a hashcode for this object

toString

public java.lang.String toString()
Returns a string representation of this ESSSecurityLabel.

Specified by:
toString in class AttributeValue
Returns:
this ESSSecurityLabel as string

toString

public java.lang.String toString(boolean detailed)
Returns a string representation of this ESSSecurityLabel.

Parameters:
detailed - whether to give some more detailed information
Returns:
this ESSSecurityLabel as string
Overview  Package   Class  Tree  Deprecated  Index  Help 
This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
IAIK-CMS 6.0, (c) 2002 IAIK, (c) 2003, 2023 SIC