iaik.x509.attr

Class Targets

java.lang.Object

iaik.x509.attr.Targets

All Implemented Interfaces:

ASN1Type

public class Targets
extends java.lang.Object
implements ASN1Type

This class implements the Targets type specified by the X.509 Attribute Certificate profile (RFC 5755) to be used within TargetInformation or ProxyInfo attribute certificate extensions.
Both, TargetInformation and ProxyInfo extensions are defined as an ASN.1 SEQUENCE OF Targets, where each Targets object itself can hold any number of Target (TargetName, TargetGroup or TargetCert) elements:

 TargetInformation ::= SEQUENCE OF Targets
 
 ProxyInfo ::= SEQUENCE OF Targets
 
 Targets ::= SEQUENCE OF Target

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

Within a TargetInformation extension the SEQUENCE of Targets only shall contain one single Targets object. A Targets object may contain any number of Target elements to specify some servers/services for which the attribute certificate that contains the TargetInformation can be used. The AC verifier that validates an attribute certificate on behalf of some specific server must check if the AC contains a TargetInformation extension. If yes, it only shall accept the AC if the current server/service is targeted by any of the Target elements that are included in the Targets object of the TargetInformation extension.
A Targets object, when included in a ProxyInfo extension, specifies some servers/services which represent valid senders (proxies) or recipients of the attribute certificate that contains the ProxyInfo extension.

After having created a Targets object use method addTarget to add any Target elements as required, e.g. (note that RFC 5755 recommends that the TargetCert choice MUST NOT be used):

 // create a new Targets object
 Targets targets = new Targets();
 // create and add a TargetName 
 GeneralName name = new GeneralName(GeneralName.uniformResourceIdentifier, "www.tugraz.at");
 TargetName targetName = new TargetName(name);
 targets.addTarget(targetName);
 // create and add a TargetGroup
 GeneralName name = new GeneralName(GeneralName.dNSName, "iaik.at");
 TargetGroup targetGroup = new TargetGroup(name);
 targets.addTarget(targetGroup);
 

The Targets object then typically may be added to a TargetInformation or ProxyInfo extension. Remember that according RFC 5755 a TargetInformation extension shall contain one Targets object only, e.g.:

 TargetInformation targetInformation = new TargetInformation();
 targetInformation.setTargets(new Targets[] { targets });
 

or

 ProxyInfo proxyInfo = new ProxyInfo();
 proxyInfo.addTargets(targets);
 

An AC verifier, when receiving an attribute certificate that contains a TargetInformation or ProxyInfo extension, may query for the included Targets object(s), e.g.:

 ...
 TargetInformation targetInformation = (TargetInformation)attributeCertificate.getExtension(TargetInformation.oid);
 if (targetInformation != null) {
   Targets[] targetObjects = targetInformation.getTargets();
 }
 

However, typically the AC verifier only will call the TargetInformation isTargetFor or ProxyInfo checkProxy methods to check if the received attribute certificate can be accepted by the current server, e.g.:

 GeneralName serverName = new GeneralName(GeneralName.uniformResourceIdentifier, "http://jce.iaik.at");
 if (targetInformation.isTargetFor(serverName) {
   // ok; accept ac
 } else {
   // reject ac
 }
 

The targeting check is controlled by the TargetChecker. For each single Target element included in this Targets object, 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 reference Target element, the check returns true.
2. If the reference Target element represents a TargetName or TargetGroup and the server is given as GeneralName, the check returns true if the GeneralName of the reference Target is equal to the server GeneralName.
3. If 1. and 2. have returned false and the reference 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 reference TargetGroup (i.e. it is checked if the server name ends with the dNSName specified by the reference TargetGroup). If, for instance, the reference 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 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 Targets object 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.

See Also:

GeneralName, V3Extension, AttributeCertificate, Target, TargetName, TargetGroup, TargetCert, TargetInformation, ProxyInfo

Constructor Summary

Constructors

Constructor and Description
Targets() Default constructor.
Targets(ASN1Object obj) Creates a Targets object from its ASN.1 representation (SEQUENCE OF Target).

Method Summary

Modifier and Type	Method and Description
boolean	addTarget(Target target) Adds the given Target (if it is not already included).
boolean	containsTarget(Target target) Checks if the given Target element is contained in the list of Target elements maintained by this Targets object.
void	decode(ASN1Object obj) Decodes a Targets object from its ASN.1 representation (SEQUENCE OF Target).
boolean	equals(java.lang.Object obj) Compares this Targets with the specified object.
Target[]	getTargets() Returns all Target elements included in this Targets list.
int	hashCode() Returns a hashcode for this Targets
boolean	isTargetFor(java.lang.Object server) Checks if the given server/service is a valid target for the attribute certificate containing an extension with this Targets.
void	removeAllTargets() Removes all target elements from the list.
boolean	removeTarget(Target target) Removes the given Target element from the Target list.
void	setTargets(Target[] targets) Sets all target elements.
int	size() Returns the number of Target elements that are contained in this Targets list.
ASN1Object	toASN1Object() Returns this Targets as ASN1Object (SEQUENCE of Target).
java.lang.String	toString() Returns a string giving some information about this Targets object.
java.lang.String	toString(boolean detailed) Returns a string giving some information about this Targets object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Targets

public Targets()

Default constructor. Creates an empty Targets object. Use method addTarget to add Target elements as required.

Targets

public Targets(ASN1Object obj)
        throws CodingException

Creates a Targets object from its ASN.1 representation (SEQUENCE OF Target).

Parameters:

obj - the ASN.1 representation as SEQUENCE of Target

Throws:

CodingException - if a parsing error occurs

Method Detail

addTarget

public boolean addTarget(Target target)

Adds the given Target (if it is not already included).

Parameters:

target - the Target to be added

Returns:

true if the Target has been added, false if it has not been added because it is already included

setTargets

public void setTargets(Target[] targets)

Sets all target elements.

Parameters:

targets - the Target elements to be set.

removeTarget

public boolean removeTarget(Target target)

Removes the given Target element from the Target list.

Parameters:

target - the Target element to be removed

Returns:

true if the target has been removed, false if no such target was present

removeAllTargets

public void removeAllTargets()

Removes all target elements from the list.

getTargets

public Target[] getTargets()

Returns all Target elements included in this Targets list.

Returns:

an array of all included Target elements; the array may be empty

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes a Targets object from its ASN.1 representation (SEQUENCE OF Target).

Specified by:

decode in interface ASN1Type

Parameters:

obj - the ASN.1 representation as SEQUENCE of Target

Throws:

CodingException - if a parsing error occurs

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns this Targets as ASN1Object (SEQUENCE of Target).

Specified by:

toASN1Object in interface ASN1Type

Returns:

this Targets as ASN1Object (SEQUENCE of Target)

Throws:

CodingException - if an error occurs when creating the ASN.1 representation

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 an extension with this Targets.

This method steps through all Target elements included in this Targets list. 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 Targets list 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 Targets object, 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 reference Target element, the check returns true.
2. If the reference Target object represents a TargetName or TargetGroup and the server is given as GeneralName, the check returns true if the GeneralName of the reference Target is equal to the server GeneralName.
3. If 1. and 2. have returned false and the reference 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 reference TargetGroup (i.e. it is checked if the server name ends with the dNSName specified by the reference TargetGroup). If, for instance, the reference 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 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 Targets object 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 Targets list does not contain any Target element or if it contains a 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 element in this Targets list 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.

containsTarget

public boolean containsTarget(Target target)

Checks if the given Target element is contained in the list of Target elements maintained by this Targets object.

Parameters:

target - the Target to be checked if included

Returns:

true if the given Target is included, false if it is not included

equals

public boolean equals(java.lang.Object obj)

Compares this Targets with the specified object.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to which to compare this Targets

Returns:

true, if the given object is equal to this Targets; false otherwise

hashCode

public int hashCode()

Returns a hashcode for this Targets

Overrides:

hashCode in class java.lang.Object

Returns:

a hashcode for this Targets

size

public int size()

Returns the number of Target elements that are contained in this Targets list.

Returns:

the number of included Target elements

toString

public java.lang.String toString()

Returns a string giving some information about this Targets object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation

toString

public java.lang.String toString(boolean detailed)

Returns a string giving some information about this Targets object.

Parameters:

detailed - whether to give detailed inoformation about the included Target elements

Returns:

the string representation