Manage your archive keystore
Overview
In the Code42 cloud you can use an external keystore to maintain copies of the encryption keys that secure your users' backed-up data.
While the keys reside securely on your users' devices for use in encrypting and decrypting files, you can store a copy of the encryption keys separately from the Code42 cloud, in a Vault keystore system. Vault is a third-party application specifically built to secure secrets. This article summarizes the value of maintaining an external keystore and describes how to manage your external keystore.
- To learn about the limited functionality of a keystore in maintenance mode, see Functions unavailable during migration.
- To learn about keystore-offline alerts, see Troubleshoot your keystore connection.
- To configure your Vault server to work with the Code42 cloud, see Create a Vault server.
Considerations
- You must have the Customer Cloud Admin role to manage your keystore.
- External keystores are available to Code42 cloud customers only.
External keystores are not available in the Code42 federal environment.
Keystore types
Code42 Vault keystore: For new customers, copies of encryption keys are held, by default, in an external Vault keystore owned and operated by Code42.
Self-Administered Vault: You can manage copies of your users' encryption keys in your own private keystore.
Legacy keystore: For customers who connected to the Code42 cloud before version 6.0, copies of keys reside in the database in the Code42 cloud. For additional security, legacy customers can move copies of the keys from the Code42 cloud database to the Code42 Vault keystore or to a private keystore.
Archive key storage in Vault
Code42 apps encrypt all their device data before sending it to a Code42 backup archive. The encryption keys are unique to each user. To isolate keys from data and from other customers of the Code42 cloud, as of version 6.0 the Code42 cloud stores copies of archive keys at a Vault server managed by Code42 but otherwise separate from the Code42 cloud's database.
- Vault is a widely trusted server and storage technology specifically built to secure secrets.
- For each customer, the Code42 cloud creates one unique Vault user. That user can read and write keys for that one organization only.
- Vault authenticates each user with a unique SSL certificate. All requests to Vault can be logged and monitored.
- In the event you no longer want to maintain a private instance of Vault, you can easily move your keystore back to Code42's Vault.
- The traffic load on the server-keystore connection is light. The Code42 cloud writes a copy of an encryption key to Vault only when a new user starts backing up. The Code42 cloud reads a key only for restoring data via the Code42 console or the Code42 API, and for archive maintenance.
Failure of a keystore connection does not prevent Code42 apps from backing up data or restoring backed-up data.
Access keystore settings
To identify, monitor, and manage your keystore, access the Code42 console's keystore settings.
- Sign in to the Code42 console.
- Select Administration > Environment > Keystore.
The URL, connection status, and connection reliability are only reported for self-administered keystores.
Troubleshoot your keystore connection
If you use a private, self-administered keystore, the Code42 cloud tests its connection to your keystore every minute.
In the keystore settings, the Connection Status reports the result of the most recent test.
If the status is Offline, the reason and duration also appear.
When connection to a self-administered keystore fails for five minutes, Code42 emails an alert to the organization's administrators. Code42 resends that alert every 24 hours until the connection is restored. When the connection has resumed for five minutes, Code42 emails a success message to the administrator. See Email alerts for more information.
The following table lists offline reasons, descriptions, and steps to resolve the issue.
Offline reason | Details | Steps to resolve |
---|---|---|
Host unavailable |
The keystore did not respond to the Code42 cloud's requests.
Possible error messages:
|
|
Unable to authenticate |
The Vault server did not allow the Code42 cloud to access the data.
Possible error messages:
|
Create and upload to the Code42 cloud a new PFX or P12 certificate file and password for your keystore. |
No request | The Code42 cloud was not able to test the connection. |
|
Unknown | A migration has just completed. There is not yet enough data to inform a status report. | Wait 5 minutes. Refresh the browser page. |
Connection reliability and the timeline below report the result of the last hour's tests:
Keystore is online
Keystore is offline
Unknown (the server failed to test)
The time stamps report your local time. To refresh the connection data, reload the browser page.
While a keystore is offline
In the rare case that the Code42 cloud cannot connect to an organization's keystore, data backups do continue. But you and your users will not be able to:
- Create new users or register as a new user
- Change account passwords
- Change key passwords or security questions for archive key password security
- Log-in for the first time using SSO authentication
- Change a user security option
- Restore backed up data via the Code42 console or the Code42 API
Individual Code42 apps will, however, be able to restore data to their devices. - Generate security tools reports
After a Vault outage
If Vault experiences an outage, upon restoration of service your Vault server may be sealed. To return to normal operation, unseal the Vault server. For more information on how to diagnose Vault server issues, see Hashicorp's documentation.
Edit a keystore URL or update a certificate
If you have a self-administered private keystore, you can redefine the URL of the Vault server and provide a new security certificate (a PFX or P12 file). You might want to do so if:
- You have made a DNS or subdomain change to your Vault's address.
- You changed an encryption key at your Vault server and so created a new certificate.
- You created a new administration certificate to replace one that was about to expire.
To edit a keystore or update a certificate:
- From the action menu in the upper-right, select Edit Keystore.
The keystore settings appear. The URL field is pre-populated with your current Vault address. Changing the URL is optional (for example, you might want to use the same address but upload a new certificate file). - If you need to change the URL of your Vault server, start with
https://
and include the hostname and port number.
If you provide a new URL, it cannot contain a path (only protocol, host, and port), and it must be a public DNS address (it cannot be IPv4 or IPv6). - Provide your PFX or P12 certificate file and its password.
- Upload a valid PKCS12 certificate for your Vault. For details, see the instructions for creating a Vault keystore.
- The file name extension is not significant. A .PFX or .P12 file extension is not required.
- Your certificate file may or may not require a password, depending on what you specify when you create the file.
- URLs and certificate files are typically matched pairs, but you may want to change a URL without changing the certificate. For example, your certificate might use a wildcard to protect multiple subdomains, and you might change the Vault URL to use a new subdomain. In that case, change the URL; don't change the certificate.
- Select Continue.
The Code42 cloud will verify that:- It can connect to the URL you specified.
- The certificate file allows the Code42 cloud to authenticate and access your Vault.
Migrate keys to a new keystore
You can move your users' archive encryption keys from one Vault keystore to another, or from the legacy database to a Vault keystore.
- From the action menu in the upper-right, select Migrate Keystore.
- For the type, select either a self-administered private keystore or Code42's Vault.
Migrating to the legacy database is not possible. - If you select a self-administered keystore:
- Provide the URL for your Vault server. Start with
https://
and include the hostname and port number.
The URL cannot contain a path (only protocol, host, and port), and it must be a public DNS address (it cannot be IPv4 or IPv6). - Provide your PFX or P12 certificate file and its password.
- Provide the URL for your Vault server. Start with
- Upload a valid PKCS12 certificate for your Vault. For details, see the instructions for creating a Vault keystore.
- The file name extension is not significant. A .PFX or .P12 file extension is not required.
- Your certificate file may or may not require a password, depending on what you specify when you create the file.
- Provide one email address to receive notice about the success or failure of the migration.
- Select Continue.
The Code42 cloud will verify that:- It can connect to the URL you specified.
- The certificate file allows the Code42 cloud to authenticate and access your Vault.
View migration progress
When migration starts, progress information appears via:
- A yellow banner at the top of the Code42 console shows that the keystore is in maintenance.
The banner disappears when migration completes with either success or failure.
You may have to refresh the browser to see the banner. - The Archive Keystore monitoring view changes to a progress report:
Migration time can vary. For a rough estimate, figure one second per user, or 3 hours for 10,000 users.
Once migration completes or fails, the banner goes away and the monitoring view returns.
Functions unavailable during migration
During migration, the Code42 cloud continues to read (but not write) keys from the source keystore. Data backups do continue. But you and your users will not be able to:
- Create new users or register as a new user
- Change account passwords
- Change key passwords or security questions for archive key password security
- Log in for the first time using SSO authentication
- Change a user security option
Attempts to perform those operations will generate a system error at the Code42 console.
Migration success or failure
In no case does a migration partially complete. Either all keys get transferred and verified, or the migration fails and the Code42 cloud continues to use the source keystore.
- When a migration succeeds, the Code42 cloud attempts to remove data from the source keystore.
- When migration fails, the Code42 cloud attempts to remove data at the destination keystore. You can re-start the migration process.
View your keystore history
The keystore history log contains information about keystore configuration, editing, and migration operations. It is only available after you have edited or migrated your organization's keystore.
From the action menu in the upper-right, select View Keystore History.
The history table reports:
- Date & Time: Your local time.
- User: The ID of the Code42 console user who initiated the event.
The user "system" indicates the Code42 cloud. - Action Details:
- Migration failed: source not reachable: The Code42 cloud could not connect with the keystore that data should move from.
- Migration failed: destination not reachable: The Code42 cloud could not connect with the keystore that data should move to.
- Migration failed: destination data failed verification: After writing a key to the destination, the Code42 cloud could not read it and match it to the source. The entire migration is abandoned and the Code42 cloud attempts to delete all data from the destination.
- Migration canceled: migration process stalled: Migration stopped before it completed, most likely because the Code42 cloud suffered an internal server error. The entire migration is abandoned and the Code42 cloud attempts to delete all data from the destination.
Email alerts
Two emails to administrators announce the failure and restoration of a Code42 cloud's connection to a private keystore.
From: The Code42 Security Center To: <Administrator> Subject: Error: Keystore connection failure Error: The Code42 cloud can no longer communicate with your keystore for backup archives.
From: The Code42 Security Center To: <Administrator> Subject: Success: Keystore connection resumed Success: The Code42 cloud is now communicating with your keystore for backup archives.
When an administrator at the Code42 console starts a keystore migration, three emails announce when migration starts, and when it either succeeds or fails. The administrator provides the email address as a part of configuring the migration.
From: The Code42 Security Center To: <Administrator> Subject: Keystore Migration Starts Your Code42 archive encryption keys are now migrating from one keystore to another.
From: The Code42 Security Center To: <Administrator> Subject: Keystore Migration Succeeds Your Code42 archive encryption keys now reside at their new location.
From: The Code42 Security Center To: <Administrator> Subject: Error! Keystore Migration Failed Error! Keystore migration failed.
External resources
- Hashicorp: Introduction to Vault