Page edited by Andrei Shakirin

Changes (3)

Full Content

XML Key Management Service (XKMS)

Use case

CXF security uses asymmetric algorithms for different purposes: encryption of symmetric keys and payloads, signing security tokens and messages, proof of possession.
Normally the public keys (in form of X509 certificates) are stored in java keystores.

For example, if sender encrypts the message payload sending to the receiver, he should have access to receiver certificate saved in local keystore.
The sender uses this certificate for message encryption and receiver decrypts request with corresponded own private key:

Seems to be OK? Imagine now that you have production environment with 100 different clients of this service and service certificate is expired. You should reissue and replace certificate in ALL client keystores! Even more, if keystores are packaged into war files or OSGi bundles – they should be unpackaged and updated. Not really acceptable for enterprise environments.

Therefore large service landscapes support central certificates management. It means that X509 certificates are not stored locally in keystores, but are provided and administrated centrally.

Normally it is a responsibility of Public Key Infrastructure (PKI) established in organization. PKI is responsible to create, manage, store, distribute, synchronize and revoke public certificates and certification authorities (CAs).

XKMS Specification

W3C specifies protocol to distribute and register public keys, certificates and CAs that can be used for XML-based cryptography, including signature and encryption: XML Key Management Specification (XKMS 2.0).
The XKMS Specification comprises two parts – the XML Key Information Service Specification (XKISS) describing the runtime aspects of key lookup and certificate validation and the XML Key Registration Service Specification (XKRSS) describing the administrative aspects of registering, renewing, revoking and recovering certificates.
XKMS Service implements both parts of specification.

XKMS SOAP interface can be used as standard frontend to access Public Key Infrastructure (PKI). Using XKMS message encryption scenario message encryption picture will change in following way:

XKMS Design

Internal structure of XKMS service is represented on the following figure:

XKMS Service exposes SOAP interface specified in XKMS 2.0.
XKMS implementation realizes chain of responsibility design pattern chain-of-responsibility .
Each XKMS operation defines handler interface and provides one or more implementations of this interface. Handler implementations are connected into chain.
Operation implementation invokes handlers one after another from pre-configured chain until either all handlers will be processed or critical error will occur.
This design makes XKMS internal implementation quite flexible: it is easy to add/remove handlers, change their order, introduce handlers supporting new backends, etc.
For example certificate can be searched firstly in the LDAP repository by LDAP lookup handler and, if it is not found there, additionally looked in remote PKI using appropriate lookup handler. Logic validation operation is organized in chain is well: first validation handler checks format and expire date of X509 certificate, next one checks certificate trust chain.

Currently XKMS Service supports simple file based and LDAP backends.
Sample spring configuration of XKMS handlers for file backend looks like:

   <bean id="dateValidator" class="org.apache.cxf.xkms.x509.validator.DateValidator" />


   <bean id="x509FileLocator" class="org.apache.cxf.xkms.x509.locator.FileLocator">
      <constructor-arg value="../conf/certs" />
   </bean>

   <bean id="fileRegisterHandler" class="org.apache.cxf.xkms.x509.handlers.FileRegisterHandler">
      <constructor-arg value="../conf/certs" />
   </bean>

   <bean id="xkmsProviderBean" class="org.apache.cxf.xkms.service.XKMSService">
      <property name="validators">
         <list>
            <ref bean="dateValidator" />
         </list>
      </property>
      <property name="locators">
         <list>
            <ref bean="x509FileLocator" />
         </list>
      </property>
      <property name="keyRegisterHandlers">
         <list>
            <ref bean="fileRegisterHandler" />
         </list>
      </property>
   </bean>

   <jaxws:endpoint id="XKMSService" xmlns:serviceNamespace="http://www.w3.org/2002/03/xkms#wsdl"
      serviceName="serviceNamespace:XKMSService" endpointName="serviceNamespace:XKMSPort"
      implementor="#xkmsProviderBean" address="/XKMS">
   </jaxws:endpoint>

Integration XKMS client into CXF security.

XKMS client can be integrated into CXF and WSS4J using custom Crypto provider implementation. In this case XKMS service will be automatically invoked when WSS4J requires or validates certificate. Details are described in this blog.

Data Formats

Input and output data formats are specified in XML Key Management Service Specification Version 2.0 (see XKMS 2.0). Anyway XKMS service supports only subset of specified requests and responses.
Restrictions of formats for request and responses are described in following table:

Element XPath	Supporting values	Description
RootElement/QueryKeyBinding/UseKeyWith@Application	urn:ietf:rfc:2459	Application specifies X509 SubjectDN in Identifier attribute. Used for normal users certificates
RootElement/QueryKeyBinding/UseKeyWith@Application	urn:apache:cxf:service:soap	Application specifies Service Id in Identifier attribute as {SERVICE_ NAMESPACE}SERVICE_NAME. Used for service certificates
RootElement/QueryKeyBinding/UseKeyWith@Identifier	X509 Subject DN or Service name as {SERVICE_ NAMESPACE}SERVICE_NAME	Depending on Application attribute public key is identified as X509 Subject DN or Service nameservice certificates
RootElement/UnverifiedKeyBinding/KeyInfo	X509Data/X509Certificate	Only X509Data with X509Certificate is supported

Error Handling

Success and Fault Response formats are specified in XKMS 2.0. Error conditions in XKMS service are reported using ResultMajor and ResultMinor attributes in root response element.
XKMS Service uses following values for response codes:

ResultMajor

Value	Description
Success	The operation succeeded.
Receiver	An error occurred at the receiver.
Sender	An error occurred that was due to the message sent by the sender.

ResultMinor

Value	Description
Failure	The service attempted to perform the request but the operation failed.
NoMatch	No match was found for the search prototype provided.
TooManyResponses	The request resulted in the number of responses that exceeded limit determined by the service.
TimeInstantNotSupported	The receiver has refused the operation because it does not support the TimeInstant element.

Deployment

XKMS Service can be deployed into web and OSGi containers. Service implementation was tested with Tomcat and Karaf.

h4 Sample Requests and Responses
Sample request for Locate operation:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:LocateRequest xmlns="http://www.w3.org/2000/09/xmldsig#"
            xmlns:ns2="http://www.w3.org/2002/03/xkms#" 
            xmlns:ns3="http://www.w3.org/2001/04/xmlenc#"
            Id="1noOYHt5Lx7xUuizWZLOMw==" Service="http://cxf.apache.org/services/XKMS/">
            <ns2:QueryKeyBinding>
                <ns2:UseKeyWith Application="urn:ietf:rfc:2459"
                    Identifier="[email protected], CN=www.client.com, OU=IT Department, O=Sample Client -- NOT FOR PRODUCTION, L=Niagara Falls, ST=New York, C=US" />
            </ns2:QueryKeyBinding>
        </ns2:LocateRequest>
    </soap:Body>
</soap:Envelope>

Sample response for Locate operation:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:LocateResult ResultMajor="http://www.w3.org/2002/03/xkms#Success"
            RequestId="1noOYHt5Lx7xUuizWZLOMw==" Id="04725751-3d19-4566-87e6-b4f4a2a72606"
            Service="http://cxf.apache.org/services/XKMS/" 
            xmlns:ns2="http://www.w3.org/2002/03/xkms#"
            xmlns:ns3="http://www.w3.org/2001/04/xmlenc#" 
            xmlns:ns4="http://www.w3.org/2000/09/xmldsig#"
            xmlns:ns5="http://www.w3.org/2002/03/xkms#wsdl">
            <ns2:UnverifiedKeyBinding>
                <ns4:KeyInfo>
                    <ns4:X509Data>
                        <ns4:X509Certificate>… </ns4:X509Certificate>
                    </ns4:X509Data>
                </ns4:KeyInfo>
            </ns2:UnverifiedKeyBinding>
        </ns2:LocateResult>
    </soap:Body>
</soap:Envelope>

Sample error message:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:LocateResult ResultMajor="http://www.w3.org/2002/03/xkms#Receiver"
            ResultMinor="http://www.w3.org/2002/03/xkms#Failure"
            RequestId="1noOYHt5Lx7xUuizWZLOMw==" Id="da4f4faf-b2d6-414a-a4cf-b40f464b59a4"
            Service="http://cxf.apache.org/services/XKMS/" 
            xmlns:ns2="http://www.w3.org/2002/03/xkms#"
            xmlns:ns3="http://www.w3.org/2001/04/xmlenc#" 
            xmlns:ns4="http://www.w3.org/2000/09/xmldsig#"
            xmlns:ns5="http://www.w3.org/2002/03/xkms#wsdl">

            <ns2:MessageExtension xsi:type="ns5:resultDetails"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <Details>Search certificates failure: Application
                    identifier not supported</Details>
            </ns2:MessageExtension>
        </ns2:LocateResult>
    </soap:Body>
</soap:Envelope>

Change Notification Preferences

View Online | View Changes | Add Comment

[CONF] Apache CXF Documentation > XML Key Management Service (XKMS)