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] Note:

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

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.

Example 17.25. 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

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 17.26. 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;
}
;

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

xenc_key_remove()