iaik.xkms
Class XKMSContext

Object
  XKMSContext

public abstract class XKMSContext
extends Object

Start here :-)

This class is the main entrance point to the IAIK XKMS API. The first thing as a client is to obtain an instance of XKMSContext by means of the XKMSContext.newInstance(...) method.

All further XKMS objects are created from this instance using create... style methods.

Thread safety
If a client of IAIK XKMS is multithreaded and multiple threads want to use IAIK XKMS functionalities, there are a few points to remember:
- Use one XKMSContext instance per thread.
- Objects created by one XKMSContext can only be passed on to another XKMSContext of identical subtype.
- If you want to use the same XKMS object in multiple threads, e.g. share an Authentication object, it is your responsibility to synchronize accesses to this object.

Method Summary

abstract Authentication	createAuthentication() Creates a new Authentication object.
abstract CompoundRequest	createCompoundRequest() Creates a new CompoundRequest, which is empty, except for a randomly generated ID.
abstract CompoundResult	createCompoundResult(XRequestAbstractType request) Creates a new CompoundResult.
abstract KeyBinding	createKeyBinding() Creates a new KeyBinding object.
KeyInfo	createKeyInfo() Creates a new (empty) KeyInfo object.
abstract LocateRequest	createLocateRequest() Creates a new LocateRequest, which is empty, except for a randomly generated ID.
abstract LocateResult	createLocateResult(XRequestAbstractType request) Creates a new LocateResult.
abstract PendingRequest	createPendingRequest() Creates a new PendingRequest, which is empty, except for a randomly generated ID.
abstract PrototypeKeyBinding	createPrototypeKeyBinding() Creates a new PrototypeKeyBinding object.
abstract QueryKeyBinding	createQueryKeyBinding() Creates a new QueryKeyBinding object.
abstract RecoverKeyBinding	createRecoverKeyBinding() Creates a new RecoverKeyBinding object.
abstract RecoverRequest	createRecoverRequest() Creates a new RecoverRequest, which is empty, except for a randomly generated ID.
abstract RecoverResult	createRecoverResult(XRequestAbstractType request) Creates a new RecoverResult.
abstract RegisterRequest	createRegisterRequest() Creates a new RegisterRequest, which is empty, except for a randomly generated ID.
abstract RegisterResult	createRegisterResult(XRequestAbstractType request) Creates a new RegisterResult.
abstract ReissueKeyBinding	createReissueKeyBinding() Creates a new ReissueKeyBinding object.
abstract ReissueRequest	createReissueRequest() Creates a new ReissueRequest, which is empty, except for a randomly generated ID.
abstract ReissueResult	createReissueResult(XRequestAbstractType request) Creates a new ReissueResult.
abstract Result	createResult(XRequestAbstractType request) Creates a new Result.
abstract RevokeKeyBinding	createRevokeKeyBinding() Creates a new RevokeKeyBinding object.
abstract RevokeRequest	createRevokeRequest() Creates a new RevokeRequest, which is empty, except for a randomly generated ID.
abstract RevokeResult	createRevokeResult(XRequestAbstractType request) Creates a new RevokeResult.
abstract StatusRequest	createStatusRequest() Creates a new StatusRequest, which is empty, except for a randomly generated ID.
abstract StatusResult	createStatusResult(XRequestAbstractType request) Creates a new StatusResult.
abstract UnverifiedKeyBinding	createUnverifiedKeyBinding() Creates a new UnverifiedKeyBinding object.
abstract ValidateRequest	createValidateRequest() Creates a new ValidateRequest, which is empty, except for a randomly generated ID.
abstract ValidateResult	createValidateResult(XRequestAbstractType request) Creates a new ValidateResult.
abstract XPrivateKey	createXPrivateKey() Creates a new XPrivateKey object.
abstract XPrivateKey	decryptPrivateKeyBlock(XKRSSResult message, Key key) Decrypts and returns the encrypted private key of this result message.
abstract XMessageAbstractType	DOMToMessage(Element startelement) Converts DOM tree to XKMS message.
static void	DOMToStream(Document doc, OutputStream os) Outputs a DOM Document to an OutputStream.
static String	DOMToString(Document document) Converts a DOM document into a String.
int	getIdLength() Gets default number of characters for generated message Id.
X509Certificate	getMessageCertificate() Gets the default certificate of newly created messages.
PrivateKey	getMessagePrivateKey() Gets the default signature private key of newly created messages.
int	getNonceLength() Gets default number of characters for generated message nonce.
String	getServiceURI() Get default ServiceURI of messages.
String	getType() Gets subtype of XKMSContext instance.
abstract Document	MessageToDOM(XMessageAbstractType message) Converts XKMS message to DOM tree.
void	MessageToStream(XMessageAbstractType message, OutputStream os) Outputs a message to an OutputStream.
String	MessageToString(XMessageAbstractType message) Converts a message into a String.
static XKMSContext	newInstance(String type) Create a new custom tuned instance of XKMSContext.
void	setIdLength(int length) Sets default number of characters for generated message Id.
void	setMessageCredentials(X509Certificate cert, PrivateKey privkey) Set default credentials to use for global message signature.
void	setNonceLength(int length) Sets default number of characters for generated message nonce.
void	setRandomId(XMessageAbstractType message) Sets the Id attribute of a message to a random value.
void	setRandomNonce(XMessageAbstractType message) Sets the Nonce of a message to a random value.
void	setServiceURI(String servicename) Sets default ServiceURI of messages.
Document	StreamToDOM(InputStream stream) Parses XML from InputStream and returns a DOM representation.
XMessageAbstractType	StreamToMessage(InputStream stream) Converts an InputStream into a Message.
Document	StringToDOM(String string) Parses XML from String and returns a DOM representation.
XMessageAbstractType	StringToMessage(String message) Converts a String into a Message.
abstract boolean	validateKeyBindingAuthenticationSignature(XKRSSRequest message, Key key) Validates KeyBindingAuthentication signature with the supplied key.
abstract boolean	validateProofOfPossessionSignature(XKRSSRequest message, Key key) Validates ProofOfPossession signature with the supplied key.
abstract boolean	validateSignature(XMessageAbstractType message, Key key) Validates global message signature with supplied public key.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newInstance

public static XKMSContext newInstance(String type)
                               throws XKMSException

Create a new custom tuned instance of XKMSContext.

Parameters:

type - A string of format "marshaller:xmlprovider" which specifies which lowlevel implementation to use.

Valid values for marshaller:
JAXB - JAXB 2.0 marshalling autogenerated from XKMS schema.

Valid values for xmlprovider:
IAIK - use IAIK JCE and XSECT libraries (=maximum functionality).
JWSDP - use JWSDP (=Apache) xmlsec libraries (=reduced fuctionality).

Or pass null for autodetection.

Throws:

XKMSException - if something goes wrong.

getType

public String getType()

Gets subtype of XKMSContext instance.

Returns:

String description of XKMSContext subtype.

DOMToStream

public static void DOMToStream(Document doc,
                               OutputStream os)
                        throws XKMSException

Outputs a DOM Document to an OutputStream. (e.g. System.out)

Parameters:

doc - DOM document which should be output to Stream

os - Stream to write result to

Throws:

XKMSException - if something goes wrong.

DOMToString

public static String DOMToString(Document document)
                          throws XKMSException

Converts a DOM document into a String.

Parameters:

document - DOM document which should be converted into a String

Returns:

String representative of the XML document

Throws:

XKMSException - if something goes wrong.

MessageToString

public String MessageToString(XMessageAbstractType message)
                       throws XKMSException

Converts a message into a String.

Parameters:

message - which should be converted into a String

Returns:

String representative of the XML file

Throws:

XKMSException - if something goes wrong.

MessageToStream

public void MessageToStream(XMessageAbstractType message,
                            OutputStream os)
                     throws XKMSException

Outputs a message to an OutputStream. (e.g. System.out)

Parameters:

message - which should be output to Stream

os - Stream to write result to

Throws:

XKMSException - if something goes wrong.

StringToMessage

public XMessageAbstractType StringToMessage(String message)
                                     throws XKMSException

Converts a String into a Message.

Parameters:

message - String which should be converted into a message

Returns:

the message representative of the XML String

Throws:

XKMSException - if something goes wrong.

StreamToMessage

public XMessageAbstractType StreamToMessage(InputStream stream)
                                     throws XKMSException

Converts an InputStream into a Message.

Parameters:

stream - InputStream which contains the message to read from

Returns:

the message representative of the XML in the Inputstream

Throws:

XKMSException - if something goes wrong.

StreamToDOM

public Document StreamToDOM(InputStream stream)
                     throws XKMSException

Parses XML from InputStream and returns a DOM representation.

Parameters:

stream - InputStream to read from

Returns:

a DOM Document containing the XML read from stream

Throws:

XKMSException - if something goes wrong

StringToDOM

public Document StringToDOM(String string)
                     throws XKMSException

Parses XML from String and returns a DOM representation.

Parameters:

string - String to parse from

Returns:

a DOM Document containing the XML read from String

Throws:

XKMSException - if something goes wrong

DOMToMessage

public abstract XMessageAbstractType DOMToMessage(Element startelement)
                                           throws XKMSException

Converts DOM tree to XKMS message.

Parameters:

startelement - root element of the Message (so if there is only one message in the DOM this is Document.getDocumentElement()).

Throws:

XKMSException - if something goes wrong.

MessageToDOM

public abstract Document MessageToDOM(XMessageAbstractType message)
                               throws XKMSException

Converts XKMS message to DOM tree.

Parameters:

message - message to convert

Returns:

DOM representation of message

Throws:

XKMSException - if something goes wrong.

createLocateRequest

public abstract LocateRequest createLocateRequest()

Creates a new LocateRequest, which is empty, except for a randomly generated ID.

Returns:

a new LocateRequest

createValidateRequest

public abstract ValidateRequest createValidateRequest()

Creates a new ValidateRequest, which is empty, except for a randomly generated ID.

Returns:

a new ValidatRequest

createRegisterRequest

public abstract RegisterRequest createRegisterRequest()

Creates a new RegisterRequest, which is empty, except for a randomly generated ID.

Returns:

a new RegisterRequest

createReissueRequest

public abstract ReissueRequest createReissueRequest()

Creates a new ReissueRequest, which is empty, except for a randomly generated ID.

Returns:

a new ReissueRequest

createRecoverRequest

public abstract RecoverRequest createRecoverRequest()

Creates a new RecoverRequest, which is empty, except for a randomly generated ID.

Returns:

a new RecoverRequest

createRevokeRequest

public abstract RevokeRequest createRevokeRequest()

Creates a new RevokeRequest, which is empty, except for a randomly generated ID.

Returns:

a new RevokeRequest

createStatusRequest

public abstract StatusRequest createStatusRequest()

Creates a new StatusRequest, which is empty, except for a randomly generated ID.

Returns:

a new StatusRequest

createPendingRequest

public abstract PendingRequest createPendingRequest()

Creates a new PendingRequest, which is empty, except for a randomly generated ID.

Returns:

a new PendingRequest

createCompoundRequest

public abstract CompoundRequest createCompoundRequest()

Creates a new CompoundRequest, which is empty, except for a randomly generated ID.

Returns:

a new CompoundRequest

createCompoundResult

public abstract CompoundResult createCompoundResult(XRequestAbstractType request)

Creates a new CompoundResult. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createStatusResult

public abstract StatusResult createStatusResult(XRequestAbstractType request)

Creates a new StatusResult. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createResult

public abstract Result createResult(XRequestAbstractType request)

Creates a new Result. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createLocateResult

public abstract LocateResult createLocateResult(XRequestAbstractType request)

Creates a new LocateResult. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createValidateResult

public abstract ValidateResult createValidateResult(XRequestAbstractType request)

Creates a new ValidateResult. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createReissueResult

public abstract ReissueResult createReissueResult(XRequestAbstractType request)

Creates a new ReissueResult. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createRevokeResult

public abstract RevokeResult createRevokeResult(XRequestAbstractType request)

Creates a new RevokeResult. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createRecoverResult

public abstract RecoverResult createRecoverResult(XRequestAbstractType request)

Creates a new RecoverResult. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createRegisterResult

public abstract RegisterResult createRegisterResult(XRequestAbstractType request)

Creates a new RegisterResult. A random ID will be automatically created and set. Furthermore, if the request parameter is not null then also the data of the request will be transferred, if applicable.

Parameters:

request - request to get data from or null

Returns:

a result message with data set according to description above

createAuthentication

public abstract Authentication createAuthentication()

Creates a new Authentication object.

Returns:

a new (empty) Authentication object.

createUnverifiedKeyBinding

public abstract UnverifiedKeyBinding createUnverifiedKeyBinding()

Creates a new UnverifiedKeyBinding object.

Returns:

a new (empty) UnverifiedKeyBinding object.

createKeyBinding

public abstract KeyBinding createKeyBinding()

Creates a new KeyBinding object.

Returns:

a new (empty) KeyBinding object.

createPrototypeKeyBinding

public abstract PrototypeKeyBinding createPrototypeKeyBinding()

Creates a new PrototypeKeyBinding object.

Returns:

a new (empty) PrototypeKeyBinding object.

createQueryKeyBinding

public abstract QueryKeyBinding createQueryKeyBinding()

Creates a new QueryKeyBinding object.

Returns:

a new (empty) QueryKeyBinding object.

createRevokeKeyBinding

public abstract RevokeKeyBinding createRevokeKeyBinding()

Creates a new RevokeKeyBinding object.

Returns:

a new (empty) RevokeKeyBinding object.

createRecoverKeyBinding

public abstract RecoverKeyBinding createRecoverKeyBinding()

Creates a new RecoverKeyBinding object.

Returns:

a new (empty) RecoverKeyBinding object.

createReissueKeyBinding

public abstract ReissueKeyBinding createReissueKeyBinding()

Creates a new ReissueKeyBinding object.

Returns:

a new (empty) ReissueKeyBinding object.

createXPrivateKey

public abstract XPrivateKey createXPrivateKey()

Creates a new XPrivateKey object.

Returns:

a new (empty) XPrivateKey object.

createKeyInfo

public KeyInfo createKeyInfo()

Creates a new (empty) KeyInfo object.

Returns:

a new (empty) KeyInfo object.

validateProofOfPossessionSignature

public abstract boolean validateProofOfPossessionSignature(XKRSSRequest message,
                                                           Key key)
                                                    throws XKMSException

Validates ProofOfPossession signature with the supplied key.

Before calling this validate method, ensure by calling message.hasProofOfPossessionSignature() that the message contains a PoP signature at all, otherwise result of this call is undefined.

Parameters:

message - request message containing a PoP signature

key - key to use for validation

Returns:

true if the ProofOfPossession signature validates, false otherwise

Throws:

XKMSException - if supplied message is not a RegisterRequest or ReissueRequest (the only messages capable of carrying a ProofOfPossession signature)

validateKeyBindingAuthenticationSignature

public abstract boolean validateKeyBindingAuthenticationSignature(XKRSSRequest message,
                                                                  Key key)
                                                           throws XKMSException

Validates KeyBindingAuthentication signature with the supplied key.

Before calling this validate method, ensure by calling message.hasKeyBindingAuthenticationSignature() that the message contains a KeyBinding Authentication signature at all, otherwise result of this call is undefined.

Parameters:

message - request message containing a KBauth signature

key - key to use for validation

Returns:

true if the KeyBindingAuthentication signature is valid, false otherwise

Throws:

XKMSException - if supplied message is not a RegisterRequest, ReissueRequest, RevokeRequest or RecoverRequest (the only messages capable of carrying a KBauth signature)

validateSignature

public abstract boolean validateSignature(XMessageAbstractType message,
                                          Key key)

Validates global message signature with supplied public key.

Before calling this validate method, ensure by calling message.hasSignature() that the message contains a global signature at all, otherwise result of this call is undefined.

Parameters:

key - the key to be used for signature verification

Returns:

true if, and only if the signature is valid.

decryptPrivateKeyBlock

public abstract XPrivateKey decryptPrivateKeyBlock(XKRSSResult message,
                                                   Key key)
                                            throws XKMSException

Decrypts and returns the encrypted private key of this result message.

The supplied key will be used to perform decryption.

Before calling this decrypt method, ensure by calling message.hasPrivateKeyBlock() that the message contains an encrypted PrivateKey block at all, otherwise result of this call is undefined.

Parameters:

message - result message containing an encrypted PrivateKey block.

key - key to use for decryption

Returns:

decrypted PrivateKey

Throws:

XKMSException - if supplied message is not a RegisterResult, or RecoverResult (the only messages capable of carrying an encrypted PrivateKey). Also, if a null key is supplied.

getMessageCertificate

public X509Certificate getMessageCertificate()

Gets the default certificate of newly created messages.

Returns:

the certificate or null.

getMessagePrivateKey

public PrivateKey getMessagePrivateKey()

Gets the default signature private key of newly created messages.

Returns:

the private key or null.

setMessageCredentials

public void setMessageCredentials(X509Certificate cert,
                                  PrivateKey privkey)

Set default credentials to use for global message signature. All messages created by a context instance are preset with this credentials. If private key is not null the message will be signed with supplied private key. If additionally the certificate is not null, it will be included in the signature, too.

Parameters:

privkey - private key which will be used to sign every message

cert - certificate containing public key corresponding to private key

getServiceURI

public String getServiceURI()

Get default ServiceURI of messages.

Returns:

serviceURI String

setServiceURI

public void setServiceURI(String servicename)

Sets default ServiceURI of messages. Sets a default value for the Service URI of newly created messages. On null no default is set.

Parameters:

servicename - the URI of the service

getNonceLength

public int getNonceLength()

Gets default number of characters for generated message nonce.

Returns:

number of chars of nonce

setNonceLength

public void setNonceLength(int length)
                    throws BadParameterException

Sets default number of characters for generated message nonce.

Parameters:

length - number of characters of nonce

Throws:

BadParameterException - if less than 32 specified, which is the minimum for security reasons

setRandomNonce

public void setRandomNonce(XMessageAbstractType message)

Sets the Nonce of a message to a random value.

Parameters:

message - message to set Nonce in

getIdLength

public int getIdLength()

Gets default number of characters for generated message Id.

Returns:

number of chars of Id

setIdLength

public void setIdLength(int length)
                 throws BadParameterException

Sets default number of characters for generated message Id.

Parameters:

length - number of chars of Id

Throws:

BadParameterException - if less than 32 specified, which is the minimum entropy for security reasons

setRandomId

public void setRandomId(XMessageAbstractType message)

Sets the Id attribute of a message to a random value.

Parameters:

message - message to set Id in