Skip to main content
Previous sectionNext section

Setup and Other Common Activities

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:

  • cache.cer — This contains root certificates, that is, trusted CA X.509 certificates in PEM-encoded format. This file is required if you want to use any WS-Policy or WS-Security features in Caché.

  • cache.crl — This contains X.509 certificate revocation lists in PEM-encoded format. This file is optional.

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 (http://www.rfc-archive.org/getrfc.php?rfc=5280). For information on PEM-encoding, which is a file format, see RFC1421 (https://www.ietf.org/rfc/rfc1421.txt).

Caution:

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:

  • You own the certificate. In this case, you also have the private key. You use this certificate at the following times:

    • When you sign outbound messages (if you also load the private key file).

    • When you decrypt messages that were encrypted with your public key.

  • You do not own the certificate. In this case, you obtained it from its owner and you do not have the private key file. You use this certificate at the following times:

    • When you encrypt messages that you send to the owner of the certificate.

    • When you validate digital signatures created by the owner of the certificate.

Creating Caché Credential Sets

To create a Caché credential set:

  1. Obtain the following files:

    • A personal X.509 certificate, in PEM-encoded X.509 format.

      This could be either your own certificate or can be a certificate obtained from an entity with which you expect to exchange SOAP messages.

    • (Optional) An associated private key, in PEM-encoded PKCS#1 format.

      This is applicable only if you own the certificate. If you do not want to sign outbound messages, you do not need to load the private key file.

    • (Optional) A file containing root certificates, that is, trusted CA X.509 certificates in PEM-encoded format, for use with this credential set.

    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. Click Create New Credentials.

  4. Specify the following values:

    • Alias — Specify a unique, case-sensitive string that identifies this credential set. This property is required.

    • File containing X.509 certificate — Click Browse ... and navigate to the certificate file. This property is required.

    • File containing associated private key — Click Browse ... and navigate to the file.

    • Private key password and Private key password (confirm) — Specify the password for the private key. If you do not specify the password, you will have to provide the password instead when you retrieve the credential set.

      These fields are displayed only if you specify a value for File containing associated private key.

    • File containing trusted Certificate Authority X.509 certificate(s) — The path and filename of the X.509 certificates of any CAs trusted by this credential set. The certificates must be in PEM format. The path can be specified as either an absolute path or a path relative to the manager’s directory.

      With one exception, when you use this credential set, Caché uses this trusted certificate rather than cache.cer, discussed earlier in this chapter. The exception is when a digital signature contains a direct reference to a binary security token in the message; in this case, because the message contains the public key needed to verify the signature, Caché does not look up the credential set. Caché instead uses the trusted certificate contained in cache.cer.

    • Authorized user(s) — Specify a comma-separated list of Caché users who can use this credential set. If this property is null, any user can use this credential set.

    • Intended peer(s) — Specify a comma-separated list of the DNS names of systems where the credential set can be used. Your code must use the CheckPeerName() method of the credentials object to check that a peer is valid for this credential set.

  5. 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)
Copy code to clipboard
Note:

Do not use the normal object and SQL methods for accessing this data. The %Admin_Secure:USE privilege is needed to use the Save(), Delete(), and LoadPrivateKey() 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)
Copy code to clipboard
  • alias is the alias for the certificate.

  • pwd is the private key password; this is applicable only if you own the certificate. You need this only if the associated private key is encrypted and if you did not load the password when you loaded the private key file.

    If you do not own the certificate, you do not have access to the private key in any form.

    If you do not specify the password argument, the %SYS.X509Credentials instance does not have access to the private key and thus can be used only for encryption.

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 $CLASSNAME(credset)'="%SYS.X509Credentials" {set credset=""}
    Copy code to clipboard

    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 $CLASSNAME(credset)'="%SYS.X509Credentials" {set credset=""}
 //if credset is not null, then use it...
Copy code to clipboard

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
Copy code to clipboard

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.