iaik.xkms
Interface KeyInfo

public interface KeyInfo

KeyInfo data of KeyBindings.

The public key information to which the key binding information is bound. KeyInfo may contain keys, names, certificates and other public key management information.

KeyInfo is a collection of different objects. The add... methods add objects to the internal list, use get... methods to retrieve objects. Get the size of the current content with getLength(). Get the type of the object at list position x with getType(int).

The X509Data Object is a list itself and a container for other X509... objects. Thus, on finding a X509Data object in the main list (getType(position)==KeyInfoType.X509Data) one can dig deeper into this sublist with getLength(int) and getType(int, int) etc.

Note that KeyInfo is a temporary storage. It only keeps references to the passed objects and remembers their order, but does not do defensive copying of object contents.

NOTE: The KeyInfo API may not be final, upon more experience with usage patterns methods may change.

The KeyName element contains a string value (in which white space is significant) which may be used to communicate a key identifier to the recipient. Typically, KeyName contains an identifier related to the key pair, but it may contain other protocol-related information that indirectly identifies a key pair. (Common uses of KeyName include simple string names for keys, a key index, a distinguished name (DN), an email address, etc.)

The KeyValue element contains a single public key.

A RetrievalMethod element within KeyInfo is used to convey a reference to KeyInfo information that is stored at another location.

An X509Data element within KeyInfo contains one or more identifiers of keys or X509 certificates, certificates' identifiers or a revocation list. At least one element, from the following set of element types:
* The X509IssuerSerial element, which contains an X.509 issuer distinguished name/serial number pair that SHOULD be compliant with RFC2253 [LDAP-DN]
* The X509SubjectName element, which contains an X.509 subject distinguished name that SHOULD be compliant with RFC2253 [LDAP-DN]
* The X509SKI element, which contains the base64 encoded plain (i.e. non-DER-encoded) value of a X509 V.3 SubjectKeyIdentifier extension.
* The X509Certificate element, which contains a base64-encoded X509v3 certificate, and Elements from an external namespace which accompanies/complements any of the elements above.
* The X509CRL element, which contains a base64-encoded certificate revocation list (CRL).

No ordering is implied.

Method Summary

void	addKeyName(String name) Adds KeyName to KeyInfo content.
void	addKeyValue(PublicKey key) Adds PublicKey to KeyInfo content.
void	addRetrievalMethod(URI uri, URI type) Adds RetrievalMethod to KeyInfo content.
void	addX509Certificate(X509Certificate cert) Adds X509 certificate to KeyInfo content,
void	addX509Certificates(X509Certificate[] certs) Adds an array of X509 certificates to KeyInfo content,
void	addX509CRL(X509CRL crl) Adds X509 certificate revocation list (CRL) to KeyInfo content.
void	addX509IssuerSerial(String issuerName, BigInteger serialnumber) Adds X509 issuer distinguished name/serial number pair to KeyInfo content.
void	addX509SKI(byte[] ski) Adds X509v3 SubjectKeyIdentifier extension to KeyInfo content.
void	addX509SubjectName(String name) Adds X509 subject distinguished name to KeyInfo content.
KeyInfo	duplicate() Duplicates KeyInfo object.
String	getKeyName(int index) Gets KeyName at specific KeyInfo list position.
List<String>	getKeyNames() Gets list of all KeyName objects.
PublicKey	getKeyValue(int index) Gets PublicKey at specific KeyInfo list position.
List<PublicKey>	getKeyValues() Gets list of all KeyValue objects.
int	getLength() Gets size of current KeyInfo content.
int	getLength(int index) Gets size of X509Data sublist at specified position of KeyInfo main list.
URI[]	getRetrievalMethod(int index) Gets RetrievalMethod at specific KeyInfo list position.
List<URI[]>	getRetrievalMethods() Gets list of all RetrievalMethod objects.
KeyInfoType	getType(int index) Gets type of object at KeyInfo list position.
KeyInfoType	getType(int index, int innerindex) Gets type of X509 subtype in X509Data list.
X509Certificate	getX509Certificate(int index, int innerindex) Gets X509 certificate at specific KeyInfo list position.
X509CRL	getX509CRL(int index, int innerindex) Gets X509 certificate revocation list (CRL) at specific KeyInfo list position.
List<Integer>	getX509Datas() Gets list of indices of X509Data objects in main KeyInfo list.
Object[]	getX509IssuerSerial(int index, int innerindex) Gets X509 issuer distinguished name/serial number pair at specific KeyInfo list position.
byte[]	getX509SKI(int index, int innerindex) Gets X509v3 SubjectKeyIdentifier extension at specific KeyInfo list position.
String	getX509SubjectName(int index, int innerindex) Gets X509 subject distinguished name at specific KeyInfo list position.

Method Detail

getKeyNames

List<String> getKeyNames()

Gets list of all KeyName objects.

This is a convenience method.

Returns:

list containing all KeyName objects

getKeyValues

List<PublicKey> getKeyValues()

Gets list of all KeyValue objects.

This is a convenience method.

Returns:

list containing all KeyValue objects

getRetrievalMethods

List<URI[]> getRetrievalMethods()

Gets list of all RetrievalMethod objects.

This is a convenience method.

Returns:

list containing all RetrievalMethod objects. Note that each list entry contains an array of 2 URI objects, the first being the "uri" component and the second being the "type" component.

getX509Datas

List<Integer> getX509Datas()

Gets list of indices of X509Data objects in main KeyInfo list.

This is a convenience method.

Returns:

list of positions.

duplicate

KeyInfo duplicate()

Duplicates KeyInfo object.

Note that only internal Lists and references to objects are duplicated, not the objects themselves.

addKeyName

void addKeyName(String name)

Adds KeyName to KeyInfo content.

Parameters:

name - key name to add

Throws:

IllegalArgumentException - if parameter is null

addKeyValue

void addKeyValue(PublicKey key)

Adds PublicKey to KeyInfo content.

Parameters:

key - public key to add

Throws:

IllegalArgumentException - if parameter is null

addRetrievalMethod

void addRetrievalMethod(URI uri,
                        URI type)

Adds RetrievalMethod to KeyInfo content.

Parameters:

uri - URI to retrieve data from

type - URI specifying type of KeyInfo to retrieve (may be null)

Throws:

IllegalArgumentException - if parameter is null

addX509IssuerSerial

void addX509IssuerSerial(String issuerName,
                         BigInteger serialnumber)

Adds X509 issuer distinguished name/serial number pair to KeyInfo content.

Parameters:

issuerName - X509 issuer distinguished name

serialnumber - X509 serial number

Throws:

IllegalArgumentException - if one or both parameters are null

addX509SKI

void addX509SKI(byte[] ski)

Adds X509v3 SubjectKeyIdentifier extension to KeyInfo content.

Parameters:

ski - X509v3 SubjectKeyIdentifier extension

Throws:

IllegalArgumentException - if parameter is null

addX509SubjectName

void addX509SubjectName(String name)

Adds X509 subject distinguished name to KeyInfo content.

Parameters:

name - X509 subject distinguished name to add.

Throws:

IllegalArgumentException - if parameter is null

addX509Certificate

void addX509Certificate(X509Certificate cert)

Adds X509 certificate to KeyInfo content,

Parameters:

cert - X509 certificate to add

Throws:

IllegalArgumentException - if parameter is null

addX509Certificates

void addX509Certificates(X509Certificate[] certs)

Adds an array of X509 certificates to KeyInfo content,

This is a convenience function, it loops over the certificates and repeatedly calls addX509Certificate(X509Certificate).

Parameters:

certs - X509 certificates to add

Throws:

IllegalArgumentException - if parameter is null

addX509CRL

void addX509CRL(X509CRL crl)

Adds X509 certificate revocation list (CRL) to KeyInfo content.

Parameters:

crl - X509 certificate revocation list to add

Throws:

IllegalArgumentException - if parameter is null

getType

KeyInfoType getType(int index)

Gets type of object at KeyInfo list position.

Parameters:

index - position in list

Returns:

type of object: one of KeyInfoType.KeyName, KeyInfoType.KeyValue, KeyInfoType.RetrievalMethod, KeyInfoType.X509Data
KeyInfoType.INVALID if index is out of bounds

getType

KeyInfoType getType(int index,
                    int innerindex)

Gets type of X509 subtype in X509Data list.

Parameters:

index - index of X509Data in KeyInfo list (thus, KeyInfo.getType(index) must be equal KeyInfoType.X509Data)

innerindex - subindex in X509Data list

Returns:

subtype of X509Data: one of KeyInfoType.X509IssuerSerial, KeyInfoType.X509SKI, KeyInfoType.X509SubjectName, KeyInfoType.X509Certificate or KeyInfoType.X509CRL.
KeyInfoType.INVALID if object at index position is not KeyInfoType.X509Data or out of bounds

getLength

int getLength()

Gets size of current KeyInfo content.

Returns:

number of objects in KeyInfo.

getLength

int getLength(int index)

Gets size of X509Data sublist at specified position of KeyInfo main list.

Parameters:

index - position of X509Data in KeyInfo list (thus, KeyInfo.getType(index) must be equal KeyInfoType.X509Data)

Returns:

number of objects in X509Data, 0 if index out of bounds

getKeyName

String getKeyName(int index)

Gets KeyName at specific KeyInfo list position.

Parameters:

index - index into KeyInfo list

Returns:

KeyName or null if KeyInfo.getType(index) is not KeyInfoType.KeyName

getKeyValue

PublicKey getKeyValue(int index)

Gets PublicKey at specific KeyInfo list position.

Parameters:

index - index into KeyInfo list

Returns:

PublicKey or null if KeyInfo.getType(index) is not KeyInfoType.KeyValue

getRetrievalMethod

URI[] getRetrievalMethod(int index)

Gets RetrievalMethod at specific KeyInfo list position.

Parameters:

index - index into KeyInfo list

Returns:

array of 2 URI objects, the first being the "uri" component and the second being the "type" component or null if KeyInfo.getType(index) is not KeyInfoType.RetrievalMethod

getX509IssuerSerial

Object[] getX509IssuerSerial(int index,
                             int innerindex)

Gets X509 issuer distinguished name/serial number pair at specific KeyInfo list position.

Parameters:

index - index of X509Data in KeyInfo list (thus, KeyInfo.getType(index) must be equal KeyInfoType.X509Data)

innerindex - subindex in X509Data list

Returns:

array of 2 objects, the first being a String(issuer distinguished name), the second a BigInteger(serial number).
null if KeyInfo.getType(index,innerindex) is not KeyInfoType.X509IssuerSerial

getX509SKI

byte[] getX509SKI(int index,
                  int innerindex)

Gets X509v3 SubjectKeyIdentifier extension at specific KeyInfo list position.

Parameters:

index - index of X509Data in KeyInfo list (thus, KeyInfo.getType(index) must be equal KeyInfoType.X509Data)

innerindex - subindex in X509Data list

Returns:

X509v3 SubjectKeyIdentifier extension or null if KeyInfo.getType(index,innerindex) is not KeyInfoType.X509SKI

getX509SubjectName

String getX509SubjectName(int index,
                          int innerindex)

Gets X509 subject distinguished name at specific KeyInfo list position.

Parameters:

index - index of X509Data in KeyInfo list (thus, KeyInfo.getType(index) must be equal KeyInfoType.X509Data)

innerindex - subindex in X509Data list

Returns:

X509 subject distinguished name or null if KeyInfo.getType(index,innerindex) is not KeyInfoType.X509SubjectName

getX509Certificate

X509Certificate getX509Certificate(int index,
                                   int innerindex)

Gets X509 certificate at specific KeyInfo list position.

Parameters:

index - index of X509Data in KeyInfo list (thus, KeyInfo.getType(index) must be equal KeyInfoType.X509Data)

innerindex - subindex in X509Data list

Returns:

X509 certificate or null if KeyInfo.getType(index,innerindex) is not KeyInfoType.X509Certificate

getX509CRL

X509CRL getX509CRL(int index,
                   int innerindex)

Gets X509 certificate revocation list (CRL) at specific KeyInfo list position.

Parameters:

index - index of X509Data in KeyInfo list (thus, KeyInfo.getType(index) must be equal KeyInfoType.X509Data)

innerindex - subindex in X509Data list

Returns:

X509 certificate revocation list (CRL) or null if KeyInfo.getType(index,innerindex) is not KeyInfoType.X509CRL