Setup and Other Common Activities
For reference, this topic describes common activities that apply to securing web services.
Performing Setup Tasks
For most of the tasks related to SOAP security, you must first do the following tasks:
These tasks are also prerequisites for some tasks described in Using XML Tools.
You might also need to create SSL/TLS configurations. For information, see InterSystems TLS Guide.
Providing Trusted Certificates for InterSystems IRIS to Use
InterSystems IRIS 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 InterSystems IRIS installation. To create this collection, create the following two files and place them in the system manager’s directory:
-
iris.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 InterSystems IRIS.
-
iris.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 InterSystems IRIS credential sets; see the next subsection.
Information on creating these files is beyond the scope of this documentation. For information on X.509, which specifies the content of certificates and certificate revocation lists, see RFC5280 (https://www.ietf.org/rfc/rfc5280.txtOpens in a new tab). For information on PEM-encoding, which is a file format, see RFC1421 (https://www.ietf.org/rfc/rfc1421.txtOpens in a new tab).
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 InterSystems IRIS Credential Sets
This section describes how to create and edit InterSystems IRIS 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 InterSystems IRIS Credential Sets
To create an InterSystems IRIS credential set:
-
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.
-
-
In the Management Portal, select System Administration > Security > X.509 Credentials.
-
Click Create New Credentials.
-
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, InterSystems IRIS uses this trusted certificate rather than iris.cer, discussed earlier. 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, InterSystems IRIS does not look up the credential set. InterSystems IRIS instead uses the trusted certificate contained in iris.cer.
-
Authorized user(s) — Specify a comma-separated list of InterSystems IRIS 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.
-
-
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.X509CredentialsOpens in a new tab 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 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.X509CredentialsOpens in a new tab.
Editing InterSystems IRIS Credential Sets
Once you have created an InterSystems IRIS credential set, you can edit it as follows:
-
In the Management Portal, select System Administration > Security > X.509 Credentials.
-
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.
-
Make edits as needed. See the previous section for information on these fields.
-
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 an InterSystems IRIS credential set.
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.X509CredentialsOpens in a new tab, call the GetByAlias() class method. This method returns an InterSystems IRIS credential set that contains a certificate and other information. For example:
set credset=##class(%SYS.X509Credentials).GetByAlias(alias,password)
-
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.X509CredentialsOpens in a new tab 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 InterSystems IRIS credential set by using other class methods such as FindByField(), GetBySubjectKeyIdentifier(), and GetByThumbprint(). See the class documentation for %SYS.X509CredentialsOpens in a new tab. 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.X509CredentialsOpens in a new tab. You can retrieve that certificate. To do so:
-
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.HeaderOpens in a new tab.
-
Then do one of the following:
-
Access the Signature property of the %SOAP.Security.HeaderOpens in a new tab instance, which references the first <Signature> element in the security header element.
-
Access the first <Signature> element of the %SOAP.Security.HeaderOpens in a new tab instance by using the FindElement() method of the %SOAP.Security.HeaderOpens in a new tab instance.
In either case, the result is an instance of %XML.Security.SignatureOpens in a new tab that contains the digital signature.
-
-
Access the X509Credentials property of the signature object.
-
Check the type of the returned object to see if it is an instance of %SYS.X509CredentialsOpens in a new tab.
if $CLASSNAME(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.X509CredentialsOpens in a new tab instance.
For example:
set credset=..SecurityIn.Signature.X509Credentials
if $CLASSNAME(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 InterSystems IRIS SSL/TLS configuration.
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.