net.rim.device.api.crypto.certificate.x509
Class X509DistinguishedName

java.lang.Object
  extended by net.rim.device.api.crypto.certificate.x509.X509DistinguishedName
All Implemented Interfaces:
DistinguishedName, Persistable

public final class X509DistinguishedName
extends Object
implements DistinguishedName, Persistable

Represents the ASN.1 type RDNSequence (Relative Distinguished Name).

The following example illustrates the RDNSequence.

 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName

 RelativeDistinguishedName ::=
   SET OF AttributeTypeAndValue

 AttributeTypeAndValue ::=  SEQUENCE {
          attributeType      OBJECT IDENTIFIER,
          parameters         ANY DEFINED BY attributeType }
 

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

Field Summary
Category: Signed static int STRING_FORMAT_DEFAULT
          Specifies that the default string format should be used, when passed as a parameter to toString().
Category: Signed static int STRING_FORMAT_RFC2253
          Specifies that an RFC2253-compliant string format should be used, when passed as a parameter to toString().
 
Constructor Summary
Category: Signed X509DistinguishedName(byte[] encoding)
          Creates and initializes a distinguished name (X509DistinguishedName) object.
Category: Signed X509DistinguishedName(byte[] encoding, int offset, int length)
          Creates and initializes a distinguished name (X509DistinguishedName) object.
Category: Signed X509DistinguishedName(String input)
          Creates and initializes a distinguished name (X509DistinguishedName) object.
Category: Signed X509DistinguishedName(String input, char delimiter)
          Creates and initializes a distinguished name (X509DistinguishedName) object.
Category: Signed X509DistinguishedName(ASN1InputStream input)
          Creates and initializes a distinguished name (X509DistinguishedName) object.
 
Method Summary
Category: Signed  boolean equals(Object obj)
          Check that this X509DistinguishedName is equal to obj.
Category: Signed  String getCommonName()
          Retrieve the common name attribute associated with this distinguished name.
Category: Signed  String getCountry()
          Retrieve the country attribute associated with this distinguished name.
Category: Signed  String getEmailAddress()
          Retrieve the email attribute associated with this distinguished name.
Category: Signed  byte[] getEncoding()
          Returns the encoding of the DistinguishedName.
Category: Signed  String getLocality()
          Retrieve the locality attribute associated with this distinguished name.
Category: Signed  Enumeration getOIDs()
          Returns an enumeration of all the OIDs for the names.
Category: Signed  String getOrganization()
          Retrieve the organization attribute associated with this distinguished name.
Category: Signed  String getOrganizationalUnit()
          Retrieve the organization unit attribute associated with this distinguished name.
Category: Signed  String getStateOrProvince()
          Retrieve the state-or-province attribute associated with this distinguished name.
Category: Signed  String getString(OID oid)
          Retrieve the string associated with this OID.
Category: Signed  String getSurname()
          Retrieve the surname attribute associated with this distinguished name.
Category: Signed  int hashCode()
          Returns a hash code value for the object.
Category: Signed  String toRFC2253CompatibleString()
          Convert this DistinguishedName's internal representation to a string format.
Category: Signed  String toString()
          Convert this DistinguishedName's internal representation to a string format.
Category: Signed  String toString(int stringFormat)
          Convert this DistinguishedName's internal representation to a string format.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 



Field Detail

STRING_FORMAT_DEFAULT

public static final int STRING_FORMAT_DEFAULT
Specifies that the default string format should be used, when passed as a parameter to toString().

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

STRING_FORMAT_RFC2253

public static final int STRING_FORMAT_RFC2253
Specifies that an RFC2253-compliant string format should be used, when passed as a parameter to toString().

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0


Constructor Detail

X509DistinguishedName

public X509DistinguishedName(String input)
                      throws ASN1EncodingException
Creates and initializes a distinguished name (X509DistinguishedName) object.

Note that the input is expected to be represented as a comma-delimited list, such as CN=Joe Johnson, O=Company X, C=US. No ending character is needed, ie. the list is assumed to be finished with the last character present in the input string. The recognized data labels are "CN", "SN", "C", "L", "ST", "O", "OU", and "E". Any other labels will be ignored and not included in the object. This means they won't be a factor in any .equals or comparison operations. Also note that the ASN1 encoding of this DN has the tag and value pairs in the order that they appear in input.

Default String encoding type is DERTags.UTF8_STRING except for the label "E" where the encoding type is DERTags.IA5_STRING.

Parameters:
input - An String storing the encoding of the Distinguished Name, eg "C=Mike, OU=Software, O=RIM". Currently supported strings are:
Throws:
ASN1EncodingException - Thrown if an error occurs reading the input stream.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

X509DistinguishedName

public X509DistinguishedName(String input,
                             char delimiter)
                      throws ASN1EncodingException
Creates and initializes a distinguished name (X509DistinguishedName) object.

Note that the input is expected to be represented as a delimited list ( delimited by the character delimiter ), such as CN=Joe Johnson, O=Company X, C=US. No ending character is needed, ie. the list is assumed to be finished with the last character present in the input string. The recognized data labels are "CN", "SN", "C", "L", "ST", "O", "OU", and "E". Any other labels will be ignored and not included in the object. This means they won't be a factor in any .equals or comparison operations. Also note that the ASN1 encoding of this DN has the tag and value pairs in the order that they appear in input.

Default String encoding type is DERTags.UTF8_STRING except for the label "E" where the encoding type is DERTags.IA5_STRING.

Parameters:
input - An String storing the encoding of the Distinguished Name, eg "C=Mike delimiter OU=Software code>delimiter O=RIM". Currently supported strings are:
delimiter - A character used to seperate each attribute tag/value pair. The most common values are ',' or ';'
Throws:
ASN1EncodingException - Thrown if an error occurs reading the input stream.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

X509DistinguishedName

public X509DistinguishedName(ASN1InputStream input)
                      throws IOException,
                             ASN1EncodingException
Creates and initializes a distinguished name (X509DistinguishedName) object.

Parameters:
input - An ASN1InputStream storing the encoding of the Distinguished Name.
Throws:
IOException - Thrown if an I/O error occurs.
ASN1EncodingException - Thrown if an error occurs reading the input stream.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

X509DistinguishedName

public X509DistinguishedName(byte[] encoding)
                      throws ASN1EncodingException
Creates and initializes a distinguished name (X509DistinguishedName) object.

Parameters:
encoding - The DER encoding of this object.
Throws:
ASN1EncodingException - Thrown if an error occurs reading the input stream.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

X509DistinguishedName

public X509DistinguishedName(byte[] encoding,
                             int offset,
                             int length)
                      throws ASN1EncodingException
Creates and initializes a distinguished name (X509DistinguishedName) object.

Parameters:
encoding - The DER encoding of this object.
offset - The offset, or start position, of the data within the array.
length - The amount of data to read.
Throws:
ASN1EncodingException - Thrown if an error occurs reading the input stream.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0


Method Detail

getEncoding

public byte[] getEncoding()
Description copied from interface: DistinguishedName
Returns the encoding of the DistinguishedName.

Specified by:
getEncoding in interface DistinguishedName
Returns:
A byte array containing the encoding. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

equals

public boolean equals(Object obj)
Check that this X509DistinguishedName is equal to obj.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
Returns true if obj equals this
See Also:
Boolean.hashCode(), Hashtable
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getString

public String getString(OID oid)
Retrieve the string associated with this OID. If there are multiple attribute values for this OID, they are all returned, separated by commas.

Specified by:
getString in interface DistinguishedName
Parameters:
oid - The oid to look up the string with
Returns:
Returns the string associated with oid, or else null
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getCommonName

public String getCommonName()
Retrieve the common name attribute associated with this distinguished name.

Specified by:
getCommonName in interface DistinguishedName
Returns:
A String representing the common name. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getEmailAddress

public String getEmailAddress()
Retrieve the email attribute associated with this distinguished name.

Note that this function is for legacy only. X509 v3 defines that an email address should be found in the SubjectAltNames certificate extension.

Specified by:
getEmailAddress in interface DistinguishedName
Returns:
A String representing the email address. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getSurname

public String getSurname()
Retrieve the surname attribute associated with this distinguished name.

Specified by:
getSurname in interface DistinguishedName
Returns:
A String representing the surname. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getCountry

public String getCountry()
Retrieve the country attribute associated with this distinguished name.

Specified by:
getCountry in interface DistinguishedName
Returns:
A String representing the country name. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getLocality

public String getLocality()
Retrieve the locality attribute associated with this distinguished name.

Specified by:
getLocality in interface DistinguishedName
Returns:
A String representing the locality. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getStateOrProvince

public String getStateOrProvince()
Retrieve the state-or-province attribute associated with this distinguished name.

Specified by:
getStateOrProvince in interface DistinguishedName
Returns:
A String representing the state or province name. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getOrganization

public String getOrganization()
Retrieve the organization attribute associated with this distinguished name.

Specified by:
getOrganization in interface DistinguishedName
Returns:
Ais String representing the organization name. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getOrganizationalUnit

public String getOrganizationalUnit()
Retrieve the organization unit attribute associated with this distinguished name.

Specified by:
getOrganizationalUnit in interface DistinguishedName
Returns:
A String representing the name of the organizational unit. May be null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getOIDs

public Enumeration getOIDs()
Returns an enumeration of all the OIDs for the names.

Specified by:
getOIDs in interface DistinguishedName
Returns:
Returns an enumeration of all of the identifying OIDs in this DN
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

toString

public String toString()
Convert this DistinguishedName's internal representation to a string format.

This method will return a string in an RFC2253-like format. All known attribute type keywords will be emitted, including all of the keywords defined in RFC2253 (CN, L, ST, O, OU, C, STREET, DC, UID) as well as some other keywords like email (E). Other attribute types are not emitted. This string format would be useful for display to a user, for example.

Example output would be CN=Amy Krul;O=Research In Motion;C=US;E=akrul@rim.com.

Specified by:
toString in interface DistinguishedName
Overrides:
toString in class Object
Returns:
Returns the String representation
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

toRFC2253CompatibleString

public String toRFC2253CompatibleString()
Convert this DistinguishedName's internal representation to a string format.

This method will return the string in RFC2253-compliant format. The attribute type keywords defined in RFC2253 (CN, L, ST, O, OU, C, STREET, DC, UID) will be emitted. Any other attribute types are emitted in dotted-decimal format. Commas and other special characters within attribute values are escaped.

Example output would be CN=Amy Krul\, Developer,O=Research In Motion,C=US,1.2.840.113549.1.9.1=akrul@rim.com.

Returns:
Returns the String representation
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

toString

public String toString(int stringFormat)
Convert this DistinguishedName's internal representation to a string format.

This method will return the string in one of two formats:

  1. The default string format (specified by STRING_FORMAT_DEFAULT): All known attribute type keywords will be emitted, including all of the keywords defined in RFC2253 (CN, L, ST, O, OU, C, STREET, DC, UID) as well as some other keywords like email (E). Other attribute types are not emitted.
  2. An RFC2253-compliant format (specified by STRING_FORMAT_RFC2253): The attribute type keywords defined in RFC2253 (CN, L, ST, O, OU, C, STREET, DC, UID) will be emitted. Any other attribute types are emitted in dotted-decimal format. Commas and other special characters within attribute values are escaped.

Parameters:
stringFormat - indicates which of the supported string formats to use
Returns:
the String respresentation
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.