Skip to main content

Creating and Editing InterSystems IRIS Credential Sets

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:

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

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

  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.


Previous sectionProviding Trusted Certificates for InterSystems IRIS to Use
FeedbackOpens in a new tab