Certificates
Your system uses SSL to provide security for the Administration App. To enable SSL security, you need a valid SSL server certificate or chain of certificates.
Your system comes with its own self-signed SSL server certificate, which is generated and installed automatically when the system is installed. This certificate is not automatically trusted by web browsers.
You can choose to trust this self-signed certificate or to replace it with one from a certificate authority (CA) or one that you create yourself. You can also have the system generate and install a new self-signed SSL server certificate. You would do this, for example, if the current certificate is close to expiring and you are waiting to retrieve a new one from your CA.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
Viewing installed certificates
You can use the REST API, CLI, and Administration App to view information about the system certificate. That is, the certificate used to secure communications for the Administration App, Search App, CLIs, and REST APIs.
For each certificate, you can view:
•The distinguished name of the certificate
•The date and time when the certificate goes (or went) into effect
•The date and time when the certificate expires (or expired)
Administration App instructions
1.Click on System Configuration.
2.Click on the Certificates panel.
The System Certificates tab displays the currently active system certificate.
3.To view the data source certificates, click on the Client Certificates tab.
Related CLI command(s)
listCertificates
getCertificate
getSystemCertificate
For information on running CLI commands, see CLI reference.
Related REST API method(s)
GET /certificates
GET /certificates/system
GET /certificates/{subjectDn}
For information on specific REST API methods, in the Administration App, click on the help icon (). Then:
•To view the administrative REST API methods, click on Admin API.
•To view the API methods used for performing searches, click on Search API.
For general information about the administrative REST API, see REST API reference.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
Adding data source certificates
For your system to retrieve documents from a data source that uses SSL-protected communication, it must accept the certificate from the data source. Your system prompts you to accept a data source certificate when it tests the connection to the data source. You can also upload data source certificates manually.
Administration App instructions
Retrieving data source certificates automatically
1.Click on Workflows.
2.Click on the Data Connections .
3.Click on the data connection you want.
4.Click on the Test button.
If the system can connect to the data source, you are prompted to accept its certificate.
5.Click on the Accept and Add Certificate button.
Uploading data source certificates manually
1.Retrieve the SSL certificate from your data source.
2.In the Administration App, click on System Configuration.
3.Click on the Certificates panel.
4.On the Client Certificates tab, click on Add Client Certificate.
5.Click and drag the certificate file into the Upload Client Certificate box.
Related CLI command(s)
testDataSource
createCertificate
For information on running CLI commands, see CLI reference.
Related REST API method(s)
POST /datasources/test
POST /certificates
For information on specific REST API methods, in the Administration App, click on the help icon (). Then:
•To view the administrative REST API methods, click on Admin API.
•To view the API methods used for performing searches, click on Search API.
For general information about the administrative REST API, see REST API reference.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
Changing the system certificate
By default, your system includes a self-signed certificate when the system is first installed.
You cannot delete the currently-installed certificate. However, you can replace it by:
•Installing a new PKCS12 certificate (for instructions, see Installing a certificate you created)
•Generating and installing a new self-signed certificate (for instructions, see Installing a new self-signed certificate)
•Generating a certificate signing request (CSR) and installing the certificate you receive in response to this request (for instructions, see Creating a CSR and installing the returned certificate)
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
System certificate considerations
Keep the following in mind when configuring SSL certificates for your system, especially if you are configuring the system to use one or more certificates that you create yourself:
•Do not allow any of the SSL certificates to expire.
•Adhere to the established best practices for setting up SSL certificates. For example, if you are using wildcards to identify hostnames in an SSL certificate, a wildcard should appear only at the beginning of the hostname, not in the middle.
For information on SSL best practices, see http://tools.ietf.org/html/rfc5280 and http://tools.ietf.org/html/rfc6125.
•Ensure that the DNS name for the system matches the name defined in the certificate.
•When configuring a certificate chain, ensure that all intermediate issuers have the appropriate signing authority permissions so that the entire chain is signed.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
Installing a certificate you created
You can create an SSL server certificate by using a third-party tool such as OpenSSL. When creating the certificate, you specify two passwords — one for the PKCS12 object containing the certificate and one for the private key for the certificate. To use the certificate with your system, these passwords must be the same.
When you create your own SSL server certificate, you can choose to have that certificate signed by a certificate authority (CA). In this case, the CA you use may provide you with one or more intermediate certificates. These certificates are used in conjunction with the SSL server certificate you created to establish a certificate chain, an ordered list of certificates in which each certificate is trusted by the next.
To preserve the chain of trust among the certificates, you need to upload the certificates in the correct order. That is, each certificate you upload must be immediately followed by the certificate that signs it. For information on the correct order for the certificate chain, see your CA.
|
Important: Read and understand the topic System certificate considerations before creating your own SSL certificates and especially if you are using an in-house CA. |
Administration App instructions
To install your certificates:
1.Click on System Configuration.
2.Click on the Certificates panel.
3.Click on the Update System Certificate button.
4.On the PKCS12 panel, click and drag your certificate into the Upload Certificate Chain box.
5.In the PKCS12 Password field, type the password for your certificate.
6.Click and drag the certificate into the Upload Certificate Chain box.
7.Click on the Accept Certificate button.
Related CLI command(s)
uploadPKCS12Certificate
applyCertificateChanges
For information on running CLI commands, see CLI reference.
Related REST API method(s)
POST /certificates/system/pkcs12
POST /certificates/system
For information on specific REST API methods, in the Administration App, click on the help icon (). Then:
•To view the administrative REST API methods, click on Admin API.
•To view the API methods used for performing searches, click on Search API.
For general information about the administrative REST API, see REST API reference.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
Installing a new self-signed certificate
Your system can generate and install a new self-signed SSL server certificate. The new certificate is good for five years.
|
Important: If the system is using a self-signed certificate, when you change the hostname name of the system, you need to generate a new SSL certificate. For information on changing the hostname, see Setting the system hostname. |
Administration App instructions
To generate a new self-signed certificate:
1.Click on System Configuration.
2.Click on the Certificates panel.
3.Click on the Self-Signed panel.
4.Click on the Generate Certificate button.
Your system generates a new self-signed server certificate.
5.Click on the Accept Certificate button.
Your system installs the new certificate.
6.To continue using the Administration App, log out and then log back in.
Related CLI command(s)
generateSelfSignedCertificate
applyCertificateChanges
For information on running CLI commands, see CLI reference.
Related REST API method(s)
POST /certificates/system/selfsigned
POST /certificates/system
For information on specific REST API methods, in the Administration App, click on the help icon (). Then:
•To view the administrative REST API methods, click on Admin API.
•To view the API methods used for performing searches, click on Search API.
For general information about the administrative REST API, see REST API reference.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
Creating a CSR and installing the returned certificate
SSL server certificates are available from several trusted sources. To obtain a certificate created by a certificate authority (CA), you need to create a certificate signing request (CSR) and give it to the CA. The CA then generates the requested certificate and makes it available to you.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
Creating a certificate signing request
You can create a CSR using the Administration App or a third-party tool. When you use the Administration App, the system securely stores the private key needed for installing the returned certificate, so you don’t need to save it yourself.
To know exactly what information is required, check with the CA you plan to use.
Administration App instructions
To create a CSR:
1.Click on System Configuration.
2.Click on the Certificates panel.
3.Click on the CSR panel.
4.Select the Generate a new certificate signing request option and click on the Continue button.
5.In the Generate CSR section, fill in the fields as needed:
oIn the Common Name (CN) field, type the DNS name of the system preceded by an asterisk (*) and a period (.) (for example, *.system.example.com).
The Common Name (CN) field is required.
oIn the Organizational Unit (OU) field, type the name of the organizational unit that uses the system (for example, the name of a division or a name under which your company does business).
oIn the Organization (O) field, type the full legal name of your organization.
oIn the Location (L) field, type the name of the city in which your organization's headquarters are located.
oIn the State/Province (ST) field, type the full name of the state or province in which your organization's headquarters are located.
oIn the Country (C) field, type the two-letter ISO 3166-1 abbreviation for the country in which your organization's headquarters are located (for example, US for the United States).
6.Click on the Generate CSR button.
The page displays the generated certificate request.
7.Copy and paste the request text into a file and send that file to your CA.
8.Continue to Installing the certificates returned for a system-generated CSR.
Related REST API method(s)
PUT /certificates/system/csr
For information on specific REST API methods, in the Administration App, click on the help icon (). Then:
•To view the administrative REST API methods, click on Admin API.
•To view the API methods used for performing searches, click on Search API.
For general information about the administrative REST API, see REST API reference.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.
Installing the certificates returned for a system-generated CSR
In response to a CSR, your CA provides you with an SSL server certificate and any required intermediate certificates. These certificates are used in conjunction with the SSL server certificate to establish a certificate chain, an ordered list of certificates in which each certificate is trusted by the next. You need to upload and install these certificates on your system.
To preserve the chain of trust among the certificates, you need to upload the certificates in the correct order. That is, each certificate you upload must be immediately followed by the certificate that signs it. For information on the correct order for the certificate chain, see your CA.
Administration App instructions
To install the SSL server certificate and any intermediate certificates returned from a CA:
1.Click on System Configuration.
2.Click on the Certificates panel.
3.Click on the CSR panel.
4.Select the I already generated a CSR option and click on the Continue button.
5.Click and drag the certificate into the Upload certificate obtained from Certificate Authority box.
6.Click on the Accept Certificate button.
Related CLI command(s)
uploadCSR
applyCertificateChanges
For information on running CLI commands, see CLI reference.
Related REST API method(s)
POST /certificates/system/csr
POST /certificates/system
For information on specific REST API methods, in the Administration App, click on the help icon (). Then:
•To view the administrative REST API methods, click on Admin API.
•To view the API methods used for performing searches, click on Search API.
For general information about the administrative REST API, see REST API reference.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 Hitachi Vantara Corporation. All rights reserved.