Loading TOC...
Security Guide (PDF)

MarkLogic 9 Product Documentation
Security Guide — Chapter 9

« Previous chapter
Next chapter »

Configuring SSL on App Servers

This chapter describes SSL support in the MarkLogic Server, and includes the following sections:

This chapter describes how to use the Admin Interface to configure SSL on App Servers. For details on how to configure SSL programmatically, see Enabling SSL on an App Server in the Scripting Administrative Tasks Guide.

Understanding SSL

SSL (Secure Sockets Layer) is a transaction security standard that provides encrypted protection between browsers and App Servers. When SSL is enabled for an App Server, browsers communicate with the App Server by means of an HTTPS connection, which is HTTP over an encrypted Secure Sockets Layer. HTTPS connections are widely used by banks and web vendors for secure transactions over the web.

A browser and App Server create a secure HTTPS connection by using a handshaking procedure. When browser connects to an SSL-enabled App Server, the App Server sends back its identification in the form of a digital certificate that contains the server name, the trusted certificate authority, and the server's public encryption key. The browser uses the server's public encryption key from the digital certificate to encrypt a random number and sends the result to the server. From the random number, both the browser and App Server generate a session key. The session key is used for the rest of the session to encrypt/decrypt all transmissions between the browser and App Server, enabling them to verify that the data didn't change in route.

The end result of the handshaking procedure described above is that only the server is authenticated. The client can trust the server, but the client remains unauthenticated. MarkLogic Server supports mutual authentication, in which the client also holds a digital certificate that it sends to the server. When mutual authentication is enabled, both the client and the server are authenticated and mutually trusted.

MarkLogic Server uses OpenSSL to implement the Secure Sockets Layer (SSL v3) and Transport Layer Security (TLS v1) protocols.

The following are the definitions for the SSL terms used in this chapter:

  • A certificate, or more precisely, a public key certificate, is an electronic document that incorporates a digital signature to bind together a public key with identity information, such as the name of a person or an organization, address, and so on. The certificate can be used to verify that a public key belongs to an individual or organization. In a typical public key infrastructure (PKI) scheme, the signature will be that of a certificate authority.
  • A certificate authority (CA) is a trusted third party that certifies the identity of entities, such as users, databases, administrators, clients, and servers. When an entity requests certification, the CA verifies its identity and grants a certificate, which is signed with the CA's private key. If the CA is trusted, then any certificate it issues is trusted unless it has been revoked.
  • A certificate chain is a group of interdependent CAs. A certificate chain consists of a single trusted root CA, one or more intermediate CA, and one or more end CA. The intermediate and end certificates must be imported into MarkLogic.

    MarkLogic supports only one intermediate CA per host.

  • A certificate request is a request data structure containing a subset of the information that will ultimately end up in the certificate. A certificate request is sent to a certificate authority for certification.
  • A key is a piece of information that determines the output of a cipher. SSL/TLS communications begin with a public/private key pair that allow the client and server to securely agree on a session key. The public/private key pair is also used to validate the identity of the server and can optionally be used to verify the identity of the client.
  • A certificate template is a MarkLogic construct that is used to generate certificate requests for the various hosts in a cluster. The template defines the name of the certificate, a description, and identity information about the owner of the certificate.
  • A cipher is an algorithm for encrypting information so that it's only readable by someone with a key. A cipher can be either symmetric and asymmetric. Symmetric ciphers use the same key for both encryption and decryption. Asymmetric ciphers use a public and private key.

    Signed certificates are imported via the Certificate Templates import page, as described in Importing a Signed Certificate into MarkLogic Server. Certificate Authority certificates are imported via the Certificate Authorities import page, as described in CA Certificate (User Cert Signer) Import from Admin Interface.

General Procedure for Setting up SSL for an App Server

This section describes the general procedure for setting up SSL on an App Server. The general steps are:

Procedures for Enabling SSL on App Servers

The following sections describe how to enable SSL for an App Server:

Creating a Certificate Template

Access to an SSL-enabled server is managed by a public key in a signed certificate obtained from a certificate authority. The first step in producing a request for a signed certificate is to define a certificate template. This procedure will produce a self-signed certificate that your browser can temporarily use to access an SSL-enabled server until you receive a signed certificate from a certificate authority.

  1. Click the Security icon in the left tree menu.
  2. Click the Certificate Templates icon on the left tree menu.
  3. Click the Create tab. The Create Certificate Template page will display:

  4. In the Template Name field, enter a shorthand name for this certificate template. MarkLogic Server will use this name to refer to this template on display screens in the Admin Interface.
  5. You can enter an optional description for the certificate template.

  6. Enter the name of your company or organization in the Organization Name field.
  7. You can optionally fill in subject information, such as your country, state, locale, and email address. Country Name must be two characters, such as US, UK, DE, FR, ES, etc.

  8. When you have finished filling in the fields, click OK. MarkLogic Server automatically generates a Self-Signed Certificate Authority, which in turn automatically creates a signed certificate from the certificate template for each host. For details on how to view the Certificate Authority and signed certificate, see Viewing Trusted Certificate Authorities.

Enabling SSL for an App Server

After creating a certificate template, you can enable SSL for an HTTP, ODBC, WebDAV, or XDBC server.

  1. Click the Groups icon in the left tree menu.
  2. Click the group in which you want to define the HTTP server (for example, Default).
  3. Click the App Servers icon on the left tree menu.
  4. Either create a new server by clicking on one of the Create server_type tabs or select an existing server from the left tree menu.

    The SSL fields are located at the bottom of the server specification page.

  5. In the SSL Certificate Template field, select the certificate template you created in Creating a Certificate Template. Selecting a certificate template implicitly enables SSL for the App Server.
  6. (Optional) The SSL Hostname field should only be filled in when a proxy or load balancer is used to represent multiple servers. In this case, you can specify an SSL hostname here and all instances of the application server will identify themselves as that host.
  7. (Optional) In the SSL Ciphers field, you can either use the default (ALL:!LOW:@STRENGTH) or one or more of the SSL ciphers defined in http://www.openssl.org/docs/apps/ciphers.html.

  8. (Optional) If you want SSL to require clients to provide a certificate, select True for SSL Require Client Certificate. Then select Show under SSL Client Certificate Authorities and which certificate authority is to be used to sign client certificates for the server.
  9. (Optional) Set SSL Client Issuer Authority Verification to True to ensure that the App Server will accept client certificates only signed directly by a selected CA from the SSL Client Certificate Authorities list. A setting of False enables the App Server to accept client certificates that have a parent CA that is indirectly signed by one or more ancestor CAs selected in the Admin Interface (same as prior to MarkLogic 9.0-8).

Accessing an SSL-Enabled Server from a Browser or WebDAV Client

When you create a certificate template and set it in your App Server, MarkLogic Server automatically generates a temporary self-signed MarkLogic certificate authority that signs host certificates. If you have not yet received a signed certificate for your SSL-enabled App Server from a certificate authority, your browser must accept the temporary self-signed certificate authority before it can access the App Server. There are two alternative ways to do this, both of which are browser-dependent and described below.

To enable WebDAV clients to access an SSL-enabled App Server, you must follow the procedure described in Importing a Self-Signed Certificate Authority into Windows.

To enable a single browser to access the SSL-enabled App Server, you can create a security exception for the self-signed certificate in your browser, as described in the following sections:

If you need to enable a number of browsers to access the SSL-enabled App Server, you might want each browser to import the self-signed certificate authority for the certificate template. Once this is done, all certificates signed by the certificate authority will be trusted by the browser, so you can distribute new certificates without requiring each browser to create new security exceptions. The following sections describe how to import the self-signed MarkLogic certificate authority:

Creating a Security Exception in Internet Explorer

If you have not imported the certificate authority for the certificate template into Windows, when you first access an SSL-enabled server with your IE browser, you will receive an error notifying you that there is a problem with this website's security certificate. You can bypass this security exception by accepting the certificate. For example, if you enabled SSL on the HTTP server, App-Services, each host can accept the self-signed certificate as described below.

  1. Access the server with the URL:
    https://gordon-1:8000/

    Remember to start your URL with HTTPS, rather than HTTP. Otherwise, the browser will return an error.

  2. The server responds with a There is a problem with this website's security certificate notification similar to:

  3. Click on Continue to this website (not recommended)
  4. Enter your MarkLogic Server username and password at the prompt.

Creating a Security Exception in Google Chrome

If you have not imported the MarkLogic certificate authority into your Chrome browser, when you first access an SSL-enabled server, you will receive an error notifying you that you have accessed an untrusted server. You can bypass this security exception by accepting the certificate. For example, if you enabled SSL on the HTTP server, App-Services, you can accept the self-signed certificate as described below.

  1. Access the server with the URL:
    https://gordon-1:8000/

    Remember to start your URL with HTTPS, rather than HTTP. Otherwise, the browser will return an error.

  2. The server responds with a Your connection is not private notification similar to:

  3. Click on Advanced.
  4. At the bottom of the expanded window, select Proceed to hostname (unsafe).

  5. Enter your MarkLogic Server username and password at the prompt.

Importing a Self-Signed Certificate Authority into Windows

This section describes how to import the Certificate Authority into Windows for use by the Internet Explorer browser and WebDAV clients.

  1. Open the Admin interface in your Internet Explorer browser.
  2. Click the Security icon in the left tree menu.
  3. Click the Certificate Templates icon on the left tree menu.
  4. Click the certificate template name on the left tree menu. The Configure certificate template page will display.
  5. Click the Status tab to display the certificate template Status page.
  6. Click on Import.

  1. In the Do you want to open or save this file? window, click Open.

  2. In the Certificate Information window, click Install Certificate.

  3. In the Certificate Import Wizard window, select Place all certificates in the following store and click Browse.

  4. In the Select Certificate Store window, select Trusted Root Certification Authorities and click OK.

  5. In the Certificate Import Wizard window, click Next.
  6. On the Completing the Certificate Import Wizard page, select Certificate Store Selected by User and click Finish

  7. In the Security Warning page, click Yes.

  8. When you see The import was successful prompt, click OK.

  9. In the Certificate Information window, click OK to exit.

You should now be able to access the SSL-enabled server from your Internet Explorer browser or WebDAV client.

Procedures for Obtaining a Signed Certificate

Use the following procedures to obtain a signed certificate and import into your server:

Generating and Downloading Certificate Requests

Once the server is created or modified with SSL enabled, you can generate one or more PEM-encoded certificate requests.

You must first assign the certificate template to an App Server, as described in Enabling SSL for an App Server, before you can generate a certificate request.

  1. Click the Security icon in the left tree menu.
  2. Click the Certificate Templates icon on the left tree menu.
  3. Click the certificate template name on the left tree menu. The Configure certificate template page will display.
  4. Click the Request tab. The Generate Certificate Request page will display:

  1. Select either All or Only those that are needed for missing, expired, self-signed, or out of date certificates that are not already pending, then click OK.
  2. The certificate template Status page will display. Click on Download to download the certificate request to your file system.

  1. If the file does not already have a 'zip' extension, rename the file by replacing the 'xqy' extension with 'zip'.
  2. Send the zip file containing the certificate requests to a Certificate Authority, such as Verisign.

Signing a Certificate with your own Certificate Authority

As an alternative to using a third-party Certificate Authority, you can create your own Certificate Authority, as described in Creating a Certificate Authority. You can then use this Certificate Authority to sign the certificate request using the pki:authority-sign-host-certificate-request function.

Once signed, you can forward the signed certificate to any MarkLogic user, who can then import the signed certificate into their MarkLogic host, as described in Importing a Signed Certificate into MarkLogic Server.

For example, to request and sign a certificate from the mycert template created in Creating a Certificate Template, do the following:

xquery version "1.0-ml"; 
 
import module namespace pki = "http://marklogic.com/xdmp/pki" 
      at "/MarkLogic/pki.xqy";

declare namespace x509 = "http://marklogic.com/xdmp/x509";

let $req :=
  pki:generate-certificate-request(
    pki:get-template-by-name("mcert")/pki:template-id,
    "ServerName", (), ())
let $cert := 
  pki:authority-sign-host-certificate-request(
    xdmp:credential-id("acme-ca"),
    xdmp:x509-request-extract($req),
    fn:current-dateTime(),
    fn:current-dateTime() + xs:dayTimeDuration("P365D"))

return xdmp:x509-certificate-extract($cert)

Importing a Signed Certificate into MarkLogic Server

When you receive the PEM file(s) containing signed certificate(s) from the certification authority, import the PEM file(s) into MarkLogic Server. If you are using chained certificates, you will need to import the end and intermediate certificate PEM files into MarkLogic Server. If your MarkLogic Server is to act as a client , you must also import the root certificate.

Because the signed certificate is from a trusted certification authority, browsers are already configured to trust the certificate.

  1. Click the Security icon in the left tree menu.
  2. Click the Certificate Templates icon on the left tree menu.
  3. Click the certificate template name on the left tree menu. The Configure certificate template page will display.
  4. Click the Import tab. The Import Certificates page will display:

  5. Click on Browse to locate the PEM file(s) containing the signed certificate(s) and select OK. Zip files can be uploaded directly without the need to unzip them. Alternatively, you can paste an individual certificate(s) into the text area.

Viewing Trusted Certificate Authorities

You can list all of the certificate authorities that are known to and trusted by the server in the Certificate Authority page. Each CA in the list links to the corresponding Certificate Authority page for that CA.

The Certificate Authority page provides detailed information on the CA, a list of revoked certificates, the option to manually revoke a certificate by ID, and the ability to delete the CA from the server.

  1. Click the Security icon in the left tree menu.
  2. Click the Certificate Authority icon on the left tree menu.
  3. The Certificate Authority Summary page displays the list of trusted CAs:

  1. Click on a CA in the list to display the details on the CA:

Importing a Certificate Revocation List into MarkLogic Server

A Certificate Revocation List (CRL) is a list of certificate serial numbers that have been revoked by a certificate authority. The CRL is signed by the certificate authority to verify its accuracy. The CRL contains the revocation date of each certificate, along with the date the CRL was published and the date it will next be published, which is useful in determining whether a newer CRL should be fetched.

You can use the pki:insert-certificate-revocation-list function to import a CRL into the Security database. certificate authorities typically allow the CRL to be downloaded via HTTP. The document URL in the database is derived from the URL passed in to the function, so Inserting a newer CRL retrieved from the same URL will replace the previous one in the database.

For example, the following script imports a PEM- or DER-encoded CRL from Verisign into the Security database:

xquery version "1.0-ml"; 
import module namespace pki = "http://marklogic.com/xdmp/pki" 
         at "/MarkLogic/pki.xqy";
let $URI := "http://crl.verisign.com/pca3.crl"
return
    pki:insert-certificate-revocation-list(
         $URI,
         xdmp:document-get($URI)/binary() )

If next publication date of the CRL is earlier than the current time, you will recieve the following message in the error log: loadCertificateRevocationLists: Most recent CRL for issuer=<issuer_name> is expired.

Deleting a Certificate Template

Deleting a template deletes all signed certificates and pending requests for the template. Before deleting a certificate template, ensure that a certificate with that name is not in use by a server. If a certificate with the same name as the certificate template is in use by a server, the delete operation returns an Invalid input error.

To delete an unused certificate template:

  1. Click the Security icon in the left tree menu.
  2. Click the Certificate Templates icon on the left tree menu.
  3. Click the certificate template name on the left tree menu.
  4. On the Certificate Template page, click Delete:

  1. In the confirmation page, select OK.
« Previous chapter
Next chapter »