iaik.x509.attr.attributes

Class Role

java.lang.Object

iaik.asn1.structures.AttributeValue

iaik.x509.attr.attributes.Role

All Implemented Interfaces:

ASN1Type

public class Role
extends AttributeValue

The Role attribute.

The X.509 Attribute Certificate profile (RFC 5755) specifies the Role attribute to be included as attribute in an AttributeCertificate or in the SubjectDirectoryAttributes extension of a public key X509Certificate for assigning some particular role to the holder of the attribute certificate or the subject of the public key certificate, respectively.

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

 id-at OBJECT IDENTIFIER ::= { joint-iso-ccitt(2) ds(5) 4 }
 
 id-at-role OBJECT IDENTIFIER ::= { id-at 72 }
 

which corresponds to the OID string "2.5.4.72".

A certificate that contains a Role attribute is called role assignment certificate because it assigns some particular role to the holder/subject of the certificate. A role may give the corresponding entity some kind of privilege to, for instance, access some kind of resource. However, the privilege verfier must know about the exact meaning of the asserted privilege. The binding between role and privilege context may be done by special configuration settings or by using a so-called role specification certificate. The role specification certificate again is an attribute certificate which assigns some specific privilege to the role contained in the corresponding role assignment certificate. The link between the role assignement certificate and the corresponding role specification certificate is done by the roleName field of the Role attribute of the role assignment certificate (this roleName field shall also be contained in the holder field of the role specification certificate; see RFC 5755, ITU-T X.509):

 RoleSyntax ::= SEQUENCE {
   roleAuthority   [0] GeneralNames OPTIONAL,
   roleName        [1] GeneralName
 }
 

The roleAuthority field, if present, may specify the issuing authority of the corresponding role specification certificate (in this case one of the names of the roleAuthority field shall be present in the issuer field of the role specification certificate). If there is no role specification certificate in use, the roleAuthority field may, for instance, distinguish between same-named roles that are used in different organisations/departments (see RFC 5755). For instance, to differ the "CEO" role of the IAIK JavaSecurity group from the "CEO" role of the IAIK "VLSI" group, the first Role attribute may have a "IAIK JavaSecurity" roleAuthority field and the other Role attribute may have a "IAIK VLSI" roleAuthority field, however, both specifying "CEO" as roleName.

When creating a Role attribute the role name has to be supplied as GeneralName, e.g.:

 GeneralName roleName = new GeneralName(GeneralName.uniformResourceIdentifier, "urn:sysadmin");
 Role role = new Role(roleName);
 

If required, use method setRoleAuthority for specifying the role authotity (which may refer the issuing authority of the role specification certificate that assignes a privilege to the roleName of this Role attribute), e.g.:

 GeneralNames roleSpecCertIssuer = ...;
 role.setRoleAuthority(roleSpecCertIssuer);
 

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

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

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

 // the AttributeCertificate:
 AttributeCertificate ac = new AttributeCertificate(encodedAc);
 ...
 // verify signature, check validity,...
 ...
 // query for Role attribute:
 Attribute roleAttribute = ac.getAttribute(Role.oid);
 if (roleAttribute != null) {
   // in our example we know that we have a single-valued Role attribute only
   Role role = (Role)roleAttribute.getAttributeValue();
   // get role name
   GeneralName roleName = role.getRoleName();
   GeneralNames roleAuthority = role.getRoleAuthority();
   if (roleAuthority != null) {
     ...
   }
 }  
 

If a role specification certificate is used for assigning a privilege to the roleName of this Role attribute, method roleSpecifiedBy maybe used to check if a given attribute certificate is a role specification certificate for this role:

 AttributeCertificate roleSpecificationCert = ...;
 if (role.roleSpecifiedBy(roleSpecificationCert)) {
   ...
 }
 

See Also:

AttributeCertificate, Attribute, GeneralName, GeneralNames

Field Summary

Fields

Modifier and Type	Field and Description
static ObjectID	oid The attributeType object identifier of the Role attribute.

Constructor Summary

Constructors

Constructor and Description
Role() Empty default constructor.
Role(ASN1Object obj) Creates a Role attribute from its ASN.1 representation.
Role(GeneralName roleName) Creates a Role attribute with the given roleName.

Method Summary

Methods

Modifier and Type	Method and Description
void	decode(ASN1Object obj) Decodes a Role attribute from its ASN.1 representation.
ObjectID	getAttributeType() Returns the OID (2.5.4.72) identifying the Role attribute type.
GeneralNames	getRoleAuthority() Gets the role authority of this Role attribute, if set.
GeneralName	getRoleName() Returns the role name.
boolean	roleSpecifiedBy(AttributeCertificate roleSpecificationCertificate) Checks if the given attribute certificate is a role specification certificate for the attribute certificate containing this Role attribute.
GeneralNames	setRoleAuthority(AttributeCertificate roleSpecificationCertificate) Sets the role authority field of this Role attribute to the issuer GeneralNames of the given role specification certificate.
void	setRoleAuthority(GeneralNames roleAuthority) Sets the role authority field of this Role attribute.
ASN1Object	toASN1Object() Returns this Role attribute as ASN1Object.
java.lang.String	toString() Returns a string representation of this Role attribute.

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 Role attribute. The corresponding OID string is "2.5.4.72".

Constructor Detail

Role

public Role()

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

Role

public Role(GeneralName roleName)

Creates a Role attribute with the given roleName.

According to the X.509 Attribute Certificate profile ( RFC 5755) of the IETF PKIX working group the roleName must be a GeneralName of type uniformResourceIdentifier. However, this may not be required by other recommendations (e.g. ITU-T X.509). For that reason any GeneralName type name is accepted by this constructor.

Use method setRoleAuthority for specifyng a role authority for this Role attribute, if required.

Parameters:

roleName - the name of the role which shall be assigned to the holder of the corresponding attribute certificate (or to the subject of a public key certificate that contains an SubjectDirectoryAttributes extension with this Role attribute)

Throws:

java.lang.NullPointerException - if null is specified as roleName

Role

public Role(ASN1Object obj)
     throws CodingException

Creates a Role attribute from its ASN.1 representation.

Parameters:

obj - the Role as ASN1Object

Throws:

CodingException - if an error occurs when parsing the ASN1Object

Method Detail

getRoleName

public GeneralName getRoleName()

Returns the role name.

Returns:

the role name

getRoleAuthority

public GeneralNames getRoleAuthority()

Gets the role authority of this Role attribute, if set.
The roleAuthority field, if present, may specify the issuing authority of the corresponding role specification certificate (in this case one of the names of the roleAuthority field shall be present in the issuer field of the role specification certificate). If there is no role specification certificate in use, the roleAuthority field may, for instance, distinguish between same-named roles that are used in different organisations/departments (see RFC 5755). For instance, to differ the "CEO" role of the IAIK JavaSecurity group from the "CEO" role of the IAIK "VLSI" group, the first Role attribute may have a "IAIK JavaSecurity" roleAuthority field and the other Role attribute may have a "IAIK VLSI" roleAuthority field, however, both specifying "CEO" as roleName.

Returns:

the role authority, or null if no role authority is associated with this Role attribute

setRoleAuthority

public void setRoleAuthority(GeneralNames roleAuthority)

Sets the role authority field of this Role attribute.
The roleAuthority field may specify the issuing authority of the corresponding role specification certificate (in this case one of the names of the roleAuthority field shall be present in the issuer field of the role specification certificate). If there is no role specification certificate in use, the roleAuthority field may, for instance, distinguish between same-named roles that are used in different organisations/departments (see RFC 5755). For instance, to differ the "CEO" role of the IAIK JavaSecurity group from the "CEO" role of the IAIK "VLSI" group, the first Role attribute may have a "IAIK JavaSecurity" roleAuthority field and the other Role attribute may have a "IAIK VLSI" roleAuthority field, however, both specifying "CEO" as roleName.

Parameters:

roleAuthority - the role authority

setRoleAuthority

public GeneralNames setRoleAuthority(AttributeCertificate roleSpecificationCertificate)

Sets the role authority field of this Role attribute to the issuer GeneralNames of the given role specification certificate.
The roleAuthority field may specify the issuing authority of the corresponding role specification certificate (in this case one of the names of the roleAuthority field shall be present in the issuer field of the role specification certificate).
This method tries to get a GeneralNames from the issuer field of the given role specification certificate in the following way (in that order):

1. If the issuer field is a V1Form, the roleAuthority field is set to the V1Form GeneralNames
2. If the issuer field is a V2Form and contains the issuerName component, the roleAuthority field is set to the issuerName GeneralNames
3. If the issuer field is a V2Form and does not contain the issuerName component, but baseCertificateID component, the roleAuthority field is set to the issuer GeneralNames of the baseCertificateID IssuerSerial

Parameters:

roleSpecificationCertificate - the role specification certificate from which to create the roleAuthority field

Returns:

the newly created roleAuthority field, or null if the role authority field could not be created

roleSpecifiedBy

public boolean roleSpecifiedBy(AttributeCertificate roleSpecificationCertificate)

Checks if the given attribute certificate is a role specification certificate for the attribute certificate containing this Role attribute.

This method first checks if the roleName of this Role attribute is contained in the holder field of the given role specification certificate. If this Role attribute contains the roleAuthority field, it is checked of at least one if its names is included in the issuer field of the given role specification certificate.

Parameters:

roleSpecificationCertificate - the attribute certificate to be checked of being a role specification certificate for the attribute certificate containing this Role attribute

Returns:

true if the given attribute certificate is a role specification certificate for this Role attribute, false if not

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes a Role attribute from its ASN.1 representation.

The ASN.1 syntax for the Role attribute is as follows:

 RoleSyntax ::= SEQUENCE {
   roleAuthority   [0] GeneralNames OPTIONAL,
   roleName        [1] GeneralName
 }
 

Parameters:

obj - the Role attribute as ASN1Object

Throws:

CodingException - if an parsing error occurs or the ASN.1 representation of the Role attribute is not well structured (e.g. does contain invalid components)

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns this Role attribute as ASN1Object.

The ASN.1 syntax for the Role attribute is as follows:

 RoleSyntax ::= SEQUENCE {
   roleAuthority   [0] GeneralNames OPTIONAL,
   roleName        [1] GeneralName
 }
 

Returns:

this Role attribute as ASN1Object

Throws:

CodingException - if the ASN1Object cannot be built

getAttributeType

public ObjectID getAttributeType()

Returns the OID (2.5.4.72) identifying the Role attribute type.

Specified by:

getAttributeType in class AttributeValue

Returns:

the OID identifying the Role attribute type.

toString

public java.lang.String toString()

Returns a string representation of this Role attribute.

Specified by:

toString in class AttributeValue

Returns:

this Role attribute as string