Administration > SSL Settings

Use the Administration > SSL Settings page to configure how the search appliance identifies itself when communicating over HTTPS and controls configuration settings for certificate use. This help page covers the following topics:

• Understanding SSL Certificate Settings
• Uploading an Externally Generated Private Key and Certificate
  • Decrypting a Private Key
  • Installing a Private Key and Certificate
• Requesting and Installing a Certificate Using the Admin Console
  • Creating and Installing a Self-Signed Certificate
  • Generating a CSR
  • Installing a Signed Certificate for a Generated CSR
• Forcing Secure Connections When Serving
• Using Secure Feeds
  • Enabling HTTP (non-SSL) Access for Feedergate
  • Enabling Client Certificate Authentication for Feedergate
• Specifying Client Certificates for User Authentication
• Setting Server Certificates for Crawler Authentication
• Setting Server Certificates for Serving
• Setting Server Certificates for OneBox Provider Authentication
• Marking Certificate-Protected Documents as "Public"
• Identifying Servers that Use HTTPS
• Troubleshooting Certificate-Based Authentication Issues
• For More Information

Before Starting this Task

Before configuring SSL settings, complete the tasks shown in the following table.

Page Options

The SSL Settings page provides the options shown in the following table.

Understanding SSL Certificate Settings

The search appliance uses a certificate to establish HTTPS connections when it is crawling web servers and when it is serving results to clients. If you do not have a current certificate on the SSL Settings page, or the certificate is unsigned, users will see a security message each time that they perform a search.

Use the following sections on the SSL Settings page to install a signed certificate from a certificate authority.

• Current SSL Certificate Information
• Create a New SSL Certificate
• Install an SSL Certificate

If you don't have a signed certificate, you can request one. Use the SSL Settings page to create the certificate signing request file that you send to a certificate authority such as VeriSign or E-Certify.

Note: It may take a couple of days to receive a signed certificate back from a root CA, so plan your schedule accordingly.

There are two methods for configuring a certificate for the search appliance:

• If you have a signed digital certificate and a corresponding private key, you can provide the credentials in the Install an SSL Certificate section. If you are using an intermediate certificate, use this method and append the intermediate certificate to the host certificate file. The process for uploading an externally generated private key and certificate is described below.
• If you don't have a signed digital certificate, you can use the Admin Console to request one and then install it. The process for requesting a certificate using the Admin Console is described below.
  

When requesting a certificate for the search appliance, note the certificate expiration date, and make sure that you request a new certificate before the current one expires.

Only one SSL certificate can be used by the search appliance at any time. Uploading a new certificate replaces the one currently used.

Uploading an Externally Generated Private Key and Certificate

The process for uploading an externally generated private key and certificate is as follows:

1. If the private key is encrypted or in PKCS#12 format, decrypt the private key for upload to the search appliance. The SSL Settings page can only install non-encrypted RSA keys in privacy enhanced mail (.pem) format.
2. If your SSL certificate (end entity certificate) is signed by one or more certificate authorities, then you need to combine the host certificate, intermediate CA certificates, and the root CA certificate in a single file. The file should be in a base64 encoded PEM file. Also, the certificates must be in the following order:
   
   -----BEGIN CERTIFICATE-----
   Host certificate
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   Intermediate certificate-1
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   Intermediate certificate-2
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   Root certificate
   -----END CERTIFICATE-----
3. Install the private key and the corresponding certificate. Installing the certificate restarts the Admin Console and the front end.

Decrypting a Private Key

The SSL Settings page can only install non-encrypted RSA keys in .pem format. Use the freely available openssl software and the following openssl command to decrypt the private key and perform conversion to .pem format.

For a key in PKCS#12 format, use this syntax to extract the key and decrypt it:

openssl pkcs12 -in file.p12 -out file.pem -nodes

For a .pem format encrypted key, use this syntax to decrypt the key:

openssl rsa -in file.pem -out file.pem

Installing a Private Key and Certificate

To install a private key and certificate:

1. On the SSL Settings page, scroll down to Install an SSL Certificate.
• Under SSL Certificate, type the file name of the certificate or click the Choose File button to locate it. If you are using an intermediate certificate, type the name of the file that includes both the intermediate certificate and the host certificate.
• Under SSL Private Key, type the file name of the unencrypted private key or click the Choose File button to locate it. If the SSL Certificate contains an intermediate certificate, use the private key that corresponds to the host certificate.
2. Click View Certificate Information.
3. Installing the certificate restarts the search appliance. If you are ready to install, click Install SSL Certificate.
4. When the page refreshes, the following message appears at the top:
SSL certificate installed. The appliance console needs to be restarted, please log in again.
5. On the Admin Console login page, click Log in, and log in using the admin username and password.
6. Click Administration > SSL Settings. The new certificate information is listed under Current SSL Certificate Information.
7. Query the search appliance for secure content that requires HTTPS authentication. If you see a security message when you try to view the content, the certificate is invalid, or it cannot be authenticated with the key that you installed. If you see the expected content and do not get any security messages, the certificate is correctly installed.
8. If SSL authentication is working as expected, delete your local copy of the unencrypted private key file.

Important Note: For HTTPS crawling to work correctly, you must upload all intermediate and root certificates to the Google Search Appliance on Administration > Certificate Authorities page.

Requesting and Installing a Certificate Using the Admin Console

Important: After you export a certificate signing request (CSR) and send it to your signing authority, do not generate an additional CSR file. Generating a CSR file deletes the private key associated with the previous CSR and creates a new key pair, which does not match the certificate that you have already sent to the certificate authority (CA).

The process for requesting and installing a certificate using the search appliance user interface is as follows:

1. Install a self-signed certificate on the search appliance. Although this certificate has not been signed by a certificate authority, it will eliminate "hostname mismatch" warning that displays while you wait for a response from the certificate authority.
2. Generate a certificate signing request (CSR) file and key pair.
3. Send the CSR file to the CA. It may take a few days to receive a signed certificate back from a root CA.
4. When you receive the signed certificate from the certificate authority, install the certificate on the search appliance.
5. Perform a test query over HTTPS to ensure that SSL authentication is working as expected.

Creating and Installing a Self-Signed Certificate

To create and install a self-signed certificate on the search appliance:

1. Click Administration > SSL Settings.
2. On the SSL Settings page, scroll down to Create a New SSL Certificate.
• Under Host Name, type the fully qualified host name of the search appliance. This is the name users see when they search on your site.
• Under Organizational Unit, type the name of your department. For example, "Web Services Group".
• Under Organization, type the name of your organization.
• Under Locality, type the name of your city.
• Under State, type the state or province. You must use the full name, not an abbreviation.
• Under Country, type the two-letter code for your country, such as US or FR.
• Under Email Address, type the administrator's email address, or "None."
• Under Self-Generated SSL Private Key Size, select one of the following sizes from the pull-down menu: 1024 bits, 2048 bits, or 4096 bits.
• Under Upload my SSL Private Key, type your company's non-encrypted private key, or click the Choose File button to locate it. The SSL Settings page can only install non-encrypted RSA keys in .pem format. If the key is encrypted, see decrypting a private key.
  If you do not enter a private key, the search appliance creates one.


3. Click Create Self-Signed Certificate to generate a key pair for the certificate signing request. The generated key pair is 1024-bit RSA.
   
4. Installing the certificate restarts the search appliance. Click Install SSL Certificate. When the page refreshes, the following message appears at the top:
SSL certificate installed. The appliance console needs to be restarted, please log in again.
5. On the Admin Console login page, click Log in, and log in using your username and password.
6. Click Administration > SSL Settings. The new certificate information is listed under Current SSL Certificate Information.
7. Verify that the information shown under Current SSL Certificate Information is correct.

Generating a CSR

To generate a certificate signing request (CSR):

1. On the Admin Console login page, click Log in, and log in using your username and password.
2. Click Administration > SSL Settings. The certificate information is listed under Current SSL Certificate Information.
3. To generate a certificate signing request file based on this information, click Export Certificate Signing Request.
4. The Download dialog box opens with a search appliance Certificate Signing Request file (.pem). Save the CSR file to your hard disk.
5. Locate the saved file, and send it to a signing authority organization. The root CA will ask for proof that you are the company that you say you are. It may take a few days to hear back from them. When you receive the signed certificate, continue with Installing a Signed Certificate for a Generated CSR

Installing a Signed Certificate for a Generated CSR

To install a signed certificate for a certificate signing request (CSR) that is generated on the search appliance:

1. Click Administration > SSL Settings.
2. On the SSL Settings page, scroll down to Install an SSL Certificate.
   • Under SSL Certificate, type the file name of the certificate that you received from the certificate authority in response to the search appliance-generated certificate signing request.
   • If your SSL certificate (end entity certificate) is signed by one or more certificate authorities, then you need to combine the host certificate, intermediate CA certificates, and the root CA certificate in a single file. The file should be in a base64 encoded PEM file. Also, the certificates must be in the following order:
   
   -----BEGIN CERTIFICATE-----
   Host certificate
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   Intermediate certificate-1
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   Intermediate certificate-2
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   Root certificate
   -----END CERTIFICATE-----
   
   
   • Leave the SSL Private Key field blank.
     
3. Click View Certificate Information.
4. Installing the certificate restarts the search appliance. If you are ready to install, click the Install SSL Certificate button. When the page refreshes, the following message appears at the top:
SSL certificate installed. The appliance console needs to be restarted, please log in again.
5. On the Admin Console login page, click Log in, and log in using your username and password.
6. Click Administration > SSL Settings. The certificate information is listed under Current SSL Certificate Information.
7. Query the search appliance for secure content that requires HTTPS authentication. If you see a security message when you try to view the content, your certificate is not valid, or else it cannot be authenticated with the key that you installed. If you see the expected content and do not get any security messages, the certificate is correctly installed.

Important Note: For HTTPS crawling to work correctly, you must upload all intermediate and root certificates to the Google Search Appliance on Administration > Certificate Authorities page.

Forcing Secure Connections When Serving

• No. No results are served over HTTPS. This option provides fastest performance.
• Use HTTPS when serving secure results, but not when serving public results. Only documents requiring credential authentication are served over HTTPS.
• Use HTTPS when serving both public and secure results. All documents, both public and secure, served over HTTPS.

To make a selection, click an option button and click the Save button.

Using Secure Feeds

You upload an XML feed using an HTTP POST to the feedergate server located on port 19900 of your Google Search Appliance. The search appliance supports HTTPS access to the Feedergate server through port 19902, enabling you to upload an XML feed file by using a secure connection. The Administration > SSL Settings page provides the following options for configuring secure access to Feedergate:

• Enabling HTTP (non-SSL) access for Feedergate
• Enabling Client Certificate Authentication for Feedergate

For more information about the Feedergate server, see "Feeds Protocol Developer's Guide," which is linked to the Google Search Appliance help center.

Enabling HTTP (non-SSL) Access for Feedergate

By default, the search appliance supports HTTP (non-SSL) access to the Feedergate server. You can disable or re-enable HTTP (non-SSL) access to Feedergate.

To disable HTTP access to Feedergate:

1. Click Administration > SSL Settings.
2. On the SSL Settings page, scroll down to Feedergate HTTP (non-SSL) access.
3. Clear the Enable HTTP (non-SSL) access for Feedergate checkbox.
4. Click Save.

To re-enable HTTP access to Feedergate:

1. Click Administration > SSL Settings.
2. On the SSL Settings page, scroll down to Feedergate HTTP (non-SSL) access.
3. Check the Enable HTTP (non-SSL) access for Feedergate checkbox.
4. Click Save.

Enabling Client Certificate Authentication for Feedergate

By default, Feedergate accepts any incoming connection from the list of valid IP addresses. You can force the Feedergate SSL port (19902) to accept only connections from IP address in the trusted IP addresses list and clients who present a valid x509 certificate when connecting. Valid means that the certificate is signed by a certificate in the CA keystore on the search appliance (or a certificate in the certificate chain).

The search appliance does not support Certificate Revocation Lists (CRLs) with Feedergate client authentication.

To enable client certificate authentication for Feedergate:

1. Click Administration > SSL Settings.
2. On the SSL Settings page, scroll down to Feedergate Client Certificate Authentication.
3. Check the Enable Client Certificate Authentication for Feedergate checkbox.
4. Click Save.

If Enable Client Certificate Authentication for Feedergate is not checked, then any client of the Feedergate does not need to present a client certificate to submit feeds successfully.  In this case, the Feedergate SSL port accepts any connections from IP addresses in the trusted IP addresses list.

To disable client certificate authentication for Feedergate:

1. Click Administration > SSL Settings.
2. On the SSL Settings page, scroll down to Feedergate Client Certificate Authentication.
3. Clear the Enable Client Certificate Authentication for Feedergate checkbox.
4. Click Save.

Specifying Client Certificates for User Authentication

To use client certificates as authentication for confidential documents, configure a credential group rule for client certificate user authentication by using the Client Certificate tab of the Search > Secure Search > Universal Login Auth Mechanisms page.

Note: The Google Search Appliance must have a digital certificate that permits crawl and serve over HTTPS.

Setting Server Certificates for Crawler Authentication

To require that the crawler authenticates certificates presented by servers that contain secure content:

1. Click Administration > Certificate Authorities page.
2. Upload a Certificate Authority certificate and its Certificate Revocation List files.
3. Navigate back to this page (Administration > SSL Settings).
4. Check the Enable Server Certificate Authentication check box and then click Save.

Setting Server Certificates for Serving

To require serve-time server certificate check, ensure that Enable Server Certificate Authentication During Serving Time is checked. To disable the serve-time server certificate check, uncheck the checkbox.

Setting Server Certificates for OneBox Provider Authentication

To require that the crawler authenticates certificates presented by OneBox providers, check Enable OneBox Provider Certificate Authentication and click Save.

Note: The search appliance does not accept a self-signed certificate from a OneBox external provider.

Marking Certificate-Protected Documents as "Public"

You can allow users to get all documents protected by certificates as non-secure search results by marking them as public. However, the Make Public settings for URL patterns on the Content Sources > Web Crawl > Secure Crawl > Crawler Access page override the setting on this page.

To mark these protected documents as public:

1. Click Administration > SSL Settings.
2. On the SSL Settings page, scroll down to Client Certificate Authentication.
3. Click the Documents protected by certificates are marked "public" checkbox.
4. Click Save.

To disable the setting, clear the checkbox.

Identifying Servers That Use HTTPS

Unless forced to use secure connections when serving, the search appliance uses the same protocol specified during crawl that a user uses to submit a search.

To identify access-controlled content, check for the following:

• If you have forced the search appliance to use secure connections by selecting Use HTTPS when serving both public and secure results, the search appliance uses HTTPS and requires certificates, regardless of whether the content is public or secure.
• Check for server names or IP addresses that appear in URLs beginning with https: in the following text fields:
  • Under Content Sources > Web Crawl > Secure Crawl > Forms Authentication, check Sample Forms Authentication protected URL and URL pattern for this rule.
    
  • Under Search > Secure Search > Universal Login Auth Mechanisms > Cookie, check Sample URL.

Troubleshooting Certificate-Based Authentication Issues

If you have installed a certificate and see certificate warnings or are unable to serve access-controlled documents, the following certificate issues can occur:

• A user searches and the browser displays an error about the certificate.
• A user searches and expects to view access-controlled documents. The documents do not appear in the search results and the crawler cannot download the documents because the search appliance's certificate is not recognized by the content server.

To diagnose these issues, you can check the following:

• Is the certificate signed by a CA that your browser trusts? See Certificate Authorities.
• Has the certificate expired? Request a new certificate and install it using one of the procedures described in Requesting and Installing a Certificate Using the Admin Console.
• Does your fully qualified search appliance name match the name in the certificate?

Note that the search appliance supports certificates that are signed for only a single host name.
• Does your search URL correspond to the fully qualified machine name as shown on the certificate?
• Is the private key for the certificate uploaded as an unencrypted RSA key in .pem format?
• Verify the hierarchy of certificates, either in your browser, or by asking your X.509 Certificate Authority support team. Some CAs provide root certificates that issue intermediate certificates that issue the server certificates. If this is the case for the certificate on one or more of your web servers, you must create a file that contains both the host and intermediate certificates and install it along with the host key.
• On the SSL Settings page, clear the checkbox labeled Server certificates for Crawler Authentication and retry the query. When server certificate verification is enabled for the crawler, the search appliance performs additional checks including Certificate Revocation List validation which may fail due to expiring CRLs. Remove any expiring CRL entries and try re-enabling the checkbox again.

For More Information

See the section "Digital Certificates and Certificate Authorities" in "Managing Search for Controlled-Access Content: Crawl, Index, and Serve," which is linked to the Google Search Appliance help center.