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

Performing Setup Tasks