TargetInformation (6.0 API Documentation)

java.lang.Object
- iaik.x509.V3Extension
- - iaik.x509.attr.extensions.TargetInformation

```
public class TargetInformation
extends V3Extension
```
This class implements the TargetInformation attribute certificate extension.
When included in an attribute certificate, the TargetInformation extension MUST be marked as being critical.
Each extension is associated with a specific certificateExtension object identifier. The OID for the TargetInformation
```
 certificateExtension  OBJECT IDENTIFIER ::=
                            {joint-iso-ccitt(2) ds(5) 29}
 id-ce                 OBJECT IDENTIFIER ::=  certificateExtension
 
 id-ce-targetInformation OBJECT IDENTIFIER ::= { id-ce 55 }
 
```
which corresponds to the OID string "2.5.29.55".
The X.509 Attribute Certificate profile presented in RFC 5755 specifies the TargetInformation extension to be used for targeting an attribute certificate to be accepted only by a specified number of servers/services. If no TargetInformation extension is present in an attribute certificate, the certificate may be accepted by any service/server.
The TargetInformation extension is defined as an ASN.1 SEQUENCE of Targets objects. Each Targets object can hold any number of Target elements of type TargetName, TargetGroup or TargetCert, however, the TargetCert choice must not be used (see RFC 5755):
```
 TargetInformation ::= SEQUENCE OF Targets
 
 Targets ::= SEQUENCE OF Target

 Target  ::= CHOICE {
   targetName          [0] GeneralName,
   targetGroup         [1] GeneralName,
   targetCert          [2] TargetCert
 }

 TargetCert  ::= SEQUENCE {
   targetCertificate    IssuerSerial,
   targetName           GeneralName OPTIONAL,
   certDigestInfo       ObjectDigestInfo OPTIONAL
 }
 
```
Although TargetInformation is defined as SEQUENCE of Targets RFC 5755 requires AC issuers to only issue attribute certificates with TargetInformation extensions that do contain only one Targets object. If a TargetInformation contains more than one Targets object, all included Target elements must be treated as belonging to one single Targets object.
Based on the presence of the TargetInformation extension a server/service may decide whether to accept the attribute certificate or not. If no TargetInformation is present the attribute certificate is not targeted and may be accepted by any server/service. If a TargetInformation is present the included Target elements have to be checked to see if the current server "matches" the target condition: the server can accept the attribute certificate if the server is one of the included targetName elements, or if it is a member of one of the included targetGroup elements. How group membership may be verified, may depend on application specific settings. For instance, if a targetGroup specifies a DNS domain the AC verifier will have to know the DNS domain to which it belongs. Or, for instance, if a targetGroup specified "PRINTERS" the AC verifier must know if it is a, e.g., printer or print server (see RFC 5755).
After having created a TargetInformation extension object and having added any Target elements as required, the TargetInformation object has to be set as an extension for the AttributeCertificate object in mind, e.g.:
```
 // create TargetInformation
 TargetInformation targetInformation = new TargetInformation();
 // add a TargetName element
 GeneralName name = new GeneralName(GeneralName.uniformResourceIdentifier, "jce.iaik.tugraz.at");
 TargetName targetName = new TargetName(name);
 targetInformation.addTargetElement(targetName);
 ...
 // add any further Target element if required
 ...
 // create attribute certificate
 AttributeCertificate ac = new AttributeCertificate();
 ...
 // set holder, issuer, validity,...
 ...
 // add TargetInformation extension
 ac.addExtension(targetInformation);
 // sign and encode certificate
 ac.sign(...);
 byte[] encodedAc = ac.getEncoded();
 
```
On the receiving end use method getExtension of the AttributeCertificate to get a TargetInformation extension -- if included -- from an Attribute Certificate:
```
 // the AttributeCertificate:
 AttributeCertificate ac = new AttributeCertificate(encodedAc);
 ...
 // verify signature, check validity,...
 ...
 // query for TargetInformation extension:
 TargetInformation targetInformation = (TargetInformation)ac.getExtension(TargetInformation.oid);
 if (TargetInformation != null) {
   GeneralName serverName = new GeneralName(GeneralName.uniformResourceIdentifier, "jce.iaik.tugraz.at");
   if (targetInformation.isTargetFor(serverName)) {
     // accept attribute certificate 
   }
 } else {
   // no TargetInformation extension included; accept the certificate
 }  
 
```
The code sample above uses method isTargetFor to check if the AC verifying server/recipient is a valid target for the attribute certificate. The targeting check is controlled by the TargetChecker. For each single Target element included in this TargetInformation extension, the default TargetChecker implementation performs the following checks (in this order):
1. If the server is given as Target object and is equal to the AC Target element, the check returns true.
2. If the AC Target element represents a TargetName or TargetGroup and the server is given as GeneralName, the check returns true if the GeneralName of the AC Target is equal to the server GeneralName.
3. If 1. and 2. have returned false and the AC Target is a TargetGroup containing a GeneralName of type dNSName the server maybe given as TargetGroup or GeneralName. In this case the server GeneralName is checked of being of type dNSName, uniformResourceIdentifier or rfc822Name. If the server GeneralName is of any of these three types the check returns true if the server name is in the domain specified by the dNSName of the AC TargetGroup (i.e. it is checked if the server name ends with the dNSName specified by the AC TargetGroup). If, for instance, the AC TargetGroup specifies a dNSName like "iaik.at" and the server name is "http://jce.iaik.at" the server is accepted as being a member of the AC TargetGroup.
4. The check returns false, if any of the steps above has not come to a positive result.
As seen from above the server can be given as Target object or -- if the TargetInformation contains TargetName or TargetGroup elements -- as GeneralName. In any other case -- if the supplied server object is not given as Target or GeneralName -- a TargetException is thrown indicating that the server object cannot be handled by the TargetChecker. An application may plug-in its own TargetChecker implementation for enforcing a more sophisticated target checking policy which may be tailored to application specific requirements that cannot be considered by a general default implementation.
Version:

File Revision 20

See Also:
GeneralName, V3Extension, AttributeCertificate, Target, Targets, TargetName, TargetGroup, TargetCert

Field Summary

Fields
Modifier and Type Field and Description

static ObjectID oid
The object identifier of this TargetInformation extension.
- Fields inherited from class iaik.x509.V3Extension
  critical

Fields
Modifier and Type	Field and Description
`static ObjectID`	`oid` The object identifier of this TargetInformation extension.

Constructor Summary

Constructors
Constructor and Description

TargetInformation()
Default constructor.

Constructors
Constructor and Description
`TargetInformation()` Default constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`addTargetElement(Target target)` Adds the given Target.
`boolean`	`containsTargetElement(Target target)` Checks if the given Target element is contained in this TargetInformation extension.
`ObjectID`	`getObjectID()` Returns the object ID of this `TargetInformation` extension
`Target[]`	`getTargetElements()` Gets all Target elements included in the Targets objects of this TargetInformation extension.
`Targets[]`	`getTargets()` Gets all Targets objects included in this TargetInformation extension.
`int`	`hashCode()` Returns a hashcode for this identity.
`void`	`init(ASN1Object obj)` Inits this `TargetInformation` implementation with an ASN1object representing the value of this extension.
`boolean`	`isTargetFor(java.lang.Object server)` Checks if the given server/service is a valid target for the attribute certificate containing this TargetInformation extension.
`int`	`numberOfTargetElements()` Returns the total number of Target elements that are contained in this TargetInformation.
`int`	`numberOfTargets()` Returns the number of Targets objects that are contained in this TargetInformation.
`void`	`removeAllTargets()` Removes all targets from this TargetInformation.
`boolean`	`removeTargetElement(Target target)` Removes the given Target element from this TargetInformation.
`boolean`	`removeTargets(Targets targets)` Removes the given Targets object from this TargetInformation.
`void`	`setTargetElements(Target[] targets)` Sets all Target elements.
`void`	`setTargets(Targets[] targets)` Sets all Targets objects.
`ASN1Object`	`toASN1Object()` Returns an ASN1Object representing the value of this `TargetInformation` extension object.
`java.lang.String`	`toString()` Returns a string that represents the contents of this `TargetInformation` extension.
`java.lang.String`	`toString(boolean detailed)` Returns a string that represents the contents of this `TargetInformation` extension.

Methods inherited from class iaik.x509.V3Extension
getName, isCritical, setCritical

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - oid
```
public static final ObjectID oid
```
    The object identifier of this TargetInformation extension. The corresponding OID string is "2.5.29.55".
- Constructor Detail
  - TargetInformation
```
public TargetInformation()
```
    Default constructor. Creates an empty TargetInformation object. Use method addTargetElement for adding Target elements as required.
- Method Detail
  - getObjectID
```
public ObjectID getObjectID()
```
    Returns the object ID of this TargetInformation extension
    
    Specified by:
    
    getObjectID in class V3Extension
    
    Returns:
    the object ID
  - init
```
public void init(ASN1Object obj)
          throws X509ExtensionException
```
    Inits this TargetInformation implementation with an ASN1object representing the value of this extension.
    The given ASN1Object represents the SEQUENCE of Targets value of the TargetInformation extension:
```
 TargetInformation ::= SEQUENCE OF Targets
 
```
    When parsing the ASN.1 representation of an attribute certificate this method is used for properly initializing an included TargetInformation extension. This method initializes the extension only with its value, but not with its critical specification. For that reason, this method shall not be explicitly called by an application.
    Specified by:
    
    init in class V3Extension
    
    Parameters:
    obj - the TargetInformation as ASN1Object
    
    Throws:
    
    X509ExtensionException - If the extension value is not an ASN.1 SEQUENCE object or some error occurs when parsing the included Targets objects
  - toASN1Object
```
public ASN1Object toASN1Object()
                        throws X509ExtensionException
```
    Returns an ASN1Object representing the value of this TargetInformation extension object.
    The returned ASN1Object is an ASN.1 SEQUENCE representing the value of this TargetInformation extension:
```
 TargetInformation ::= SEQUENCE OF Targets
 
```
    Specified by:
    
    toASN1Object in class V3Extension
    
    Returns:
    the value of this TargetInformation as ASN1Object
    
    Throws:
    
    X509ExtensionException - if the extension could not be created
  - hashCode
```
public int hashCode()
```
    Returns a hashcode for this identity.
    
    Specified by:
    
    hashCode in class V3Extension
    
    Returns:
    a hash code for this identity
  - addTargetElement
```
public boolean addTargetElement(Target target)
```
    Adds the given Target.
    The given Target element is added to the first (and maybe only) Targets object in the list: Although the TargetInformation value is defined as SEQUENCE OF Targets, the X.509 Attribute Certificate profile (RFC 5755) requires that a TargetInformation has to contain only one Targets object. If more than one Targets object are present, all Target elements that are included in the serveral Targets objects have to be treated as belonging to one single Targets object only.
    
    Parameters:
    target - the Target element to be added
    
    Returns:
    true if the Target element has been added false if it has not been added because it is already included
  - setTargetElements
```
public void setTargetElements(Target[] targets)
```
    Sets all Target elements.
    Any already included Targets objects are removed and one new single Targets object is created. All the given Target elements are added to the one and only Targets object just created: Although the TargetInformation value is defined as SEQUENCE OF Targets, the X.509 Attribute Certificate profile (RFC 5755) requires that a TargetInformation has to contain only one Targets object.
    
    Parameters:
    targets - the Target elements to be set
  - setTargets
```
public void setTargets(Targets[] targets)
```
    Sets all Targets objects.
    Note that although the TargetInformation value is defined as SEQUENCE OF Targets, the X.509 Attribute Certificate profile (RFC 5755) requires that a TargetInformation has to contain only one Targets object. If more than one Targets object is present, all Target elements that are included in the serveral Targets objects have to be treated as belonging to one single Targets object. Nevertheless this method provides the possibility to set more than only one Targets object. Thus an application may not be fully RFC 5755 compliant when calling this method with more than only one Targets object.
    
    Parameters:
    targets - the Targets to be set (the supplied array may contain only one Targets object as requested by the X.509 attribute profile).
  - removeTargets
```
public boolean removeTargets(Targets targets)
```
    Removes the given Targets object from this TargetInformation.
    
    Parameters:
    targets - the Targets object to be removed
    
    Returns:
    true if the Targets object has been removed, false if no such Targets object was present
  - removeTargetElement
```
public boolean removeTargetElement(Target target)
```
    Removes the given Target element from this TargetInformation.
    
    Parameters:
    target - the Target element to be removed
    
    Returns:
    true if the Target element has been removed, false if no such Target was present
  - removeAllTargets
```
public void removeAllTargets()
```
    Removes all targets from this TargetInformation.
  - getTargets
```
public Targets[] getTargets()
```
    Gets all Targets objects included in this TargetInformation extension.
    Note that although the TargetInformation value is defined as SEQUENCE OF Targets, the X.509 Attribute Certificate profile (RFC 5755) requires that a TargetInformation has to contain only one Targets object. Nevertheless a TargetInformation may contain more than only one Targets objects. In this case all Targets objects are returned by this method, and all the Target elements that are included in the serveral Targets objects shall be treated as belonging to one single Targets object only.
    
    Returns:
    an array of all included Targets objects; the array may be empty
  - getTargetElements
```
public Target[] getTargetElements()
```
    Gets all Target elements included in the Targets objects of this TargetInformation extension.
    This method steps through all included Targets objects and builds an array of all Target elements that are contained in the several Targets objects. If more than only one Targets object is included in this TargetInformation extension, all the Target elements returned by this method may be treated as belonging to one and only Targets object as required by the X.509 Attribute Certificate profile RFC 5755).
    
    Returns:
    an array of all included Target elements that are found in the Targets objects of this TargteInformation; the array may be empty
  - numberOfTargets
```
public int numberOfTargets()
```
    Returns the number of Targets objects that are contained in this TargetInformation. According to the X.509 Attribute Certificate profile RFC 5755) only one Targets object should be included.
    
    Returns:
    the number of included Targets objects
  - numberOfTargetElements
```
public int numberOfTargetElements()
```
    Returns the total number of Target elements that are contained in this TargetInformation.
    
    Returns:
    the number of included Target elements
  - isTargetFor
```
public boolean isTargetFor(java.lang.Object server)
                    throws TargetException
```
    Checks if the given server/service is a valid target for the attribute certificate containing this TargetInformation extension.
    This method steps through all Target elements included in this TargetInformation extension. It returns true if it detects a Target element that denotes the given server/service as a valid target. It returns also true if this TargetInformation does not contain any Target elements at all (in which case the corresponding attribute certificate is not specially targeted and can be accepted by any server). It returns false if none of the included Target elements denotes the server/service as valid target. It throws a TargetException if it cannot find a Target element that accepts the server/service as valid Target but some of the Target elements cannot handle the server/service and thus cannot provide a reliable information.
    The targeting check is controlled by the TargetChecker. For each single Target element included in this TargetInformation extension, the default TargetChecker implementation performs the following checks (in this order):
    1. If the server is given as Target object and is equal to the AC Target element, the check returns true.
    2. If the AC Target element represents a TargetName or TargetGroup and the server is given as GeneralName, the check returns true if the GeneralName of the AC Target is equal to the server GeneralName.
    3. If 1. and 2. have returned false and the AC Target is a TargetGroup containing a GeneralName of type dNSName the server maybe given as TargetGroup or GeneralName. In this case the server GeneralName is checked of being of type dNSName, uniformResourceIdentifier or rfc822Name. If the server GeneralName is of any of these three types the check returns true if the server name is in the domain specified by the dNSName of the AC TargetGroup (i.e. it is checked if the server name ends with the dNSName specified by the AC TargetGroup). If, for instance, the AC TargetGroup specifies a dNSName like "iaik.at" and the server name is "http://jce.iaik.at" the server is accepted as being a member of the AC TargetGroup.
    4. The check returns false, if any of the steps above has not come to a positive result.
    As seen from above the server can be given as Target object or -- if the TargetInformation contains TargetName or TargetGroup elements -- as GeneralName. In any other case -- if the supplied server object is not given as Target or GeneralName -- a TargetException is thrown indicating that the server object cannot be handled by the TargetChecker. An application may plug-in its own TargetChecker implementation for enforcing a more sophisticated target checking policy which may be tailored to application specific requirements that cannot be considered by a general default implementation.
```
 MyTargetChecker myTargetChecker = ...;
 Target.setTargetChecker(myTargetChecker);
 
```
    Parameters:
    server - the server/service to be checked for being a target of the AC
    
    Returns:
    true if this TargetInformation extension does not contain any Target element or if it contains a Target element that denotes the given server/service as a valid target; false if none of the included Target elements denotes the server/service as valid target
    
    Throws:
    
    TargetException - if none of the Target elements in this TargetInformation extension accepts the server/service as valid target, but some of the Target elements cannot handle the server/service and thus cannot provide a reliable information. For instance, checking if a server/service belongs to some specific TargetGroup cannot be done in a general way because membership of a target to a TargetGroup only can be handled in application specfic manner, e.g. (see RFC 5755): a TargetGroup may specify "PRINTERS," and the AC verifier knows if it is a printer or print server or not). In such cases the isTargetFor check must be done in a different, application specific way by implementing and plugging-in a special TargetChecker.
  - containsTargetElement
```
public boolean containsTargetElement(Target target)
```
    Checks if the given Target element is contained in this TargetInformation extension.
    
    Parameters:
    target - the Target element to be checked if included
    
    Returns:
    true if the given Target is included, false if it is not included
  - toString
```
public java.lang.String toString()
```
    Returns a string that represents the contents of this TargetInformation extension.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    the string representation
  - toString
```
public java.lang.String toString(boolean detailed)
```
    Returns a string that represents the contents of this TargetInformation extension.
    
    Parameters:
    detailed - whether to give some detailed information about the included Targets objects
    
    Returns:
    the string representation

Class TargetInformation

Field Summary

Fields inherited from class iaik.x509.V3Extension

Constructor Summary

Method Summary

Methods inherited from class iaik.x509.V3Extension

Methods inherited from class java.lang.Object

Field Detail

oid

Constructor Detail

TargetInformation

Method Detail

getObjectID

init

toASN1Object

hashCode

addTargetElement

setTargetElements

setTargets

removeTargets

removeTargetElement

removeAllTargets

getTargets

getTargetElements

numberOfTargets

numberOfTargetElements

isTargetFor

containsTargetElement

toString

toString