www.openlinksw.com
docs.openlinksw.com

Book Home

Contents
Preface

Web Services

SOAP
WSDL
WS-Security (WSS) Support in Virtuoso SOAP Server
Client and Server side Certificates & Keys SOAP Server WS-Security Endpoint Virtual Directory SOAP WSS Options Accounting & Accounting Hook Signature Templates SOAP Client
Web Services Routing Protocol (WS-Routing)
Web Services Reliable Messaging Protocol (WS-ReliableMessaging)
Web Services Trust Protocol (WS-Trust)
XML for Analysis Provider
XML-RPC support
SyncML
UDDI
Exposing Persistent Stored Modules as Web Services
Testing Web Published Web Services
BPEL Reference
XSQL

15.3. WS-Security (WSS) Support in Virtuoso SOAP Server

The following terms are used in this section in the following meanings:

The following algorithms are supported:

Digest algorithms:

Signing algorithms:

Canonicalization algorithms with comments:

The keys can be temporary or persistent keys. Temporary keys are loaded only in memory an will be lost when the server is restarted. These are usually used for making symmetric session keys. Persistent keys are kept on the file-system or in the database and will be loaded upon server startup. These are asymmetric keys, certificates that belong to the user.

The location where persistent keys are stored depends on the key reference. If the key reference is a 'file:' URI, then the API's assume file-system storage, otherwise they will be kept in the U_OPT column of the SYS_USERS table as a serialized string. The API functions are described below. Whether keys are stored on the file-system or within the database they will have an in-memory representation which is used in crypto functions. The memory cache of keys is contained in the user account space, hence no user can access or reference another user's keys. Furthermore if a user account is removed all associated keys will also be removed if they were stored in the database. If the keys were on the file-system only the in-memory cache will be deleted.

15.3.1. Client and Server side Certificates & Keys

Since XML encoding routines are executed on server-side, we cannot strictly say that we have client and server certificates (as browser and HTTPS server). To perform the encoding on behalf of a client or user account, the XML encoding functions need to have the keys and certificates loaded in the memory cache of the user. The same applies to server keys and certificates. Therefore we will refer to these as client or server security tokens that are kept on server-side.

Note:

Uploading of keys and certificate must be done under a secure SSL/TLS connection to minimize the risk of vulnerability.

15.3.1.1. Key Definition & Persistence

xenc_key_3DES_rand_create() USER_KEY_LOAD()

15.3.1.2. Key Encryption

To minimize the risk of non-authorized private key usage, keys are usually kept encrypted with password. If a key or certificate containing a key is loaded using a password, the API will assume it is an encrypted private key and will be kept in that form. In other words encrypted keys are kept in their encrypted form in memory, there will be no raw certificate or key data if the encrypted form is used to import. Virtuoso will ask for passwords to unlock persisted encrypted keys upon server restart. This is only possible when the server is running in foreground mode. If the server is started as background process and the key needs a password to decrypt and load, an error will be logged in the virtuoso log file and that particular key will not be loaded.

An example of a password prompt and log on success
Enter a password for key "wss.pfx":
13:14:04 PL LOG: XENC:   Loaded : wss.pfx

15.3.1.3. Referencing Keys

To make a run-time key instance, used for XML encryption functions, and to perform server or client side the xenc_key_inst_create (in key_name varchar[, super key inst]) function can be used.

Example
create procedure
DB.DBA.WSDK_GET_KEY ()
{
  -- this returns a instance of shared secret suitable for content encryption
  return xenc_key_inst_create ('WSDK Sample Symmetric Key');
}
;

create procedure
DB.DBA.WS_SOAP_GET_KEY ()
{
  declare superkey, keyinst any;
  superkey := xenc_key_inst_create ('file:dsa.der'); -- already loaded asymmetric key (see above example)
  -- this returns a session key , to be encrypted with a asymmetric one
  keyinst := xenc_key_inst_create (xenc_key_3DES_rand_create (NULL), superkey);
  return keyinst;
}
;

15.3.1.4. Key Removal

To delete a key, persistent or otherwise, the following function is used:

xenc_key_remove()



15.3.2. SOAP Server WS-Security Endpoint

The WS-Security processing is performed by filtering incoming and outgoing messages of the Virtuoso SOAP server. These filters are activated when a special SOAP option is set on the current virtual directory that is the SOAP endpoint. The WS-Security filters are invoked on input to verify / decrypt the message. Upon success the message will be processed by the SOAP server, otherwise a SOAP:Fault will be returned to the SOAP requester. On outgoing messages, depending of SOAP options, messages produced by the SOAP server can be encoded and signed as well. The administrator configures the WS Security subsystem at the access point level. Different security schemes involving encryption and/or signature can be selected.

The keys and certificates need to be defined in order to get a working secure service. The key/certificate(s) for the SOAP endpoint that is WS-Security enabled are referenced in a special PL hook and/or signature template. If none of these (signature or key instance hook) are defined the response will not be encrypted or signed.

Here are the steps involved in processing a message to a secure end point.

  1. SOAP server receives a message on a secure endpoint

  2. The message is determined to be for this endpoint, otherwise will be sent to the next SOAP router if routing is enabled.

  3. The message (as is) is passed to the decoding routine. At this point keys that are referenced in SOAP message need to be in the user space of the SQL account on whose behalf SOAP accessible procedures of this end point run. If any key does not exist in the user space, the requested processing will fail.

    Note:

    Signatures can be verified in the following manners:

    • never try signatures
    • expect signatures, explicit
    • try signature if exists

    This behavior depends on the "WSS-Validate-Signature" option set for the virtual directory.

  4. If step 3 completes without problem, security related headers are stripped from the decoded message.

  5. The result of point 4 is passed to the usual SOAP server for processing.

  6. Once a response is generated by the SOAP method (i.e. corresponding PL procedure, exposed as SOAP method) the result will be encoded and/or signed. This is the last step before the result is sent back to the requestor client. At this point the server behavior is controlled by a few options defined in the virtual directory. See below: "WSS-KEY", "WSS-Template", and "WSS-Type" options.


15.3.3. Virtual Directory SOAP WSS Options

The following SOAP options are available for configuring a virtual directory:

Configuring WS Secure Endpoints
-- definition of /SecureWebServices endpoint
VHOST_DEFINE (
  lpath=>'/SecureWebServices', ppath=>'/SOAP/', soap_user=>'WSS',
  soap_opts=>vector(
    'Namespace','http://temp.uri/',
    'MethodInSoapAction','yes',
    'ServiceName', 'WSSecure',
    'CR-escape', 'no',
    'WS-SEC','yes',
    'WSS-Validate-Signature', 2)
  )
;

this will define a WS-Security enabled endpoint that is compatible with .NET WSDK examples. This endpoint will accept encrypted/or signed SOAP messages and will generate an error if security checking fails. Upon success it will return non-encrypted message. Therefore it's a one-way encryption example.

-- complex example
VHOST_DEFINE (
  lpath=>'/wss', ppath=>'/SOAP/', soap_user=>'WSS',
  soap_opts=>vector(
    'Namespace','http://soapinterop.org/',
		'MethodInSoapAction','no',
		'ServiceName', 'WSSecure',
		'HeaderNS', 'http://soapinterop.org/echoheader/',
		'CR-escape', 'no',
    'WS-SEC','yes',
		'WSS-KEY','DB.DBA.WS_SOAP_GET_KEY',
		'WSS-Template','wss_tmpl.xml',
    'WSS-Validate-Signature', 1)
  )
;

This endpoint will expect signed and encrypted incoming messages and will sign and encrypt outgoing messages too. This is a two-way encryption example, for client to server and reverse.


15.3.4. Accounting & Accounting Hook

If an X.509 certificate is used to sign an incoming message, the following connection variables will be available to the SOAP processing function and accounting hook:

These can be accessed by invoking connection_get([name-of-info]) when processing the SOAP request, i.e. in the procedure being invoked or from a user defined accounting hook.

A user defined procedure hook named DB.DBA.WS_SOAP_ACCOUNTING can be used for accounting purposes. If it exists it will be invoked after the connection information is set. This PL hook should return 0 when an error occurs or 1 upon success. Hence, a SOAP request may be rejected based on some custom condition.

The procedure prototype is :

create procedure DB.DBA.WS_SOAP_ACCOUNTING ()
{
  -- custom logic
  return 1; -- on success
  return 0; -- on failure
}
;

Note that the usage of this functionality is global to the Virtuoso server, To get similar functionality for each SOAP method, the developer will need to include account checking within the PL procedures that are exposed as SOAP methods.


15.3.5. Signature Templates

Signature templates are used to define how signatures are generated for SOAP messages. They are XML files containing a structure of Signature elements as per XML Signature standard. The DigestValue and SignatureValue elements are empty, so they will be filled upon output. The most important element is the KeyName element. This must contain a reference to an existing key from the user account space. This key reference does not need to be the same as key for datas encryption, it can be a different key. Please note that XML encoding routines will resolve the key automatically, so there is no need to specify how the key instance will be obtained, hence no relation to "WSS-Key" from SOAP options section (above).

15.3.5.1. Default Template Generation

The default template will create an XML Signature using the following definitions:

a) have a simple template corresponding to a key reference (and it's algorithm) as:

TEMP := <?xml version="1.0" encoding="UTF-8"?>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#" >
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
    <SignatureMethod Algorithm="[key algorithm]" />
  </SignedInfo>
  <SignatureValue></SignatureValue>
  <KeyInfo>
    <KeyName>[key reference]</KeyName>
  </KeyInfo>
</Signature>'

b) generate references to template a), using the dsig_template_ext() function and BODY of the SOAP request.

TEMPLATE :=  dsig_template_ext (xtree_doc (SOAP_BODY), TEMP,
      'http://schemas.xmlsoap.org/soap/envelope/', 'Body',
      'http://schemas.xmlsoap.org/rp', 'action',
      'http://schemas.xmlsoap.org/rp', 'to',
      'http://schemas.xmlsoap.org/rp', 'id',
      'http://schemas.xmlsoap.org/ws/2002/07/utility', 'Created',
      'http://schemas.xmlsoap.org/ws/2002/07/utility', 'Expires');

In other words, the 'Body' of the SOAP message, part of the routing header elements ('action,'to','id') and, if it exists, Timestamp headers ('Created', 'Expires').

Using default templates

This example demonstrates the use of the default template mechanism and X.509 certificate with RSA key:

--------------- SOAP message
<SOAP:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
 xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
 xmlns:dt="urn:schemas-microsoft-com:datatypes">
  <SOAP:Header />
  <SOAP:Body Id="Id-2e7c29c7-8645-4ad8-af59-06bed179d2fb">
    <AddInt xmlns="http://microsoft.com/wsdk/samples/SumService">
      <a>3</a>
      <b>4</b>
    </AddInt>
  </SOAP:Body>
</SOAP:Envelope>

--------------- Generated signature template
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
	      xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
	      xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
   <ds:SignedInfo>
      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
      </ds:CanonicalizationMethod>
      <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
      <ds:Reference URI="#Id-2e7c29c7-8645-4ad8-af59-06bed179d2fb">
        <ds:Transforms>
	  <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
	    </ds:Transform>
	  </ds:Transforms>
	<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
	<ds:DigestValue></ds:DigestValue>
      </ds:Reference>
   </ds:SignedInfo>
   <ds:SignatureValue></ds:SignatureValue>
    <ds:KeyInfo>
      <wsse:SecurityTokenReference>
        <wsse:Reference URI="#SecurityToken-24c152e3-26e0-d611-bb59-90b4c67d3be5"></wsse:Reference>
      </wsse:SecurityTokenReference>
    </ds:KeyInfo>
</ds:Signature>

Now, an example of a user defined template:

<?xml version="1.0" encoding="UTF-8"?>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1" />
      <Reference URI="">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <DigestValue></DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue></SignatureValue>
    <KeyInfo>
        <KeyName>file:dsa.der</KeyName>
    </KeyInfo>
</Signature>


15.3.6. SOAP Client

The soap_client() function is used to make soap requests. Upon success it will return an array containing the XML tree of the result. However, it can return more complex results when the debug parameter is enabled, in which case it can return the request and the response messages as well. Some of the parameters are optional, not all are required and they can be named.

See Also:

soap_client()