Security
The System Management application supports configuring system security features, including user authentication.
Granting access to users
These are the general steps you need to take to grant users access to the system:
- Add one or more identity providers to the system.
- Add one or more groups from your identity providers to the system.
- Create a role that contains the system permissions you want to associate with a group of users.
- Associate roles with groups.
Setting the session timeout limit
You can use the Admin App, CLI commands, or REST API methods to set the system session timeout limit. This limit affects user sessions in all applications that your system runs and also affects the length of time that REST API authorization tokens are valid.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Settings tab, type a number of minutes in the Session Timeout field.
Click Update.
Related CLI commands
editSecuritySettings
Related REST API methods
PUT /security/settings
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Setting the refresh token timeout limit
You can use the Admin App, CLI commands, or REST API methods to set the refresh token timeout limit. The refresh token timeout limit must be greater than the session timeout limit so that if the access token expires, the refresh token will still be active and you can request a new session token. When your refresh token expires, you will need to resubmit your credentials to access your system.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Settings tab, type a number of minutes in the Refresh Token Timeout field.
Click Update.
Related CLI commands
editSecuritySettings
Related REST API methods
PUT /security/settings
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Setting the CORS Allowed Origins
You can use the Admin App, CLI commands, or REST API methods to set CORS (cross-origin resource sharing) origins that are allowed on your system. Specifying multiple origins allows you to access restricted resources.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Settings tab, type a list of origins in the CORS Allowed Origins field.
Click Update.
Related CLI commands
editSecuritySettings
Related REST API methods
PUT /security/settings
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Identity providers
The system supports these identity provider types for user authentication:
- Active Directory (AD)
- OpenLDAP
- 389 Directory Server
- LDAP Compatible: Other LDAP-compatible identity providers not listed above
To use one of these systems to authenticate users with your system, you need to first add your identity provider to the system.
Adding identity providers
Procedure
Select the Configuration window.
Click Security.
On the Identity Providers tab, click Create.
Select and configure an identity provider type.
Click Create.
Related CLI commands
createIdentityProvider
Related REST API methods
POST /security/identityProviders
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Identity provider configuration settings
The following sections describe the configuration settings for each type of identity provider that the system supports.
Security Realm Name - The name by which to identify this identity provider in the system. The name appears as an option in the Security Realm list on Admin App login pages.
- Identity Provider Hostname - Host name or IP address for the identity provider.
- Transport Security - The protocol to use for securing communications between the system and the identity provider. Options are:
- None
- TLS Security (Transport Layer Security)
- Use Suffix For Hostname Verification - When enabled, if the client host name doesn’t match the certificate host name, host name verification will instead verify whether the ending of the client host name matches the provided suffix. WARNINGThis option can impact security and should only be enabled if the client host name is expected to differ from the certificate host name.
- Hostname Suffix - The suffix used for host name verification if the default host name verification fails.
- Use Suffix For Hostname Verification - When enabled, if the client host name doesn’t match the certificate host name, host name verification will instead verify whether the ending of the client host name matches the provided suffix.
- SSL (Secure Sockets Layer)
NoteWhen selecting TLS Security, the setting Use Suffix For Hostname Verification appears. - Identity Provider Host Port - Network port used to communicate with the identity provider. The default value depends on the Transport Security setting:
- For None or TLS Security (Transport Layer Security), 389
- For SSL (Secure Sockets Layer), 636
- User Name - A user account on the identity provider. The system uses this user account to read information from the identity provider.
- Password - The user account password.
- Domain - The AD domain in which the user account is defined. NoteUse the short name for the AD domain. For example, use
MYACTIVEDIRECTORYinstead ofMYACTIVEDIRECTORY.local. - Search Base DN - The distinguished name (DN) of the identity provider location where you want the system to begin its searches for users and groups.
For example, if you specify a value of OU=Users,DC=corp,DC=example,DC=com, the system searches for users and groups in the organization unit called Users in the corp.example.com domain.
- Default Domain Name - The default domain for users logging into the Admin App and Search App. For example, if you specify a default domain name of east.example.com, the user jdoe@east.example.comneeds to specify only jdoe when logging into either app.
- Identity Provider Hostname - Host name or IP address for the identity provider.
- Transport Security - The protocol to use for securing communications between the system and the identity provider. Options are:
- None
- TLS Security (Transport Layer Security)
- Use Suffix For Hostname Verification - When enabled, if the client host name doesn’t match the certificate host name, host name verification verifies whether the ending of the client host name matches the provided suffix. CautionThis option can impact security and should only be enabled if the client host name is expected to differ from the certificate host name.
- Hostname Suffix - The suffix used for host name verification if the default host name verification fails.
- Use Suffix For Hostname Verification - When enabled, if the client host name doesn’t match the certificate host name, host name verification verifies whether the ending of the client host name matches the provided suffix.
- SSL (Secure Sockets Layer)
- Identity Provider Host Port - Network port used to communicate with the identity provider. The default value depends on the Transport Security setting:
- For None or TLS Security (Transport Layer Security), 389
- For SSL (Secure Sockets Layer), 636
- User Name - A user account on the identity provider. Your system uses this account to read information from the identity provider.
- Password - The user account password.
- User DN Template - A template on the LDAP server. When a user logs into their system, the provided username is inserted into this template to determine the user's LDAP distinguished name (DN).
- Unique ID - The unique identifier of this user on this identity provider (for example, an entryUUID).
- Member Name Attribute - The name of the attribute that each group on the identity provider uses to list its members.
- Search Base DN - The distinguished name (DN) of the identity provider location where you want the system to begin searching for users and groups.
For example, if you specify a value of OU=Users,DC=corp,DC=example,DC=com, the system searches for users and groups in the organization unit called Users in the corp.example.com domain.
- Group Object Class - The objectClass value for groups on the LDAP server.
- Identity Provider Hostname - Host name or IP address for the identity provider.
- Transport Security - The protocol to use for securing communications between the system and the identity provider. Options are:
- None
- TLS Security (Transport Layer Security)
- Use Suffix For Hostname Verification - When enabled, if the client host name doesn’t match the certificate host name, host name verification verifies whether the ending of the client host name matches the provided suffix. WARNINGThis option can impact security and should only be enabled if the client host name is expected to differ from the certificate host name.
- Hostname Suffix - The suffix used for host name verification if the default host name verification fails.
- Use Suffix For Hostname Verification - When enabled, if the client host name doesn’t match the certificate host name, host name verification verifies whether the ending of the client host name matches the provided suffix.
- SSL (Secure Sockets Layer)
- Identity Provider Host Port - Network port used to communicate with the identity provider. The default value depends on the Transport Security setting:
- For None or TLS Security (Transport Layer Security), 389
- For SSL (Secure Sockets Layer), 636
- User Name - The distinguished name of the user or role, used by HCP for cloud scale to query the identity provider.
- Password - The user account password.
- User DN Template - A template on the LDAP server. When a user logs into their system, the provided username is inserted into this template to determine the user's LDAP distinguished name (DN).
- Unique ID - The unique identifier of this user on this identity provider (for example, an entryUUID).
- Member Name Attribute - The name of the attribute that each group on the identity provider uses to list its members.
- Search Base DN - The distinguished name (DN) of the identity provider location where you want the system to begin searching for users and groups.
For example, if you specify a value of OU=Users,DC=corp,DC=example,DC=com, the system searches for users and groups in the organization unit called Users in the corp.example.com domain.
User information caching
The system caches the following information from each of your identity providers:
- The names of users who access the system.
- The groups that each user belongs to.
As long as this information is in the system's cache, your users can perform any activities for which they have permissions, without the system needing to reconnect to the identity provider.
LDAP user information remains in the cache for four hours.
Any changes that you make on the identity provider are not reflected in the system until the information is removed from the cache. For example, if you add a user to an LDAP identity provider, that user cannot access the system for up to four hours, or until the cache is cleared. If you delete a user from an LDAP identity provider, that user will be able to access the system for up to four hours, or until the cache is cleared.
To ensure that a change is reflected immediately, use the clearCache command or API.
Related CLI commands
clearCache
Related REST API methods
POST /security/clearCache
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Viewing identity providers
You can use the Admin App, CLI commands, or REST API methods to view the identity providers that have been added to your system.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Identity Providers tab.
Related CLI commands
getIdentityProvider
listIdentityProviders
Related REST API methods
GET /security/identityProviders/{uuid}
GET /security/identityProviders
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Deleting identity providers
When you delete an identity provider from your system, all users from that provider lose access to the system.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Identity Providers tab, click the delete icon (
) for the server you want to remove.
Related CLI commands
deleteIdentityProvider
Related REST API methods
DELETE /security/identityProviders/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Groups
To allow user access to your system, you need to add groups to your system. These groups are defined on your organization's identity providers. After you add a group to your system, you can specify what roles its members have.
Adding groups
You use the Admin App, CLI commands, or REST API methods to add groups from your identity providers to your system.
objectClass=groupOfNames are supported.Procedure
Select Dashboard > Configuration.
Click Security.
On the Groups tab, click Create.
Select an identity provider and type a string on which to query the identity provider for groups.
Click Discover Groups.
Click Continue.
Select one or more roles to associate with the group.
Click Create.
Related CLI commands
createGroup
Related REST API methods
POST /security/groups
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Viewing groups
You use the Admin App, CLI commands, or REST API methods to view all the groups that have been created for your system.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Groups tab.
Related CLI commands
getGroup
listGroups
Related REST API methods
GET /security/groups/{uuid}
GET /security/groups
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Assigning roles to groups
You use the Admin App, CLI commands, or REST API methods to assign roles to the groups that you've added your system.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Groups tab, select the group you want to edit.
On the Roles tab, select one or more roles to enable for the group.
Click Update.
Related CLI commands
editGroup
Related REST API methods
PUT /security/groups/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Deleting groups
When you delete a group, all users in the group lose access to your system.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Groups tab.
Click the delete icon (
) for the group you want to remove.
Related CLI commands
deleteGroup
Related REST API methods
DELETE /security/groups/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Roles
Roles determine what actions a group of users can perform. You create your own roles, each of which can grant permission to perform any combination of actions.
Creating roles
You can use the Admin App, CLI commands, or REST API methods to create roles and select which permissions the roles contain.
Each permission in a role grants a user the ability to perform an action in some area of the system. For example, the admin:services:read permission grants the ability to view services through the Admin App.
Procedure
Select Dashboard > Configuration.
Click Security.
On the Roles tab, click Create.
Specify a name and, optionally, a description for the role.
Use the Individual and Wildcard tabs to edit the permissions for the role.
On the Individual tab, you can enable individual permissions or categories of permissions:- Select a category of permissions and select one or more individual permissions within the category.
For example, with the permissions selected in this image, a user can read, create, and update certificates, but cannot delete them.
- On the Wildcard tab, you can enable permissions for multiple categories at the same time. To do this:
- Click Add Permission.
- Use the menus to select a category of permissions.
- Leave the last menu set to the wildcard character (*).
- Select a category of permissions and select one or more individual permissions within the category.
Click Create.
Click Update.
Related CLI commands
createRole
Related REST API methods
POST /security/roles
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Viewing roles
You can use the Admin App, CLI commands, or REST API methods to view all the roles that have been created for your system.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Roles tab.
Related CLI commands
getRole
listRoles
Related REST API methods
GET /security/roles/{uuid}
GET /security/roles
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Editing roles
You can use the Admin App, CLI commands, or REST API methods to change the permissions that a role contains.
Each permission in a role grants a user the ability to perform an action in some area of the system. For example, the permission admin:services:read grants the ability to view services through the Admin App.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Roles tab.
Select the role you want to edit.
Use the Individual and Wildcard tabs to edit the permissions for the role.
On the Individual tab, you can enable individual permissions or categories of permissions:- Select a category of permissions and select one or more individual permissions within the category.
For example, with the permissions selected in this image, a user can read, create, and update certificates, but cannot delete them.
- On the Wildcard tab, you can enable permissions for multiple categories at the same time. To do this:
- Click Add Permission.
- Use the menus to select a category of permissions.
- Leave the last menu set to the wildcard character (*).
- Select a category of permissions and select one or more individual permissions within the category.
Click Create.
Click Update.
Related CLI commands
editRole
Related REST API methods
PUT /security/roles/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Deleting roles
When you delete a role, all groups associated with that role lose the permissions that the role granted.
Procedure
Select Dashboard > Configuration.
Click Security.
Select the Roles tab.
Click the delete icon (
) for the role you want to remove.
Related CLI commands
deleteRole
Related REST API methods
DELETE /security/roles/{uuid}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Permissions
The following tables list the HCP for cloud scale permissions available for system roles. The words Yes and No indicate whether or not the permission is assigned for a default role.
The set permissions override corresponding get permissions. That is, if a user has permission to set (configure) a function, the user is also granted permission to get (view) the function.
| Chargeback Reporting | ||
| Permission name | Description | Default admin role permission? |
| chargeback:system:get_report | Generate chargeback report for any bucket | Yes |
| chargeback:user:get_report | Generate chargeback report for the user's buckets | Yes |
| Data Service | ||
| Permission name | Description | Default admin role permission? |
| data:bucket:encryption:get | Execute S3 API GET bucket object encryption rules | Yes |
| data:bucket:encryption:set | Execute S3 API PUT bucket object or DEL bucket object encryption rules Note: Does not govern use of --x-amz-Server-side-encryption=AES256 | Yes |
| data:bucket:expirationlifecycle:get | View bucket expiration lifecycle policy configuration | Yes |
| data:bucket:expirationlifecycle:set | Configure bucket expiration lifecycle policy | Yes |
| data:bucket:notification:get | View bucket notification configuration | Yes |
| data:bucket:notification:set | Configure bucket notification | Yes |
| data:bucket:objectlock:get | View bucket object lock policy configuration | Yes |
| data:bucket:objectlock:set | Configure bucket object lock policy | Yes |
| data:bucket:sync:from:set | Create bucket sync-from rules for buckets the user owns or has access to | Yes |
| data:bucket:sync:get | View bucket sync-from and sync-to rules for buckets the user owns or has access to | Yes |
| data:bucket:sync:to:set | Create bucket sync-to rules for buckets the user owns or has access to | Yes |
| KMIP | ||
| Permission name | Description | Default admin role permission? |
| mapi:kmip:add_server | Configure an external KMIP server | Yes |
| mapi:kmip:add_server | Remove configuration of an individual external KMIP server | Yes |
| mapi:kmip:get_server | Get information about an individual external KMIP server | Yes |
| mapi:kmip:list_servers | Get information about configured KMIP servers | Yes |
| mpi:kmip:update_server | Update the configuration of an external KMIP server | Yes |
| License | ||
| Permission name | Description | Default admin role permission? |
| mapi:license:add | Add licensed feature | Yes |
| mapi:license:list | List all licensed feature | Yes |
| MAPI Alerts | ||
| Permission name | Description | Default admin role permission? |
| mapi:alert:list | List all active alerts | Yes |
| MAPI S3 Settings | ||
| Permission name | Description | Default admin role permission? |
| mapi:s3_settings:get | Read S3 settings | Yes |
| mapi:s3_settings:set | Modify S3 settings | Yes |
| MAPI Storage Component | ||
| Permission name | Description | Default admin role permission? |
| mapi:storage_component:activate | Activate a storage component | Yes |
| mapi:storage_component:get_capacity | Get storage component capacity | Yes |
| mapi:storage_component:create | Create a storage component | Yes |
| mapi:storage_component:list | List storage component(s) | Yes |
| mapi:storage_component:test | Test a storage component | Yes |
| mapi:storage_component:update | Modify a storage component | Yes |
| mapi:storage_component:update_state | Modify state of a storage component | Yes |
| MAPI Stored Objects | ||
| Permission name | Description | Default admin role permission? |
| mapi:client_object:lookup | List stored objects | Yes |
| MAPI System | ||
| Permission name | Description | Default admin role permission? |
| mapi:certificates:refresh | Refresh SSL certificates | |
| mapi:system:info | List system information | Yes |
| MAPI User | ||
| Permission name | Description | Default admin role permission? |
| mapi:user:list | List existing users | Yes |
| mapi:user:list_buckets | List user's buckets | Yes |
| mapi:user:revoke_credentials | Revoke S3 credentials | Yes |
| mapi:user:revoke_tokens | Revoke OAuth tokens | Yes |
| S3 Encryption Setting | ||
| Permission name | Description | Default admin role permission? |
| mapi:s3_encryption:get | Read S3 encryption settings | Yes |
| mapi:s3_encryption:set | Enable global encryption | Yes |
| mapi:s3_encryption:unseal | Unseal KMS service | Yes |
| S3 User | ||
| Permission name | Description | Default admin role permission? |
| s3:user:generate_credentials | Generate S3 credentials | Yes |
| Serial Number | ||
| Permission name | Description | Default admin role permission? |
| mapi:serial_number:get | Read serial number | Yes |
| mapi:serial_number:set | Modify serial number | Yes |
Revoking user account credentials
To immediately and completely revoke a user's account credentials, it's best to remove credentials from the identity provider, clear the HCP for cloud scale user cache, revoke OAuth tokens, and revoke S3 credentials, in that order.
You might want to revoke a user's account credentials for a number of reasons:
- The user has left the organization.
- The user is part of a company that has ended a contract with the organization.
- The user had a temporary account that has expired.
Before you begin
To complete these tasks you must have permission to reset a user's password in the identity provider (IdP), such as Active Directory or LDAP, and you must have permission to execute HCP for cloud scale API methods.
If you remove the user account from the IdP, you might not be able to move or delete the user's data and buckets. If you must do that, reset the account password instead, delete or move the data as needed, and then remove or disable the account.
Procedure
Prevent the user from signing in through the IdP.
- Remove or disable the user account in the IdP.
- Change or remove the user's password.
Clear the HCP for cloud scale user cache:
Obtain an OAuth token.
Use the API method
POST security/clearCache.
Revoke the user's OAuth tokens.
Obtain an OAuth token (or use the token previously obtained).
Obtain an XSRF token.
Use the API method
The response body contains the user ID.POST user/listto obtain the user ID for the user.Use the API method
You should receive a 200 OK response with an empty response body.POST user/revoke_tokens, passing as a parameter the user ID previously obtained.
Revoke the user's existing S3 credentials.
(Alternatively, you can generate fresh S3 credentials, but the listed steps create a positive record of revocation.)Obtain an OAuth token (or use the token previously obtained).
Obtain an XSRF token (or use the token previously obtained).
Use the API method
POST user/listto obtain the user ID for the user (or use value previously obtained).Use the API method
You should receive a 200 OK response with an empty response body.POST user/revoke_credentials, passing as a parameter the user ID previously obtained.
Results
Next steps
- Remove all objects, versions, and delete markers in each of the user's buckets. When the buckets are empty, remove them.
- Set an expiration period of one second in each of the user's buckets. When the buckets are empty, remove them.
Changing a local user's account password
Your system includes a single local user account called admin, which is available when you first install the system. In addition, your system lets you create a secondary local admin account for reconciliation purposes. You can use the Admin App, CLI commands, or REST API methods to change the passwords for these accounts.
Procedure
Click the user icon (
) in the top right corner of the window.Click Change Password.
Confirm your current password for the chosen account and specify a new password.
Click Change Password.
Related CLI commands
updateCurrentUserPassword
Related REST API methods
POST /setup/password
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Certificates
HCP for cloud scale uses SSL to provide secure incoming and outgoing communication for the product applications and mTLS for external encryption key management.
To enable secure socket layer (SSL) security, you need a valid server certificate or chain of certificates for incoming communication and a valid client certificate for outgoing communication.
The system comes with its own self-signed SSL system certificate, which is generated and installed automatically when the system is installed. This certificate is sufficient for some purposes but not automatically trusted by web browsers. For production systems the best practice is to obtain and use a certificate from a certificate authority (CA).
If you choose to replace the self-signed system certificate, do one of the following:
- Upload a PKCS12 format certificate chain from a CA.
- Download a certificate signing request (CSR) and use it to obtain, upload, and apply a certificate signed by a CA.
- Generate and apply a new self-signed SSL server certificate. You might do this, for example, if the current certificate is close to expiring and you are waiting to retrieve a new one from your CA.
For outgoing communication, such as to storage components, you need to upload the certificate used by clients. However, you don't need to upload the client certificate if it's valid and trusted by a CA.
HCP for cloud scale supports mutual transport layer security (mTLS) v1.2 (not recommended), v1.3, or later to support data in flight encryption with an external key management system (KMS). Establishing mTLS requires an exchange of certificates between the system and the KMS.
Viewing installed certificates
You can use the Admin App, CLI commands, or REST API methods to view information about:
- The system certificate. This is the certificate used to secure communications for your system's applications, CLIs, and REST APIs.
- Client certificates. These are the certificates you upload to HCP for cloud scale that allow the system to communicate securely with clients such as storage components, Active Directory, and external key management systems.
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)
Procedure
Select Dashboard > Configuration.
Click Certificates.
The System tab displays the currently active system certificate.To view the client 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.
Client certificates
The HCP for cloud scale system requires certificates to communicate securely with external systems.
For the HCP for cloud scale system to communicate with Identity Providers (IdPs), storage components that use SSL-protected communication, and external encryption key management systems, the system must accept the certificate from those clients. Your system prompts you to accept a client certificate when testing the connection to an IdP using the System Management application. It's best to use valid SSL certificates trusted by a certificate authority, but you can also upload client certificates manually.
Client certificate considerations
Keep the following in mind when configuring SSL certificates for a client (such as a storage component):
- Do not allow any of the SSL certificates to expire.
- Adhere to the established best practices for setting up SSL certificates.
For information on SSL best practices, see http://tools.ietf.org/html/rfc5280 and http://tools.ietf.org/html/rfc6125.
- When configuring a certificate chain, ensure that all intermediate issuers have the appropriate signing authority permissions so that the entire chain is signed.
- If you regenerate or upload an SSL certificate you must repair (that is, restart) the S3 Gateway and MAPI Gateway services for the change to take effect.
- If you regenerate or upload an SSL certificate for an S3-compatible remote system used for bucket synchronization you must repair (that is, restart) the S3 Gateway and Policy Engine services for the change to take effect.
Retrieving the client certificate for an HCP S Series Node
It's best to use valid SSL certificates from a trusted certificate authority. If an HCP S Series Node storage component uses another kind of certificate, you can retrieve the certificate and upload it manually. This procedure uses the Firefox browser.
Procedure
Go to the HCP S Series Node management interface at
where host is the host name of the management system.https://host:8000/Right click and select Page Info.
Select Security and click View Certificate.
Click the Details tab.
Click Export, select a download location, and click Save.
Results
Next steps
Uploading client certificates manually
If a client such as a storage component does not have a trusted SSL certificate, you can upload it manually.
Procedure
Retrieve the SSL certificate from your client.
In the Admin App, click Configuration.
Click Certificates.
On the Client tab, click Upload Client Certificate.
Drag the certificate file into the Upload Certificate box.
Refresh the certificate by doing one of the following:
- Use the Object Storage Management MAPI method
POST /certificates/refresh - Click Services, select and repair the S3 Gateway service, and then select and repair the MAPI Gateway service.
- Use the Object Storage Management MAPI method
Next steps
Related CLI commands createCertificate
createCertificate
Related REST API methods
POST /certificates (System Management)
POST /certificates/refresh (Object Storage Management)
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Changing the system certificate
Your system includes a self-signed certificate when the system is first installed.
You cannot delete the currently installed certificate. However, you can replace the certificate by:
- Installing a new PKCS12 certificate
- Generating and installing a new self-signed certificate
- Generating a certificate signing request (CSR), sending it to a certificate authority (CA), and installing the certificate you receive in response
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. If you rename the system you need a new certificate.
- When configuring a certificate chain, ensure that all intermediate issuers have the appropriate signing authority permissions so that the entire chain is signed.
- If you regenerate or upload an SSL certificate you must repair (that is, restart) the S3 Gateway and MAPI Gateway services for the change to take effect.
- If encryption is enabled you must also repair the Key Management Server service and unseal the vault.
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 the system, these passwords must be the same.
When you create an SSL server certificate, you can have that certificate signed by a certificate authority (CA). In this case, the CA you use might 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 must 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 the CA.
Procedure
Select Dashboard > Configuration.
Click Certificates.
Click Update System Certificate.
In the box PKCS12 Password, type the password for the certificate.
Drag the certificate into the box Upload Certificate Chain.
Click Continue.
Click Accept.
Restart (repair) the S3 Gateway.
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.
- 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.
- When you install the new certificate, if you are using encryption, you must repair the Vault service and then unseal the vault.
Procedure
Select Dashboard > Configuration.
Click Certificates.
Click Update System Certificate.
Select the Self-Signed window.
Click Continue.
Your system generates a new self-signed server certificate.Click Accept.
Your system installs the new certificate.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.
Verify what information is required with the certificate authority (CA) that you plan to use.
Procedure
Select Dashboard > Configuration.
Click Certificates.
Select the System tab.
Click Update System Certificate.
Select the CSR window.
Choose Generate a new certificate signing request and click Continue.
Fill in the following as needed:
- In the Common Name (CN) box, type the cluster name or an asterisk (*) followed by the DNS name of the system (for example, cluster.company.com or *.company.com).
Common Name (CN) is required.
- In the Organizational Unit (OU) box, 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 Organization (O) box, type the full legal name of the organization.
- In the Location (L) box, type the name of the city in which the organization's headquarters are located.
- In the State/Province (ST) box, type the full name of the state or province in which the organization's headquarters are located.
- In the Country (C) box, type the two-letter ISO 3166-1 abbreviation for the country in which the organization's headquarters are located (for example,
USfor the United States). - In the Subject Alternate Name box, type
cluster.dns *.cluster.dns, where cluster is the name of your HCP for cloud scale cluster.For example: cluster.company.com *.cluster.company.com
Subject Alternative Name is required for Chrome browsers.
NoteThe System Management application supports a single SAN, so arrange with your CA to include two SANs in the final signed certificate.
- In the Common Name (CN) box, type the cluster name or an asterisk (*) followed by the DNS name of the system (for example, cluster.company.com or *.company.com).
Click Generate CSR.
The page displays the generated certificate request.Copy and paste the request text into a file and send that file to the CA.
Related CLI commands
generateCSR
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.
Procedure
Select Dashboard > Configuration.
Click Certificates.
Select the System tab.
Click Update System Certificate.
Select the CSR window.
Select the option I already generated a CSR and obtained a signed certificate and then click Continue.
Drag the certificate into the Upload certificate obtained from Certificate Authority box.
Click Accept.
Related CLI commands
uploadCSR
applyCertificateChanges
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.
Exchanging certificates with a KMS server
Before you can configure a connection to an external KMS server, the HCP for cloud scale system and an external server must exchange SSL certificates to establish mutual trust.
To enable data-at-rest encryption with keys managed by an external key management system (KMS) that supports the Key Management Interoperability Protocol (KMIP), you need to exchange SSL certificates between the HCP for cloud scale system and the KMS so that they can establish mutual transport layer security (mTLS). HCP for cloud scale supports mTLS v1.3 and, for backward compatibility, v1.2. Both systems need to have certificates granted by a certificate authority (CA).
Before you begin, you must have entered a serial number in your HCP for cloud scale and then uploaded a digital license to use the encryption feature. For information on entering a serial number, see Entering your serial number. For information on uploading a license, see Uploading a license.
The following workflow uses Thales CipherTrust Manager as an example of an external KMS, but you can use any third-party product that supports the KMIP protocol. Some steps in the workflow are performed on the Thales system. Before you begin the workflow, you need the following information:
- The certificate of the certificate authority that signed the HCP for cloud scale system certificate
- The URL and login credentials for the Thales system
- The HCP for cloud scale certificate signing request and signed system certificate
These are the tasks involved:
- Creating a certificate signing request from the HCP for cloud scale system
- Installing the certificates returned for a system-generated CSR on the HCP for cloud scale system
- Restarting (repairing) the S3 Gateway, MAPI Gateway, and Key Management Server services on the HCP for cloud scale system
- Retrieving the KMIP certificate from the KMS server
- Uploading the client certificate (the KMIP certificate) from the KMS server to the HCP for cloud scale system
- Retrieving the system certificate from the HCP for cloud scale system and uploading the CA certificate to the KMS server
- Creating a new user, profile, registration token, and registered client on the KMS server
Once the HCP for cloud scale and external KMS have exchanged certificates, you can configure external encryption key management.
Retrieving the KMIP certificate from the KMS server
The HCP for cloud scale system requires an SSL certificate in PEM format from the KMS system to establish mTLS.
For example, to retrieve the certificate from a Thales CipherTrust Manager system:
Procedure
Log in to the Thales system.
The web console opens.Select .
The Interfaces page opens.Select the kmip interface.
Click the more icon, at the righthand side of the interface, and select Edit.
The Configure KMIP page opens.Click Download Current Certificate.
The certificate file, Certificate_kmip.txt is downloaded.Edit the certificate file to copy the first certificate to a separate file with the suffix .crt.
This is the KMIP certificate.Transfer the edited certificate file you created in the previous step to the HCP for cloud scale system as a client certificate.
Retrieving the system certificate from the HCP for cloud scale system and uploading the CA certificate to the KMS server
The KMS server requires an SSL certificate from the HCP for cloud scale system to establish mTLS.
For example, to retrieve the system certificate from the HCP for cloud scale system and upload the CA certificate on the Thales system:
Procedure
Open the HCP for cloud scale system certificate and copy the body.
Log in to the Thales system.
The web console opens.Select .
The External Certificate Authorities page opens.Click Add External CA.
The Add External Certificate page opens.Name the certificate, paste in the body of the certificate, and click Save.
The CA is added to the list of external certificate authorities.From the web console, select .
The Interfaces page opens.Select the kmip interface.
Click the more icon, at the righthand side of the interface, and select Edit.
The Configure KMIP page opens.Select the HCP for cloud scale CA and click the add (+) button.
Click Update
Creating a new user, client profile, registration token, and registered client on the KMS server
Before you begin
You need to create the following on the third-party KMS system:
- User account corresponding to the common name (CN) of the HCP for cloud scale system
- Client profile
- Registration token
- Registered client
Before you begin this task:
- You need both the HCP for cloud scale certificate signing request and signed system certificate.
- You need to determine the name, email, and password of the user account on the Thales system.
- You need to determine the name of the client profile.
- You need to determine the default name prefix, token lifetime, certificate duration, and client capacity of the registration token. (For the last three items you can use the defaults.)
- You need to determine the name of the registered client.
For example, to create a new user account, client profile, registration token, and registered client on the Thales system:
Procedure
Log in to the Thales system.
The web console opens.Create a user account:
Select .
The Users page opens.Click Create New User.
The Create a New User page opens.Enter the user's username, email, and password (twice).
Click Create.
The user is added to the list of users.Select .
The Groups page opens.Select the Key Users group.
The members of the Key Users group are listed.Locate the user and click Add.
The user is added as a member of the group.
Create a client profile:
Click Products and select KMIP.
The Registered Clients page opens.Select Client Profile.
The Client Profiles page opens.Click Add Profile.
The Add Profile page opens.Enter the client profile name.
Expand the Certificate Details section of the page and paste the contents of the HCP for cloud scale CSR into the CSR field.
Click Save.
The profile is added to the list of profiles.
Create a registration token:
Click Products and select KMIP.
The Registered Clients page opens.Select Registration Token.
The Registration Token page opens.Click New Registration Token.
The Create New Registration Token wizard opens.Click Begin and enter the default name prefix, token lifetime, certificate duration in days, and client capacity.
Click Select CA, click External, and select the CA you uploaded previously.
Click Select Profile and select the client profile you created previously.
Click Create Token.
The registration token is created.Click Copy to copy the registration token.
Click Done.
The registration token is added to the list of tokens.
Register a new client:
Click Products and select KMIP.
The Registered Clients page opens.Select Add Client.
The Add Client page opens.Enter the name of the client.
In the Registration Token field, paste the registration token you previously copied.
In the Client Certificate field, paste the contents of the HCP for cloud scale system certificate.
Click Save.
The client is added to the list of registered clients.
Repeating the certificate exchange if HCP for cloud scale is redeployed
If you redeploy the HCP for cloud scale system, you must repeat the process of establishing mTLS because the system's private key is changed.
For example, on a Thales system you must:
- Delete the client profile, registration token, and registered client
- Restart the KMIP and web services
- Redefine the client profile, registration token, and registered client
Encryption
Using the licensed DARE encryption feature, you can configure and manage either internal encryption, using a built-in HCP for cloud scale service, or external encryption, using a KMIP-compatible encryption server.
An administrator with appropriate permissions can:
- Select and configure either internal or external encryption
- Provide unseal keys to the internal KMS service as needed
- Manage the external KMS connection
- Initiate a rekey operation
Enabling either internal or external encryption requires both planning and configuration. The mode of encryption cannot be changed between internal and external, and once enabled encryption cannot be disabled.
Internal encryption uses the Key-Management-Server (KMS) service to store and manage key encryption keys (KEKs). The KMS service generates a KEK for each storage component and stores them in a persistent vault maintained by the service. Enabling internal encryption generates an initial root token to establish the connection to the service, KEKs for each storage component, and a set of five unseal keys.
Each time the KMS service starts it uses the unseal keys to open the vault. If the KMS service goes down, it seals the vault, and to unseal the vault you must provide a quorum of at least three valid unseal keys. If HCP for cloud scale restarts, encryption and decryption functions pause until the KMS service is running and the vault is unsealed.
External encryption uses an external KMS to store and manage KEKs. HCP for cloud scale supports any KMS that supports the open standard Key Management Interoperability Protocol (KMIP) v1.2 (not recommended), v1.3, or greater. You can configure connections to one primary and up to three secondary KMS servers. HCP for cloud scale can obtain KEKs from and store new KEKs on a primary KMS server (read/write access), and can obtain KEKs from a secondary KMS server (read access).
Synchronization of data across multiple KMS servers is the responsibility of the KMS administrator and outside the scope of HCP for cloud scale operations.
If HCP for cloud scale restarts, encryption and decryption functions are unavailable until an external KMS server connection is re-established. HCP for cloud scale automatically attempts to re-connect to already configured KMS server connections. The KMS servers must be online.
After either internal or external encryption is enabled on the system, users must turn encryption on for each bucket. Also, any objects placed in a bucket before encryption is enabled on the system and turned on for the bucket are not encrypted. To encrypt pre-existing objects once encryption is enabled and turned on, reload them.
Enabling internal encryption
You can enable internal encryption using the Object Storage Management application or a management API method.
- If you intend to use encryption, it's best to enable it before defining storage components so that all objects written to storage components are encrypted.
- If you have already defined storage components and intend to enable encryption, do not try to enable encryption from multiple accounts, or by multiple calls to the API method
/s3_encryption/set, simultaneously.CautionIf two accounts try to set the encryption flag simultaneously, either using the Object Storage Management application or the management API method/s3_encryption/set, existing storage components can become inaccessible.
Object Storage Management application instructions
Before you begin
Procedure
From the Object Storage Management application, select Settings > Encryption.
The ENCRYPTION page opens. The page displays information about the key management server options.In the Internal Key Management Server (KMS) panel, click Enable.
You are reminded that your selection is permanent, and reminded to scale the KMS service up to at least three instances.Click Continue to confirm your selection.
The Vault Unsealing window opens, displaying your initial root token and five unseal keys.NoteYou receive an error message if the KMS service is stopped, unable to complete the request, or not yet available. In this case, try again when the service is available.ImportantThis window is the only time that all of this data is ever available to you, and also the only time that the unseal keys should ever appear together. To minimize the possibility of multiple keys becoming unavailable, the best practice is securely distribute, encrypt, and store the unseal keys in separate locations.Do one of the following:
- Click Download Keys to download the initial root token and the five unseal keys in a single text file.
- Click the copy icons (
), for the initial root token and each unseal key, to save the token and keys in separate files.
Secure the token and unseal key files.
Click Continue.
You are warned that you won't have another opportunity to record the unseal keys and the initial root token.Click Continue.
A connection to the KMS service is established, the storage component encryption keys are generated and applied, and encryption is enabled.
Next steps
Related REST API methods
POST /s3_encryption/set
For information about specific API methods, see the MAPI Reference or, in the Object Storage Management application, click the profile icon and select REST API.
Providing unseal keys to KMS service
When internal encryption is enabled for a HCP for cloud scale system, the Key Management System service provides key encryption keys for storage components. If the service restarts, the vault is sealed and stored objects can't be decrypted. If the vault becomes sealed, you must provide a quorum of unseal keys (three of the five provided when encryption was first enabled) to reopen the vault and resume encryption and decryption.
Procedure
From the Object Storage Management application, select Settings > Encryption.
The ENCRYPTION page opens.In the UNSEAL VAULT INSTANCES section, enter the first unseal key into the Unseal key 1 field.
The key is validated. You can't leave the field blank.Enter a second unseal key into the Unseal key 2 field.
The key is validated. You can't leave the field blank. Each key must be different.Enter a third unseal key into the Unseal key 3 field.
The key is validated. You can't leave the field blank. Each key must be different.Click Unseal vault.
Results
Enabling external encryption
You can enable external encryption using the Object Storage Management application or a management API method.
If you intend to use encryption, it's best to enable it before defining storage components so that all objects written to storage components are encrypted.
Using an external KMS requires establishing mutual transport layer security (mTLS) authentication between your system and the KMS. The authentication requires an exchange of SSL certificates.
Object Storage Management application instructions
Before you begin
Before you start you need to know, for each KMS server:
- The name you intend to label the server with
- The host name or IP address
- The port (typically 5696)
- The TLS version used
- The KMIP protocol version
- The HTTPS ciphers
This procedure configures a connection to a KMS server. For configuration to succeed the configuration values must be accurate and the server must be online. The first server configured is designated the primary server; you can configure connections to one or two servers on this page. After you configure two server connections, you can configure connections to up to two more servers.
Procedure
From the Object Storage Management application, select Settings > Encryption.
The ENCRYPTION page opens. The page displays information about the key management server options.In the External Key Management Server (KMS) panel, click Enable.
The CONFIGURE EXTERNAL KEY MANAGEMENT SERVER window opens.In the Name field, type a label for the primary server. This name must be unique.
In the Hostname or IP Address field, type a host name or an IP address for the primary server.
In the Port field, type the server port number. The default is 5696.
(Optional) In the Allow TLS 1.2 field, select whether Transport Layer Security v1.2 is used. The default is No (a version later than v1.2 is used).
(Optional) In the KMIP Protocol field, select the KMIP version used:
- 1.3
- 1.4 (the default)
- 2.0
- 2.1
- 3.0
(Optional) In the HTTPS Ciphers section, edit the comma-separated list of ciphers used.
The default group of ciphers ensures interoperability with popular commercial key managers and an open-source implementation called PyKMIP. The default ciphers are: TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, SSL_RSA_WITH_3DES_EDE_CBC_SHA, TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256(Optional) In the SECONDARY KEY MANAGEMENT SERVER (OPTIONAL) section, repeat steps 3 through 8 for the secondary KMS server.
Click Save.
The connection is validated and you are prompted, "Server added successfully."(Optional) To configure a connection to another server, click Add KMS and repeat steps 3 through 10.
Results
Next steps
Related REST API methods
POST /kmip/add_server
For information about specific API methods, see the MAPI Reference or, in the Object Storage Management application, click the profile icon and select REST API.
Modifying an external KMS server connection
You can use the Object Storage Management application or an API method to modify the configuration of an external KMS server connection after defining it.
Object Storage Management application instructions
Procedure
From the Object Storage Management application, select Settings > Encryption.
The ENCRYPTION page opens. The page displays information about the key management configuration.Select a KMS server from the list, click the more icon (
The CONFIGURE EXTERNAL KEY MANAGEMENT SERVER window opens.
), and select Edit.Edit the information as necessary.
For more information about these fields refer to Enabling external encryption.Click Save.
The connection is updated.
Results
Related REST API methods
POST /kmip/update_server
For information about specific API methods, see the MAPI Reference or, in the Object Storage Management application, click the profile icon and select REST API.
Deleting an external KMS server connection
You can use the Object Storage Management application or an API method to delete the configuration of an external KMS server connection after defining it.
Object Storage Management application instructions
Procedure
From the Object Storage Management application, select Settings > Encryption.
The ENCRYPTION page opens. The page displays information about the key management configuration.Select a KMS server from the list, click the more icon (
The connection is removed.), and select Delete.
Results
Related REST API methods
POST /kmip/delete_server
For information about specific API methods, see the MAPI Reference or, in the Object Storage Management application, click the profile icon and select REST API.
Changing the primary external KMS server
You can use the Object Storage Management application or an API method to promote a secondary external KMS server to the primary role.
The HCP for cloud scale system has read/write access to the primary external KMS server, but only read access to secondary external KMS servers. With read access a KMS server can provide storage component KEKs. With write access new KEKs can be added.
Any external KMS server designated as a secondary server can be promoted to a primary server. Promoting a secondary server demotes the existing primary server to secondary status.
Normally, KEKs are synchronized between the primary server and any secondary servers. If a secondary server is promoted but has an incomplete set of KEKs, HCP for cloud scale tries to populate missing KEKs using cached KEKs. If the promoted server cannot produce a KEK and the KEK is not cached, then all data associated with the missing KEK remains unavailable until the previous primary server is repaired and populates the newly promoted primary server with the missing KEK.
Object Storage Management application instructions
Procedure
From the Object Storage Management application, select Settings > Encryption.
The ENCRYPTION page opens. The page displays information about the key management configuration.Select a secondary KMS server from the list, click the more icon (
The KMS server role changes to Primary.), and select Promote.
Results
Related REST API methods
POST /kmip/promote_server
For information about specific API methods, see the MAPI Reference or, in the Object Storage Management application, click the profile icon and select REST API.
Initiating rekeying
You can use the Object Storage Management application or an API method to initiate rekeying of key encryption keys (KEKs).
You can change (or rekey) KEKs for either internal or external encryption at any time. This function supports either routine rekeying according to a security policy or rekeying on demand (because, for example, of a data compromise). When you initiate rekeying, the system logs the time and reason for the request. The system displays a history of rekey operations.
Superseded keys are marked as deactivated but not removed.
Generating new KEKs takes several seconds for each encrypted storage component. Rewrapping object data encryption keys (DEKs) takes longer but proceeds in the background.
Object Storage Management application instructions
Procedure
From the Object Storage Management application, select Settings > Encryption.
The ENCRYPTION page opens. The page displays information about the key management configuration.Click Rekey.
The Rekey window opens.Select a reason for initiating the rekey operation:
- Routine rekey.
- Keys were COMPROMISED.
(Optional) If appropriate, type a further description of the reason for rekeying.
Click Continue.
Results
Related REST API methods
POST /s3_encryption/rekey
For information about specific API methods, see the MAPI Reference or, in the Object Storage Management application, click the profile icon and select REST API.