Caché Security Administration Guide
The InterSystems Public Key Infrastructure
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter covers the following topics:

About the InterSystems Public Key Infrastructure (PKI)
A Public Key Infrastructure (PKI) provides a means of creating and managing private keys, public keys, and certificates. These are used for cryptographic operations including encryption, decryption, and digital signing and signature verification. Certificates provide a means of associating a public key with an identity. To do this, a PKI includes a trusted third party known as a certificate authority (CA).
The InterSystems PKI implementation gives Caché the ability to serve as a Certificate Authority (CA). An instance of Caché acting as a CA is known as a CA server; an instance of Caché using a CA’s services is known as a CA client. A single instance of Caché can be both a CA server and a CA client. As a CA server, an instance can either generate and use a self-signed CA Certificate, or it can use a CA Certificate issued by a commercial third party or product. As a CA client, an instance is associated with a CA server; the CA client’s certificate is available for use with SSL/TLS, XML encryption, and signature verification; there is also the option of configuring a CA client to serve as an intermediate CA. Communications involving the PKI occur through web services.
When establishing itself as a CA server, an instance of Caché either creates a public/private key pair and then embeds the public key in a self-signed X.509 certificate or it uses a private key and X.509 certificate signed by an outside CA. X.509 is an industry-standard certificate structure that associates a public key with both identifying information for an entity and other related data; this identifying information is known as a subject Distinguished Name (DN), and consists of various specific information regarding an entity’s organization, location, or both. You can use X.509 certificates to provide a high level of public-key–based security if, and only if, appropriate security policies regarding the protection of private keys and the issuance of certificates are enforced, including strict control of the CA server’s private key file, preferably stored on removable media which can be physically secured when not in use.
To use the Caché PKI infrastructure from the Management Portal, all actions start from the Public Key Infrastructure page (System Administration > Security > Public Key Infrastructure).
For more background on PKI and CAs, see the appendix, About Public Key Infrastructure (PKI).” For technical details about the SSL/TLS calls underlying the InterSystems PKI, see the OpenSSL library. For technical details about X.509 certificates, see RFC 5280, “Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.”
Help for Management Portal PKI Tasks
The following are links to help for PKI tasks:
Certificate Authority Server Tasks
A Caché instance can serve as a certificate authority (CA) server. This involves:
  1. Configuring a Caché instance as a CA server. This involves providing information that is either related to the certificate or that the CA server uses for processing certificate signing requests.
  2. Managing pending certificate signing requests (CSRs). This is the ongoing work of a CA server.
Note:
Because these tasks are for the CA server administrator, this section is addressed to those administrators. This differs from the tasks in the CA client tasks, which are addressed to CA client administrators/technical contacts.
Configuring a Caché Instance as a Certificate Authority Server
Before any PKI operations are possible, you need to configure a Caché instance as a Certificate Authority (CA) server. This involves either:
It may also involve reinitializing a CA server.
Configuring a CA Server with a New Private Key and Certificate
If you are creating a new private key and certificate, the procedure is:
  1. For the selected Caché instance, in the Management Portal, go to the Public Key Infrastructure page (System Administration > Security > Public Key Infrastructure).
  2. On the Public Key Infrastructure page, under Certificate Authority Server, select Configure Local Certificate Authority server. This displays fields for (1) the file name root for the CA server’s certificate and private key and (2) the directory that holds these files.
    Important:
    If you specify a path and file name root that point to an existing certificate and private key, Caché uses these for the CA server. Otherwise, it creates a new certificate and private key. (Also, if only one of the files exists, Caché renames it by appending the .old suffix to it and creates new files.)
    The fields are:
  3. Click Next to continue.
  4. The fields that appear next depend on whether you are creating a new private key and certificate pair or using an existing private key and certificate. When you are creating a new private key and certificate, Caché displays the following fields:
  5. Complete these fields as required and click Save. Caché displays a message indicating success, such as:
    Certificate Authority server successfully configured. 
    Created new files: C:\pki\FileNameRoot.cer .key, and .srl. 
    Certificate Authority Certificate SHA-1 fingerprint: 
    E3:FB:30:09:53:90:9A:31:30:D3:F0:07:8F:64:65:CD:11:0A:1A:A2 
    Confirmation email sent to: CAserver-admin@intersystems.com
    This indicates that a private key, certificate, and their associated SRL (serial) file have been created. (Otherwise, Caché displays an error message.)
    Once the files have been created, it is strongly recommended that you store this sensitive information on encrypted, removable media that can be physically secured.
    Warning:
    It is critical that you properly protect all private keys, and most important that you protect the private key of a CA. The exposure of a private key can result in security breaches, data exposure, financial losses, and legal vulnerability.
    If it has succeeded, Caché has performed the following actions:
Once you have created the CA private key and certificate, you can process certificate signing requests (CSRs). When a CA client creates a CSR, you, as CA administrator, will receive email notification about this.
Configuring a CA Server with an Existing Private Key and Certificate
If you are using an existing private key and certificate (such as from another Caché CA, or from an external CA, such as a commercial CA), the procedure is:
  1. Create or obtain a private key and certificate. The certificate must be in PEM format, or you must be able to convert it to PEM format.
  2. If they do not already have identical file name roots, rename them as filenameroot.cer for the certificate and filenameroot.key for the private key, where filenameroot is the file name root you wish to use.
  3. Store both files in the same directory, making sure that this directory is accessible to the Caché instance that you are configuring as a CA server. This directory should always be on an external device (not a local hard drive or a network server), preferably on an encrypted external device. As this is the directory that holds the CA’s private key, it is extremely important that this be a completely secure location.
    Warning:
    It is critical that you properly protect all private keys, and most important that you protect the private key of a CA. The exposure of a private key can result in security breaches, data exposure, financial losses, and legal vulnerability.
  4. For the selected Caché instance, in the Management Portal, go to the Public Key Infrastructure page (System Administration > Security > Public Key Infrastructure).
  5. On the Public Key Infrastructure page, under Certificate Authority Server, select Configure Local Certificate Authority server. Complete the fields on this page as follows:
  6. Click Next to continue.
  7. The fields that appear next depend on whether you are creating a new private key and certificate pair or using an existing private key and certificate. When you are using an existing private key and certificate, Caché displays the following fields:
    Important:
    If the Management Portal displays more fields than these, then you have not properly directed it to the private key and certificate that you wish to use. If you complete all the displayed fields, click Save, and there is success, Caché will have created a new private key and certificate for the CA server.
  8. Click Save. When you save the configuration information for the local CA server, Caché uses the existing certificate and private key. (It will also create an SRL file, if one does not exist.) It will display a success message such as:
    Certificate Authority server successfully configured. 
    Using existing files: C:\pki\FileNameRoot.cer and .key 
    Certificate Authority Certificate SHA-1 fingerprint: 
    E3:FB:30:09:53:90:9A:31:30:D3:F0:07:8F:64:65:CD:11:0A:1A:A2 
    Confirmation email sent to: CAserver-admin@intersystems.com
As with creating a new private key and certificate, at this point, the CA server is configured and is now ready to process certificate signing requests (CSRs). Again, when a CA client creates a CSR, you, as CA administrator, will receive email notification about this.
Reinitializing a CA Server
If you have already configured an instance as a CA server, then there is a Reinitialize button on the page for configuring a CA. Selecting it has the following effects:
Note:
Reinitialization does not delete the files containing the private key or existing certificate for the CA, nor does it delete the CA’s existing SRL file; in fact, these are still valid and can be used. Also, it does not render any already signed certificates invalid.
When you click the button, there is a prompt to confirm that you want to reinitialize the CA. After reinitialization, you can configure a new CA server.
Managing Pending Certificate Signing Requests
Once the Certificate Authority (CA) server has been configured, the principal task associated with the CA server is managing certificate signing requests (CSRs) from potential CA clients. This can involve:
If processing leads to approving the request, the CA server issues an X.509 certificate signed with the CA’s private key, and sends email notification of the issued certificate’s serial number to the CA client’s technical contact. It is also possible to delete (that is, reject) a request.
A critical step in this process is verification, in which the CA administrator uses communications that prevent impersonation to verify the identity of the requester, the authority of the technical contact to hold a certificate with the requested DN, and the purpose for which the certificate is being issued. (To do this, the CA server’s administrator uses the contact information received from the potential CA client along with the CSR.)
Processing a Certificate Signing Request (CSR)
To process a request is to convert the CSR into a certificate. The procedure is:
  1. In the Management Portal, go to the Public Key Infrastructure page (System Administration > Security > Public Key Infrastructure).
  2. On the Public Key Infrastructure page, under Certificate Authority Server, select Process pending Certificate Signing Requests. This displays a table of CSRs that the CA has received and not processed or deleted; to the right of each CSR there are Process and Delete links.
  3. Mount the media containing the CA server certificate and private key files. (This is the media on which you stored these files while configuring a Caché instance as a CA server.)
  4. To process a CSR, click Process. This displays the contents of the CSR.
  5. Prior to issuing the certificate, you need to specify the use of the certificate. The choices for the Certificate Usage radio buttons specify which operations the certificate can perform:
  6. Important:
    This step requires that you verify the identity of the technical contact for the potential CA client using a means that prevents impersonation.
    As the instructions on this page specify, you must contact the designated technical contact for the instance that has submitted the CSR. According to the policies of your organization, contact this person by phone or in person and verify:
  7. Once you have specified the purpose of the certificate and verified the relevant information with the technical contact, you can issue the certificate. To do this, click Issue Certificate. This causes the page to display the Password for Certificate Authority's Private Key file field.
  8. In the Password for Certificate Authority's Private Key file field, enter the password to decrypt the CA server’s private key file. If you created the private key and certificate with Caché, this is the value you entered in the Password to Certificate Authority's Private Key file field; if you created the private key and certificate using other tools, it is the password, if any, that you provided to those tools for this purpose.
  9. Click Finish to create the certificate. If successful, Caché displays a message such as
    Certificate number 31 issued for Certificate Signing Request 
    "Santiago Development Group"
  10. Remove the media holding the CA server’s certificate and private key, and store it in a secure location.
Caché has now created the certificate and notified the technical contact for the CA client by email that the certificate is available for download. The CA client’s technical contact can now download the certificate to the client host.
Deleting a Certificate Signing Request (CSR)
To delete a request, the procedure is:
  1. In the Management Portal, go to the Public Key Infrastructure page (System Administration > Security > Public Key Infrastructure).
  2. On the Public Key Infrastructure page, under Certificate Authority Server, select Process pending Certificate Signing Requests. This displays a table of CSRs that the CA has received and not processed or deleted; to the right of each CSR there are Process and Delete links.
  3. To delete a CSR, click Delete. This displays a confirmation dialog.
  4. In the confirmation dialog, click OK.
  5. Complete these fields as required and click Save.
This deletes the CSR.
Certificate Authority Client Tasks
A certificate authority (CA) client has one-time setup tasks, which are:
  1. Configuring the Caché instance as a CA client. This involves providing location about the CA server to the potential CA client; it also includes providing contact information about the CA client’s technical contact.
  2. Getting a copy of the CA certificate. This allows for verifying other certificates.
After setup tasks, the CA client tasks are:
  1. Submitting a certificate signing request (CSR) to the CA server. From the user’s perspective, this involves specifying a distinguished name (DN) and other information. (This may happen repeatedly, if the instance has reason to have multiple distinct certificates.)
  2. Getting copies of various certificates. In addition to the CA client’s own certificate, this includes any other certificates that the CA server has issued.
After performing these tasks, the CA client can then perform the operations that require use of the PKI. These are tasks in which it is known as an end entity, since it is at the end of a secured connection.
Note:
Because these tasks are for the CA client administrators/technical contacts, this section is addressed to those individuals. This differs from the tasks in the Certificate Authority Server Tasks, which are addressed to CA server administrators.
Configuring a Caché Instance as a Certificate Authority Client
The procedure to configure a Caché instance as a certificate authority (CA) client involves providing location about the CA server to the potential CA client; it also includes providing contact information about the CA client’s technical contact. The steps are:
  1. In the Management Portal, go to the Public Key Infrastructure page (System Administration > Security > Public Key Infrastructure).
  2. Complete these fields as required and click Save.
Caché acknowledges success through a message such as “Certificate Authority client successfully configured.” At this point, the next task is to download the CA server’s certificate.
Submitting a Certificate Signing Request to a Certificate Authority Server
Once an instance of Caché is configured as a certificate authority (CA) client, you can then submit a certificate signing request (CSR) to the CA server. On the surface, this involves specifying a distinguished name (DN) and other information. Under the covers, the CA client performs several actions:
  1. Generating a public/private key pair.
  2. Creating a Certificate Signing Request (CSR) containing the public key and a specified DN.
  3. Submitting that to the CA server using a web service.
The PKI infrastructure automatically provides the CSR to the CA server, acknowledges the submission, and sends email notification to the CA server’s administrator. The submission includes your contact information as the local technical contact for the CA client. The CA administrator then processes the CSR by using communications that prevent impersonation to verify the identity of the requester, the authority of the technical contact to hold a certificate with the requested DN, and the purpose for which the certificate is being issued. If the request is approved, the completion of the process includes the CA server creating a certificate.
To submit a CSR to a CA server, the procedure is:
  1. In the Management Portal, go to the Public Key Infrastructure page (System Administration > Security > Public Key Infrastructure).
  2. Complete these fields as required and click Save. If successful, Caché then displays a message such as:
    SHA-1 Fingerprint: 
    0C:DA:5F:06:04:C7:AE:64:61:9C:5C:29:35:49:88:0D:B6:E5:7D:98, 
    Certificate Signing Request "CAClient060412" 
    successfully submitted to the Certificate Authority at instance MyCA 
    on node CATESTCLIENT.CATESTDOMAIN.COM
    If Caché has successfully created a CSR, it has performed the following actions:
    (If the process does not succeed, Caché displays an error message.)
    Once the files have been created, it is strongly recommended that you store this sensitive information on encrypted, removable media that can be physically secured.
  3. Make a copy of the SHA-1 fingerprint that Caché displays.
    Important:
    Do not lose this information, as you will need to provide this later, as part of the verification process.
  4. At this point, you have used Caché to create and submit the CSR. When the administrator of the CA contacts you, provide the SHA-1 fingerprint that you copied in the last step. The administrator will then create certificate for you, which you can obtain as described in Get Certificate(s) from Certificate Authority Server.”
Getting Certificate(s) from Certificate Authority Server
Once a certificate authority (CA) client has been configured, it can then download any certificate associated with the CA server. This includes:
The procedure to obtain certificates is:
  1. In the Management Portal, go to the Public Key Infrastructure page (System Administration > Security > Public Key Infrastructure).
  2. On the Public Key Infrastructure page, under Certificate Authority Client, select Get Certificate(s) from Certificate Authority server. This displays a list of available certificates to download, as well as a button that displays certificates issued for the current instance (whether downloaded or not). Ordinarily, you need both the CA server certificate as well as your own. There are several tasks you can perform from this page:
  3. When you click Get to download a certificate, Caché displays a confirmation message, such as
    Certificate number 74 (SHA-1 Fingerprint: 
    45:E8:DE:0C:15:BF:A7:89:58:04:5E:68:2E:4D:BB:01:F5:90:94:97) 
    saved in file "c:\intersystems\myinstance\mgr\IstanbulAcctsPayable.cer"
While Caché initially downloads certificates to the manager’s directory, once they are on the client host, you can move them anywhere.