com.rsa.certj.cert.extensions

Class GeneralSubtrees

java.lang.Object
  |
  +--com.rsa.certj.cert.extensions.GeneralSubtrees

All Implemented Interfaces:

Cloneable, Serializable

public class GeneralSubtrees

extends Object

implements Cloneable, Serializable

This class is used in the NameConstraints class.

The ASN.1 definition is as follows:

 GeneralSubtrees ::= SEQUENCE SIZE (1..MAX) OF GeneralSubtree

 GeneralSubtree ::= SEQUENCE {
 	base			GeneralName,
 	minimum		[0]	BaseDistance DEFAULT 0,
 	maximum		[1]	BaseDistance OPTIONAL }

 BaseDistance ::= INTEGER (0..MAX)

The GeneralSubtree component specifies one or more naming subtrees. Each subtree isdefined by the name of the root of the subtree (base) and, optionally, within that subtree, an area that is bounded by upper or lower levels.

Visually, the subtree would be represented with the root at the top and the branches below. Therefore, the minimum field specifies the upper boundary of the area within the subtree. All names whose final name component is above the level specified are not contained within the area. A value of minimum equal to zero (the default) corresponds to the base, that is, the top node of the subtree. If minimum is set to one, then the naming subtree excludes the base node but includes subordinate nodes.

The maximum field specifies the lower boundary of the area within the subtree. All names whose final component is below the level specified are not contained within the area. A value of maximum equal to zero corresponds to the base, that is, the top node of the subtree. An absent maximum component indicates that no lower limit is imposed on the area within the subtree. If maximum is set to one, then the naming subtree excludes all nodes except the subtree base and its immediate subordinates.

For example, a name constraint for Internet mail addresses may specify a particular mailbox, all addresses at a particular host, or all mailboxes in a domain. To indicate a particular mailbox, the constraint is the complete mail address. For example, root@xyz.com indicates the root mailbox on the host xyz.com. To indicate all Internet mail addresses on a particular host, the constraint is specified as the host name. For example, the constraint xyz.com is satisfied by any mail address at the host xyz.com. To specify any address within a domain, the constraint is specified with a leading period. For example, xyz.com indicates all the Internet mail addresses in the domain xyz.com.

Copyright © RSA Security Inc., 1998-2001. All rights reserved.

See Also

Serialized Form

Constructor Summary

GeneralSubtrees()

Constructs an empty GeneralSubtrees object.

GeneralSubtrees(byte[] valueBER, int offset, int special)

Constructs a GeneralSubtrees object and initializes it with the given values.

Method Summary

void	addSubtree(GeneralName base, int minimum, int maximum) Adds a general subtree to this object.
Object	clone() Overrides the default clone method to get a deeper clone.
boolean	equals(Object obj) Returns true if this object and obj contain the same GeneralSubtrees, returns false otherwise.
GeneralName	getBase(int index) Gets the base value of the specified subtree.
int	getDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of this GeneralSubtrees object into encoding, beginning at offset.
int	getDERLen(int special) Returns the number of bytes that will be used by the DER encoding of this GeneralSubtrees object.
int	getMaximum(int index) Gets the maximum value of the specified general subtree.
int	getMinimum(int index) Gets the minimum value of the specified general subtree.
static int	getNextBEROffset(byte[] valueBER, int offset) Given valueBER, the BER encoding of a GeneralSubtrees object beginning at offset, finds the index to the next element in the encoding.
int	getSubtreeCount() Gets the number of subtrees in this object.
String	toString() Returns a String that describes this GeneralSubtrees object.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

GeneralSubtrees

public GeneralSubtrees()

Constructs an empty GeneralSubtrees object.

GeneralSubtrees

public GeneralSubtrees(byte[] valueBER,
                       int offset,
                       int special)
                throws NameException

Constructs a GeneralSubtrees object and initializes it with the given values.

Parameters

	valueBER		A byte array that contains the BER encoding of this object.
	offset		The offset into the valueBER array.
	special		The special instructions of the BER encoding, if there are any. The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Throws

NameException - If the encoding is invalid.

Method Detail

addSubtree

public void addSubtree(GeneralName base,
                       int minimum,
                       int maximum)

Adds a general subtree to this object.

Parameters

	base		The base field value.
	minimum		The minimum field value. If this value is not set, pass -1.
	maximum		The maximum field value. If this value is not set, pass -1.

getBase

public GeneralName getBase(int index)
                    throws NameException

Gets the base value of the specified subtree.

Parameters

index

The index to the specified general subtree.

Returns

The name at the top node of the specified general subtree.

Throws

NameException - If the specified index is invalid.

getMinimum

public int getMinimum(int index)
               throws NameException

Gets the minimum value of the specified general subtree.

Parameters

index

The index to the specified general subtree.

Returns

The upper boundary of the area within the specified general subtree.

Throws

NameException - If the specified index is invalid.

getMaximum

public int getMaximum(int index)
               throws NameException

Gets the maximum value of the specified general subtree.

Parameters

index

The index to the specified general subtree.

Returns

The lower boundary of the area within the specified general subtree.

Throws

NameException - If the specified index is invalid.

getSubtreeCount

public int getSubtreeCount()

Gets the number of subtrees in this object.

Returns

The number of subtrees in this object.

toString

public String toString()

Returns a String that describes this GeneralSubtrees object.

Overrides

toString in class Object

Returns

A String that describes this GeneralSubtrees object.

getNextBEROffset

public static int getNextBEROffset(byte[] valueBER,
                                   int offset)
                            throws NameException

Given valueBER, the BER encoding of a GeneralSubtrees object beginning at offset, finds the index to the next element in the encoding. In other words, this method gets the next offset after the GeneralSubtrees object.

For example, if the offset is 120 and the GeneralSubtrees object's BER encoding is 1819 bytes, then this method will return 1939, the index immediately following the GeneralSubtrees object. That is, nameBER[120] is the first byte in the encoding of the GeneralSubtrees object, nameBER[1938] is the last byte in the encoding of the GeneralSubtrees object, and the next element begins at index 1939.

Parameters

	nameBER		The BER encoding of this GeneralSubtrees object.
	offset		The offset into valueBER where the encoding begins.

Returns

The index to the next element in the BER encoding.

Throws

NameException - If the method cannot read the BER encoding.

getDERLen

public int getDERLen(int special)
              throws NameException

Returns the number of bytes that will be used by the DER encoding of this GeneralSubtrees object. If this object is not set with values, then this method returns zero.

Parameters

special

The special circumstances of the DER encoding, if there are any. The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Returns

The number of bytes that will be used by the DER encoding of this GeneralSubtrees object.

Throws

NameException - If the method cannot get the length of the DER encoding.

getDEREncoding

public int getDEREncoding(byte[] encoding,
                          int offset,
                          int special)
                   throws NameException

Places the DER encoding of this GeneralSubtrees object into encoding, beginning at offset. To determine the length of the encoding, call getDERLen. If this object is not yet set with values, then this method places nothing into the array and returns zero. To indicate that the DER encoding should follow any special instructions, use the special argument.

For example, to indicate the following:

      extension   [1] IMPLICIT Extension
 

pass in the following:

      special = (ASN1.CONTEXT_IMPLICIT | 1);
 

If there are no special circumstances, pass in the following:

      special = 0
 

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

	encoding		The byte array into which the result will be placed.
	offset		The offset into encoding where writing begins.
	special		The special circumstances of the DER encoding, if there are any. The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Returns

The number of bytes placed into encoding.

Throws

NameException - If the method cannot create the DER encoding.

equals

public boolean equals(Object obj)

Returns true if this object and obj contain the same GeneralSubtrees, returns false otherwise.

Overrides

equals in class Object

Parameters

obj

An instance of the GeneralSubtrees object.

Returns

A boolean that indicates whether these objects are equal.

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Returns

A new GeneralSubtrees object, a copy of this object.

Throws

CloneNotSupportedException - If the cloning operation is not successful.