Database Administrator's Guide

ADO.NET Support for TLS

In V11.5 and later, the FairCom DB ADO.NET provider supports TLS/SSL connections per Microsoft specifications.

The ADO.NET provider uses the local certificate store to locate certificates when using peerAuthentication. The server's CA (or a self-signed) certificate ctsrvr.pem must be added to the trusted root certificate store on the client machine for the .NET framework's certificate authentication to succeed:

CertMgr.exe /add ctsrvr.pem /c /s /r localMachine root

Note that the Common Name specified in the server certificate is the name that the application must specify in the ADO.NET connection string for the TLS option.

For this certificate, we used support.faircom.com as the Common Name, and so the ADO.NET connection string must specify sslcert=support.faircom.com for the TLS authentication to succeed.

If client certificate authentication is desired (V13.1 and later), a certificate chain and private key for the client must first be added to the current user's personal certificate store. This can be done using a PKCS #12 file containing the desired certificate chain and private key.

Connection String

The ADO.NET connection string is similar to the JDBC string. The connection string accepts a new property:

ssl=<value>

which can have two values:

• basic - Basic SSL setting, no peer certificate authentication, only communication encryption as requested by server certificate
• peerAuthentication - Server certificate authentication.

In the case of peerAuthentication the server certificate Common Name must be provided by the new property:

sslcert=<value>

If this property is not specified, the value of the Server setting is used to match the certificate.

If peerAuthentication is enabled, client authentication may also be attempted. If X509_AUTHENTICATION is enabled by the server then a client certificate can replace the normal password based authentication. Identify the Common Name for the client certificate to use:

ClientSSLCert=<value>

The current user's personal certificate store is searched first for this certificate. The localmachine store will also be searched if a matching certificate is not found in the current user's store and the process has permission to access the localmachine's personal store.

If X509_AUTHENTICATION is enabled by the server and the ClientSSLCert is accepted, any UID and PWD values included in the connection string are ignored.

Examples:

"UID=ADMIN;PWD=ADMIN;Database=CtreeSQL;Server=localhost;Service=6597;ssl=basic";

"UID=ADMIN;PWD=ADMIN;Database=CtreeSQL;Server=localhost;Service=6597;ssl=peerAuthentication;sslcert=support.faircom.com";

"Database=CtreeSQL;Server=localhost;Service=6597;ssl=peerAuthentication;sslcert=support.faircom.com;ClientSSLCert=JohnDoe";