Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Certificates

Your system uses SSL to provide security for the Admin 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 to replace the certificate with either 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 do this, for example, if the current certificate is close to expiring and you are waiting to retrieve a new one from your CA.

Viewing installed certificates

You can use the REST API, CLI, and Admin App to view information about:

  • The system certificate. This is the certificate used to secure communications for your system's applications, CLIs, and REST APIs.
  • Data source certificates. These are the certificates retrieved from the systems that your system has connected to using a data connection.

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)
Admin App instructions

Procedure

  1. Select the Configuration window.

  2. Click Certificates.

    The System tab displays the currently active system certificate.
  3. To view the data source certificates, select the Client tab.

Related CLI commands

listCertificates

getCertificate

getSystemCertificate

Related REST API methods

GET /certificates

GET /certificates/system

GET /certificates/{subjectDn}

You can get help on specific REST API methods for the Admin App at REST API - Admin.

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 testing the connection to the data source. You can also upload data source certificates manually.

Retrieving data source certificates automatically

Procedure

  1. Click Configuration.

  2. Click Data Connections window.

  3. Click the data connection you want.

  4. Click Test.

    If the system can connect to the data source, you are prompted to accept its certificate.

  5. Click Accept and Add Certificate.

Uploading data source certificates manually

Admin App instructions

Procedure

  1. Retrieve the SSL certificate from your data source.

  2. In the Admin App, click Configuration.

  3. Click Certificates.

  4. On the Client tab, click Upload Client Certificate.

  5. Drag the certificate file into the Upload Certificate box.

Related CLI commands

testDataSource

createCertificate

Related REST API methods

POST /datasources/test

POST /certificates

You can get help on specific REST API methods for the Admin App at REST API - Admin.

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
  • Generating and installing a new self-signed certificate
  • Generating a certificate signing request (CSR) and installing the certificate you receive in response to this request

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.

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, which is 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.

To install your certificates:

Admin App instructions

Procedure

  1. Select the Configuration window.

  2. Click Certificates.

  3. Click Update System Certificate.

  4. On the PKCS12 window, drag your certificate into the Upload Certificate Chain box.

  5. In the PKCS12 Password field, type the password for your certificate.

  6. Drag the certificate into the Upload Certificate Chain box.

  7. Click Continue.

  8. Click Accept.

Related CLI commands

uploadPKCS12Certificate

applyCertificateChanges

Related REST API methods

POST /certificates/system/pkcs12

POST /certificates/system

You can get help on specific REST API methods for the Admin App at REST API - Admin.

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.

NoteIf 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.
Admin App instructions

Procedure

  1. Select the Configuration window.

  2. Click Certificates.

  3. Click Update System Certificate.

  4. Select the Self-Signed window.

  5. Click Continue.

    Your system generates a new self-signed server certificate.
  6. Click Accept.

    Your system installs the new certificate.
  7. To continue using the Admin App, log out and then log back in.

Related CLI commands

generateSelfSignedCertificate

applyCertificateChanges

Related REST API methods

POST /certificates/system/selfsigned

POST /certificates/system

You can get help on specific REST API methods for the Admin App at REST API - Admin.

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.

Creating a certificate signing request

You can create a CSR using the Admin App or a third-party tool. When you use the Admin App, the system securely stores the private key needed for installing the returned certificate, so you don’t need to save the key yourself.

It's best to verify what information is required with the CA that you plan to use.

Admin App instructions

Procedure

  1. Select the Configuration window.

  2. Click Certificates.

  3. Select the System tab.

  4. Click Update System Certificate.

  5. Select the CSR window.

  6. Choose Generate a new certificate signing request and click Continue.

  7. Fill in the following as needed:

    • In the box Common Name (CN), type the DNS name of the system preceded by an asterisk (*) and a period (.) (for example, *.system.example.com).

      The Common Name (CN) is required.

    • In the box Organizational Unit (OU), type the name of the organizational unit that uses the system (for example, the name of a division or a name under which the company does business).
    • In the box Organization (O), type the full legal name of the organization.
    • In the box Location (L), type the name of the city in which the organization's headquarters are located.
    • In the box State/Province (ST), type the full name of the state or province in which the organization's headquarters are located.
    • In the box Country (C), type the two-letter ISO 3166-1 abbreviation for the country in which the organization's headquarters are located (for example, US for the United States).
  8. Click Generate CSR.

    The page displays the generated certificate request.
  9. Copy and paste the request text into a file and send that file to the CA.

Related REST API methods

PUT /certificates/system/csr

You can get help on specific REST API methods for the Admin App at REST API - Admin.

Installing the certificates returned for a system-generated CSR

In response to a CSR, your CA gives you 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.

Admin App instructions

Procedure

  1. Select the Configuration window.

  2. Click Certificates.

  3. Select the System tab.

  4. Click Update System Certificate.

  5. Select the CSR window.

  6. Select the I already generated a CSR and obtained a signed certificate option and then click Continue.

  7. Drag the certificate into the Upload certificate obtained from Certificate Authority box.

  8. Click Accept.

Related REST API methods

POST /certificates/system/csr

POST /certificates/system

You can get help on specific REST API methods for the Admin App at REST API - Admin.

 

  • Was this article helpful?