Tony Beukes · Feb 6, 2018

How does %SYS.LDAP know where to find the x.509 client certificate when using TLS Mutual Authentication from a Caché instance running on MS Windows

Cache for Windows (x86-64) 2015.1 (Build 429U) Fri Feb 13 2015 14:37:23 EST [HealthShare Modules:Core:12.07.3703 + Linkage Engine:13.04.3703]

Use case: Search an LDAP database from Caché over TLS using Mutual Authentication.

Extract from the %SYS.LDAP documentation:

Secure Connections:
For a Windows client, make sure you have the CA certificates already loaded in the Certificates(local computer)\Trusted Root Certification Authorities certificate store. NOTE: If the certificates are stored in the Certificates(current user)\Trusted Root Certification Authorities certificate store, then the SSL connection may fail with Error code 81 if the process is running in the background. For a Unix client, make sure the protections on the certificate file allow your process to be able to read it, and that any additional certificate or LDAP options are specified in the ldap.conf file.
To create a secure SSL connection to an LDAP server, here are the calls you need to make for each platform type."

1) Windows Client to Windows Active Directory LDAP server.
Using the StartTLSs call
s LD=##Class(%SYS.LDAP).Init("",389)
s Status=##Class(%SYS.LDAP).StartTLSs(LD)


Using a direct connection to the LDAP SSL port.
s LD=##Class(%SYS.LDAP).Init("",636)"


Does %SYS.LDAP support TLS Mutual Authentication on Windows?

Assuming TLS Mutual Authentication is supported on Windows:

The documentation states that the CA certificates need to be loaded in the Certificates(local computer)\Trusted Root Certification Authorities certificate store.  What about the client certificates? 

On Unix and VMS  %SYS.LDAP:SetOption() provides for setting the location of an x.509 client certificate and private key. 

 On Windows, how does %SYS.LDAP know where to find the x.509 client certificates?

And how does it differentiate between multiple x.509 client certificates?

0 622
Discussion (3)0
Log in or sign up to continue

This is an interesting question which I don't think I've seen anyone think about before. 

If this works, I would expect it to use a client certificate in the Windows certificate store.  However, I'm not sure that it would work, or what it would do if there were two client certificates.  

If you want a clear answer on this, you might want to open a WRC case.

I had the same question, and after doing some further reading, I believe that the certificate that the client sends to the server depend on the list of the “Acceptable client certificate CA names” that the server presents to the client. This list is part of the “Client Certificate Request Message” that the server sends to the client during the SSL handshake.

So it looks like that the client is using this information to search for the appropriate certificates in the windows certificate store.

You can read here about the Client Certificate Request Message:

(Optional) Client Certificate Request Message

The server must always present its certificates to the client, but the client is not always required to authenticate itself. Therefore, the client is not always required to send its certificates to the server. If the server does not require client authentication, then this message is not sent.

This step might be used for Web sites such as a banking Web site, where the server must confirm the identity of the client before providing sensitive information. If the application requires mutual authentication, the server sends a Client Certificate Request. The Client Certificate Request message includes:

  • The type of certificate required (typically RSA or DSS)
  • A list of acceptable CAs

 If I try to connect to the LDAPs server using OpenSSL:

Openssl s_client -connect –state

then I can see  the “Acceptable client certificate CA names”

I hope it helps


For client certs to be sent to the LDAP server one needs to wrap a given cert and its associated private key into a PKCS
#12 file and import that into the Personal Certificates certificate store.  This can be done with the OpenSSL pkcs12 command.  Below is a document I on  how to perform this process:

Importing Certificates to a Windows Certificate Store

  1. Convert the certificate from PEM format to PKCS#12 format.

e.g. C:\demoCA\newcerts>openssl pkcs12 -export -in newcert.pem -inkey "..\newkey.pem" -out newcert.pfx -name "New Certificate"

Loading 'screen' into random state - done

Enter pass phrase for ..\newkey.pem: <hidden>

Enter Export Password: <hidden>

Verifying - Enter Export Password: <hidden>


  1. Add the Certificates Snap-in to the Microsoft Management Console
    1. Start->Run->”mmc”
    2. File->Add/Remove Snap-in
    3. Add…->Certificates->Add
    4. For client and client-side CA certificates select ‘My user account’; for server and server-side CA certificates select ‘Computer account’->’Local computer’.  Finish.
    5. Close->OK
  1. Import the certificates to the appropriate store
  1. For client certificates, navigate to ‘Certificates – Current User’->’Personal’->’Certificates’
  2. Right-click to select All Tasks->Import
  3. Specify the certificate, enter the private key password (the “export password” from step 1 above) if applicable and specify ‘Personal’ as the certificate store.
  4. For client-side CA certificates navigate to ‘Certificates – Current User’->’Trusted Root Certification Authorities’->’Certificates’ and repeat steps b and c.
  5. For server certificates navigate to ‘Certificates (Local Computer)’->’Personal’->’Certificates’ and repeat steps b and c.
  6. For server-side CA certificates navigate to ‘Certificates (Local Computer)’->’Trusted Root Certification Authorities’->’Certificates’ and repeat steps b and c.