WARNING: Version 5.x has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Working with certificates
editWorking with certificates
editIf you’ve enabled SSL on Elasticsearch with X-Pack or through a proxy in front of Elasticsearch, and the Certificate Authority (CA) that generated the certificate is trusted by the machine running the client code, there should be nothing you’ll have to do to talk to the cluster over HTTPS with the client.
If you are using your own CA which is not trusted however, .NET won’t allow you to make HTTPS calls to that endpoint by default. With .NET,
you can pre-empt this though a custom validation callback on the global static
ServicePointManager.ServerCertificateValidationCallback
. Most examples you will find doing this this will simply return true
from the
validation callback and merrily whistle off into the sunset. This is not advisable as it allows any HTTPS traffic through in the
current AppDomain
without any validation. Here’s a concrete example:
Imagine you deploy a web application that talks to Elasticsearch over HTTPS through NEST, and also uses some third party SOAP/WSDL endpoint; by setting
ServicePointManager.ServerCertificateValidationCallback += (sender, cert, chain, errors) => true
validation will not be performed for HTTPS connections to both Elasticsearch and that external web service.
Validation configuration
editIt’s possible to also set a callback per service endpoint with .NET, and both Elasticsearch.NET and NEST expose this through
connection settings (ConnectionConfiguration
with Elasticsearch.Net and ConnectionSettings
with NEST). You can do
your own validation in that handler or use one of the baked in handlers that we ship with out of the box, on the static class
CertificateValidations
.
The two most basic ones are AllowAll
and DenyAll
, which accept or deny all SSL traffic to our nodes, respectively. Here’s
a couple of examples.
Denying all certificate validation
editHere we set up ConnectionSettings
with a validation callback that denies all certificate validation
public class DenyAllCertificatesCluster : SslAndKpiXPackCluster { protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s .ServerCertificateValidationCallback((o, certificate, chain, errors) => false) .ServerCertificateValidationCallback(CertificateValidations.DenyAll); }
Allowing all certificate validation
editHere we set up ConnectionSettings
with a validation callback that allows all certificate validation
public class AllowAllCertificatesCluster : SslAndKpiXPackCluster { protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s .ServerCertificateValidationCallback((o, certificate, chain, errors) => true) .ServerCertificateValidationCallback(CertificateValidations.AllowAll); }
Allowing certificates from a Certificate Authority
editIf your client application has access to the public CA certificate locally, Elasticsearch.NET and NEST ship with some handy helpers that can assert that a certificate the server presents is one that came from the local CA.
If you use X-Pack’s certgen
tool to generate SSL certificates, the generated node certificate
does not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use
CertificateValidations.AuthorityIsRoot
and pass it your local copy of the CA public key to assert that
the certificate the server presented was generated using it
public class CertgenCaCluster : SslAndKpiXPackCluster { public CertgenCaCluster() : this(new SslAndKpiClusterConfiguration()) { } public CertgenCaCluster(SslAndKpiClusterConfiguration configuration) : base(configuration) { } protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s .ServerCertificateValidationCallback( CertificateValidations.AuthorityIsRoot(new X509Certificate(this.ClusterConfiguration.FileSystem.CaCertificate)) ); }
If your local copy does not match the server’s CA, the client will fail to connect
public class BadCertgenCaCluster : SslAndKpiXPackCluster { protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s .ServerCertificateValidationCallback( CertificateValidations.AuthorityPartOfChain(new X509Certificate(this.ClusterConfiguration.FileSystem.UnusedCaCertificate)) ); }
If you go for a vendor generated SSL certificate, it’s common practice for the certificate to include the CA and any intermediary CAs
in the certificate chain. When using such a certificate, use CertificateValidations.AuthorityPartOfChain
which validates that
the local CA certificate is part of the chain that was used to generate the server’s key.
Client Certificates
editX-Pack also allows you to configure a PKI realm to enable user authentication
through client certificates. The certgen
tool included with X-Pack allows you to
generate client certificates as well and assign the distinguished name (DN) of the
certificate to a user with a certain role.
certgen by default only generates a public certificate (.cer
) and a private key .key
. To authenticate with client certificates, you need to present both
as one certificate. The easiest way to do this is to generate a pfx
or p12
file from the .cer
and .key
and attach these to requests using new X509Certificate(pathToPfx)
.
If you do not have a way to run openssl
or Pvk2Pfx
to do this as part of your deployments the clients ships with a handy helper to generate one
on the fly by passing the paths to the .cer
and .key
files that certgen
outputs. Sadly, this functonality is not available on .NET Core because
the PublicKey
property cannot be set on the crypto service provider that is used to generate the pfx
file at runtime.
You can set Client Certificates to use on all connections on ConnectionSettings
public class PkiCluster : CertgenCaCluster { public PkiCluster() : base(new SslAndKpiClusterConfiguration { DefaultNodeSettings = { {"xpack.security.authc.realms.file1.enabled", "false"}, {"xpack.security.http.ssl.client_authentication", "required"} } }) { } protected override ConnectionSettings Authenticate(ConnectionSettings s) => s .ClientCertificate( Elasticsearch.Net.ClientCertificate.LoadWithPrivateKey( this.ClusterConfiguration.FileSystem.ClientCertificate, this.ClusterConfiguration.FileSystem.ClientPrivateKey, "") ); }
Set the client certificate on |
|
The path to the |
|
The path to the |
|
The password for the private key |
Or per request on RequestConfiguration
which will take precedence over the ones defined on ConnectionConfiguration
Object Initializer syntax example
editnew RootNodeInfoRequest { RequestConfiguration = new RequestConfiguration { ClientCertificates = new X509Certificate2Collection { new X509Certificate2(this.Certificate) } } }
Fluent DSL example
edits => s .RequestConfiguration(r => r .ClientCertificate(this.Certificate) )