iaik.x509.extensions

Class SubjectAltName

java.lang.Object

iaik.x509.V3Extension

iaik.x509.extensions.SubjectAltName

public class SubjectAltName
extends V3Extension

This class implements the SubjectAltName extension.

The SubjectAltName extension is a standard X509v3 extension, which has to be marked as being critical if the certificate´s subject field contains an empty sequence.

Each extension is associated with a specific certificateExtension object identifier, derived from:

 certificateExtension  OBJECT IDENTIFIER ::=
                            {joint-iso-ccitt(2) ds(5) 29}
 id-ce                 OBJECT IDENTIFIER ::=  certificateExtension
 

The object identifier for the SubjectAltName extension is defined as:

id-ce-subjectAltName OBJECT IDENTIFIER ::= { id-ce 17 }

which corresponds to the OID string "2.5.29.17".

The X.509 Certificate and CRL profile presented in RFC 3280 specifies the Subject Alternative Name extension for allowing to bind additional identities to the subject of the certificate. Defined options include an rfc822 name (electronic mail address), a DNS name, an IP address, and an URI:

 SubjectAltName ::= GeneralNames
 

 GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName
 

 GeneralName ::= CHOICE {
          otherName                       [0]     OtherName,
          rfc822Name                      [1]     IA5String,
          dNSName                         [2]     IA5String,
          x400Address                     [3]     ORAddress,
          directoryName                   [4]     Name,
          ediPartyName                    [5]     EDIPartyName,
          uniformResourceIdentifier       [6]     IA5String,
          iPAddress                       [7]     OCTET STRING,
          registeredID                    [8]     OBJECT IDENTIFIER}
 

 OtherName ::= SEQUENCE {
          type-id    OBJECT IDENTIFIER,
          value      [0] EXPLICIT ANY DEFINED BY type-id }
 

 EDIPartyName ::= SEQUENCE {
          nameAssigner            [0]     DirectoryString OPTIONAL,
          partyName               [1]     DirectoryString }
 

 DirectoryString ::= CHOICE {
    teletexString           TeletexString (SIZE (1..maxSize),
    printableString         PrintableString (SIZE (1..maxSize)),
    universalString         UniversalString (SIZE (1..maxSize)),
    utf8String              UTF8String (SIZE (1.. MAX)),
    bmpString               BMPString (SIZE(1..maxSIZE))
 }
 

If the only subject identity included in the certificate is an alternative name form (e.g., an electronic mail address), then the subject distinguished name shall be empty (an empty sequence), and the subjectAltName extension shall be present. If the subject field contains an empty sequence, the subjectAltName extension shall be marked critical.

More information can be found in RFC 3280, section 4.2.1.7 "Subject Alternative Name".

For adding a SubjectAltName extension object to a X509Certificate, use the addExtension method of the iaik.x509.X509Certificate class, e.g.:

 X509Certificate cert = new X509Certificate();
  ...
 GeneralNames generalNames = new GeneralNames();
 generalNames.addName(new GeneralName(GeneralName.iPAddress, "127.0.0.1"));
 SubjectAltName subAltName = new SubjectAltName(generalNames);
 cert.addExtension(subAltName);
 

When intending to mark this extension as critical (which necessarily has to be done if the certificate´s subject field is an empty sequence), use the setCritical method of the iaik.x509.V3Extension parent class (note that you have to mark an extension as critical before adding the extension to a certificate), e.g.:

 subAltName.setCritical(true);
 

See Also:

GeneralNames, GeneralName, IA5String, OCTET_STRING, ObjectID, Name, T61String, PrintableString, UNIString, BMPString, V3Extension, X509Extensions, X509Certificate

Field Summary

Fields

Modifier and Type	Field and Description
static ObjectID	oid The object identifier of this SubjectAltName extension.

Fields inherited from class iaik.x509.V3Extension

critical

Constructor Summary

Constructors

Constructor and Description
SubjectAltName() Default Constructor.
SubjectAltName(GeneralNames gn) Constructs a SubjectAltName extension with the given GeneralNames as value.

Method Summary

Modifier and Type	Method and Description
GeneralNames	getGeneralNames() Returns the alternative name of the subject.
ObjectID	getObjectID() Returns the object ID of this SubjectAltName extension
int	hashCode() Returns a hashcode for this identity.
void	init(ASN1Object obj) Inits this SubjectAltName implementation with an ASN1object representing the value of this extension.
void	setGeneralNames(GeneralNames gn) Sets the alternative name of the subject.
ASN1Object	toASN1Object() Returns an ASN1Object representing the value of this SubjectAltName extension object.
java.lang.String	toString() Returns a string that represents the contents of this SubjectAltName 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 SubjectAltName extension. The corresponding OID string is "2.5.29.17".

Constructor Detail

SubjectAltName

public SubjectAltName()

Default Constructor.

Creates an empty SubjectAltName object. Use setGeneralNames for supplying some GeneralNames object to this SubjectAltName extension.

The critical value per default is set to false. If you want to specify this extension as critical (which necessarily has to be done if the certificate´s subject field is an empty sequence) before adding it to a certificate, use the setCritical method of the iaik.x509.V3Extension parent class, e.g.:

 subAltName.setCritical(true);
 cert.addExtension(subAltName);
 

See Also:

V3Extension.setCritical(boolean)

SubjectAltName

public SubjectAltName(GeneralNames gn)

Constructs a SubjectAltName extension with the given GeneralNames as value.

The critical value per default is set to false. If you want to specify this extension as critical (which necessarily has to be done if the certificate´s subject field is an empty sequence) before adding it to a certificate, use the setCritical method of the iaik.x509.V3Extension parent class, e.g.:

 X509Certificate cert = new X509Certificate();
  ...
 GeneralNames generalNames = new GeneralNames();
 generalNames.addName(new GeneralName(GeneralName.iPAddress, "127.0.0.1"));
 SubjectAltName subAltName = new SubjectAltName(generalNames);
 subAltName.setCritical(true);
 cert.addExtension(subAltName);
 

Parameters:

gn - the alternative name of the subject as GeneralNames

See Also:

V3Extension.setCritical(boolean), GeneralNames

Method Detail

getObjectID

public ObjectID getObjectID()

Returns the object ID of this SubjectAltName extension

Specified by:

getObjectID in class V3Extension

Returns:

the object ID

init

public void init(ASN1Object obj)
          throws X509ExtensionException

Inits this SubjectAltName implementation with an ASN1object representing the value of this extension.

The given ASN1Object represents a GeneralNames value (additionally) identifying the certificate subject.

The given ASN1Object is the one created by toASN1Object().

This method is used by the X509Extensions class when parsing the ASN.1 representation of a certificate for properly initializing an included SubjectAltName 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 SubjectAltName as ASN1Object

Throws:

X509ExtensionException - if the extension could not be parsed

toASN1Object

public ASN1Object toASN1Object()
                        throws X509ExtensionException

Returns an ASN1Object representing the value of this SubjectAltName extension object.

The returned ASN1Object represents a GeneralNames value (additionally) identifying the certificate subject:

 SubjectAltName ::= GeneralNames
 

Specified by:

toASN1Object in class V3Extension

Returns:

the value of this SubjectAltName as ASN1Object

Throws:

X509ExtensionException - if the ASN1Object cannot be created because of an coding error

setGeneralNames

public void setGeneralNames(GeneralNames gn)

Sets the alternative name of the subject.

For instance:

 GeneralNames generalNames = new GeneralNames();
 generalNames.addName(new GeneralName(GeneralName.iPAddress, "127.0.0.1"));
 SubjectAltName subAltName = new SubjectAltName();
 subAltName.setGeneralNames(generalNames);
 

Parameters:

gn - the alternative name of the subject as GeneralNames

See Also:

getGeneralNames(), GeneralNames

getGeneralNames

public GeneralNames getGeneralNames()

Returns the alternative name of the subject.

Returns:

the alternative name as GeneralNames

See Also:

setGeneralNames(iaik.asn1.structures.GeneralNames), GeneralNames

hashCode

public int hashCode()

Returns a hashcode for this identity.

Specified by:

hashCode in class V3Extension

Returns:

a hash code for this identity

toString

public java.lang.String toString()

Returns a string that represents the contents of this SubjectAltName extension.

Overrides:

toString in class java.lang.Object

Returns:

the string representation