iaik.xkms
Class XKMSContext

Object
  extended by 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