Securing Caché Web Services
Setup and Other Common Activities
[Back] [Next]
Go to:

For reference, this chapter describes common activities that apply to securing web services. These activities fall into three categories:

Performing Setup Tasks
For most of the tasks in this book, you must first do the following tasks:
These tasks are also prerequisites for some tasks described in Using Caché XML Tools.
You might also need to create SSL/TLS configurations. For information, see the chapter Using SSL/TLS with Caché in the Caché Security Administration Guide.
Providing Trusted Certificates for Caché to Use
Caché uses its own collection of trusted certificates to verify user certificates and signatures in inbound SOAP messages (or in XML documents). It also uses these when encrypting content in outbound SOAP messages or when encrypting XML documents. This collection is available to all namespaces of this Caché installation. To create this collection, create the following two files and place them in the system manager’s directory:
Note that you can have alternative root certificates used with specific Caché credential sets; see the next subsection.
Information on creating these files is beyond the scope of this book. For information on X.509, which specifies the content of certificates and certificate revocation lists, see RFC5280 ( For information on PEM-encoding, which is a file format, see RFC1421 (
Be careful to obtain certificates from a trusted source for any production use, because these certificates are the basis for trusting all other certificates.
This collection is not used for SSL.
Creating and Editing Caché Credential Sets
This section describes how to create and edit Caché credential sets, which are containers for X.509 certificates. There are two general scenarios:
Creating Caché Credential Sets
To create a Caché credential set:
  1. Obtain the following files:
    Information on creating these files is beyond the scope of this documentation.
  2. In the Management Portal, select System Administration > Security > X.509 Credentials.
  3. Specify the following values:
  4. Click Save.
    When you do so, both the certificate file and the private key file (if any) are copied into the database. If you specified File containing trusted Certificate Authority X.509 certificate(s), that file is not copied into the database.
Rather than using the Management Portal, you can use methods of the %SYS.X509Credentials class. For example:
 Set credset=##class(%SYS.X509Credentials).%New()
 Set credset.Alias="MyCred"
 Do credset.LoadCertificate("c:\mycertbase64.cer")
 Do credset.LoadPrivateKey("c:\mycertbase64.key")
 Set sc=credset.Save()
 If sc Do $system.Status.DisplayError(sc)
Do not use the normal Cache object and SQL methods for accessing this data. The %Admin_Secure resource is needed to use the Save() or Delete() methods.
For more details, see the class reference for %SYS.X509Credentials.
Editing Caché Credential Sets
Once you have created a Caché credential set, you can edit it as follows:
  1. In the Management Portal, select System Administration > Security > X.509 Credentials.
  2. In the table of credential sets, the value of the alias column serves as an identifier. For the credential set that you wish to edit, click Edit.
  3. Make edits as needed. See the previous section for information on these fields.
  4. Click Save to save the changes.
It is not possible to change the alias or certificate of a credential set; it is also not possible to add, alter, or remove an associated private key. To make any changes of this kind, create a new credential set.
Retrieving Credential Sets Programmatically
When you perform encryption or signing, you must specify the certificate to use. To do so, you choose a Caché credential set.
When you create a policy via the wizard, you can select the credential set within the wizard, or you can retrieve it programmatically within the web service or client and then use it. When you create WS-Security headers manually, you must retrieve a credential set programmatically and use it.
For reference, this section discusses the following common activities:
Retrieving a Stored Credential Set
To retrieve an instance of %SYS.X509Credentials, call the GetByAlias() class method. This method returns a Caché credential set that contains a certificate and other information. For example:
 set credset=##class(%SYS.X509Credentials).GetByAlias(alias,password)
To run this method, you must be logged in as a user included in the OwnerList for that credential set, or the OwnerList must be null.
If you are going to use the certificate for encryption, you can retrieve the Caché credential set by using other class methods such as FindByField(), GetBySubjectKeyIdentifier(), and GetByThumbprint(). See the class documentation for %SYS.X509Credentials. GetByAlias() is the only method of this class that you can use to retrieve the certificate for signing, because it is the only method that gives you access to the private key.
Retrieving a Certificate from an Inbound Message
If you receive a SOAP message that has been digitally signed, the associated certificate is available within an instance of %SYS.X509Credentials. You can retrieve that certificate. To do so:
  1. First access the WS-Security header element via the SecurityIn property of the web service or web client. This returns an instance of %SOAP.Security.Header.
  2. Then do one of the following:
    In either case, the result is an instance of %XML.Security.Signature that contains the digital signature.
  3. Access the X509Credentials property of the signature object.
  4. Check the type of the returned object to see if it is an instance of %SYS.X509Credentials.
     if $zobjclass(credset)'="%SYS.X509Credentials" {set credset=""}
    If the inbound message contained a signed SAML assertion, the X509Credentials property is an instance of some other class and cannot be used to access a %SYS.X509Credentials instance.
For example:
 set credset=..SecurityIn.Signature.X509Credentials 
 if $zobjclass(credset)'="%SYS.X509Credentials" {set credset=""}
 //if credset is not null, then use it...
Specifying the SSL/TLS Configuration for the Client to Use
If the web service requires use of HTTP over SSL/TLS (HTTPS), the web client must use the appropriate Caché SSL/TLS configuration.
When you create a policy via the wizard, you can select the SSL/TLS configuration within the wizard, or you can programmatically specify the configuration to use within the web service or client. When you create WS-Security headers manually, you must programmatically specify the configuration to use.
To specify the SSL/TLS configuration to use, set the SSLConfiguration property of the web client equal to an SSL/TLS configuration name. For example:
 set client=##class(proxyclient.classname).%New()
 set client.SSLConfiguration="mysslconfig"
 //invoke web method of client
Note that if the client is connecting via a proxy server, you must also set the HttpProxySSLConnect property equal to 1 in the web client.