# 15. Web Services

Chapter Contents | Prev | Next
Keyword Search:
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:

- encryption

  The process of making data unreadable using some secret (see 'key')

- decryption

  The opposite of encryption

- signature

  A sequence of binary codes that is calculated based on the original data and a key to secure the content from undetected change.

- key

  A secret, depending on the type can be symmetric or asymmetric.

  Typical symmetric keys are passwords. Symmetric keys are by their nature more at risk of being compromised if the secret key is stolen. Symmetric keys are usually used to encrypt large amounts of data as they are very fast.

  Asymmetric keys are more secure and their structure is more complicated. Asymmetric keys generally consist of a private and public key pair. The owner of the key can sign data to be verified by recipient with public key. A correspondent can encrypt the data using public key to be decrypted by private key owner. Asymmetric keys are used to sign data, or encrypt small amounts of data as they are slower to process than symmetric ones.

- certificate

  This is a structure of secure data, which identifies a certificate owner. This is similar to having a user-name and password but more secure. A 'certificate' can be associated with a document as an alias of the X.509 certificate. Certificates are issued by a third-party, not the owner or recipient in the verification path, namely the Certificate Authority (CA). The CA's function is to guarantee that a receiver can trust data accompanied by a particular certificate. Certificates will contain a public key, but never the private key. These must be distinguished from certificates that are exported together with their private key in PKCS#12 format, these are different things.

- user account space

  This is a data area where a user can store private data. Only ODBC sessions and web page processing code which runs on behalf of a certain SQL user account has access to this area. This is useful for caching private security related information such as keys or certificates.

- key reference

  A short hand for a key, sometime called a 'key name'. This is a string to uniquely identify a key in a user account space.

- key instance

  An entity representing a key in PL, this is a not the key per se. The key instance is used in encryption or decryption routines.

The following algorithms are supported:

- RSA (http://www.w3.org/2001/04/xmlenc#rsa-1_5)
- DSA (http://www.w3.org/2001/04/xmlenc#dsa)
- triple DES (http://www.w3.org/2001/04/xmlenc#tripledes-cbc)
- AES128 (http://www.w3.org/2001/04/xmlenc#aes128-cbc)
- AES192 (http://www.w3.org/2001/04/xmlenc#aes192-cbc)
- AES256 (http://www.w3.org/2001/04/xmlenc#aes256-cbc)

Digest algorithms:

- SHA1 (http://www.w3.org/2000/09/xmldsig#sha1)

Signing algorithms:

- RSA-SHA1 (http://www.w3.org/2000/09/xmldsig#rsa-sha1)
- DSA-SHA1 (http://www.w3.org/2000/09/xmldsig#dsa-sha1)

Canonicalization algorithms with comments:

- (http://www.w3.org/TR/2001/REC-xml-c14n-20010315)
- (http://www.w3.org/TR/2001/REC-xml-c14n)

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:

- WS-SEC

  WS-Security processing is enabled on the endpoint, in practice this enables the input and output message filters for Security Header processing. This MUST be set to enable WS-Security endpoints. All other WS related options will be ignored if this option is disabled. The possible values for this option are "yes" or "no"

- WSS-KEY

  The name of a PL procedure that is expected to return a key instance. Examples of this can be found in the Referencing Keys section. If this NULL or undefined the SOAP server will not encrypt outgoing messages.

- WSS-Template

  path and file name to a file containing a template - an instruction for how to make the XML signature for the response message. For more information see the Security Templates section. If this option is NULL or undefined the SOAP server will not sign any outgoing messages from this endpoint. As an example, if the value "sig.xml" was supplied to this option this would imply that the content of template is stored in the file called sig.xml located in the servers working directory. A default template can be used by setting this option to the value [key reference for signing] - (note '[]' around name is required). In this case the server will generate a default template based on a key, and produce a default rule for making a signature.

- WSS-Validate-Signature

  This option controls how the SOAP server responds to incoming messages i.e. how to verify the incoming message.

  possible values are:

  - 0 do not verify signatures
  - 1 expects signature to exist
  - 2 will verify signature if exists

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:

- wss-token-owner owner of certificate, an example is "C=US/ST=MA/CN=User Name".
- wss-token-issuer issued by , it's like above , but it's name of who is issued the certificate.
- wss-token-serial serial number, an integer specific to certificate issuer.
- wss-token-start valid from, a string containing a data of validity.
- wss-token-end valid to, a string containing data of end of validity.

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()

Previous WSDL | Chapter Contents | Next Web Services Routing Protocol (WS-Routing)