

The Secret Store is a required component that provides secure, auditable storage for Relativity secrets. The secrets can be system account credentials, database connect strings, an instance setting that contains confidential information, like your SMTP credentials, or TLS certificates. All confidential information is stored securely in the Secret Store database. The Secret Store can be accessed only by authenticated servers.
Note: Secret Store is required for running Relativity and must be accessible at all times.
The Secret Store includes a SQL Server database for storing the secrets and a service for managing the secrets and client access. The Secret Store service must run at all times and be accessible to all Relativity machines, web, agent, and SQL Server. The default port is 9090. We recommend that you install the Secret Store on a dedicated server and configure it for failover or high availability.
You can use your existing Service Bus or Agent Framework servers to host the Windows Secret Store Service.If you start experiencing high volume requests to the Secret Store service, you may consider a dedicated server with failover or high availability. For more information, see Configuring failover and high availability.
I do not want to buy another server to host the Secret Store. Where else can I install it?
My Secret Store server crashed and I have to replace the server. I still have my unseal key. Did I lose all my secrets?
You can still recover your secrets:
I lost my unseal key. What do I do now?
The Secret Store generates its own Certificate Authority and Client certificates that are used to register and authenticate client servers with the Secret Store over TLS. Certificate validation verifies that both client certificate and certificate authority are well formed and not expired.
After you initially install and configure the Secret Store, it is in a sealed state. The Secret Store API cannot read or write secrets until the Secret Store is unsealed by using the unseal key that is generated when the Secret Store service is configured.
Each Relativity machine must be whitelisted before it can be registered.
Before installing the Secret Store:
.NET version 4.8.1, 4.8, or 4.7.2
The following is the Secret Store-Relativity compatibility matrix:
Relativity Server 2022 | Relativity Server 2023 | Server 2024 | |
---|---|---|---|
Secret Store 1.6.1.2 | √ | √ | √ |
Secret Store 1.3.281.1 | √ | √ | √ |
Secret Store 1.2.985.1 | √ | √ | √ |
Secret Store 1.2.603.5 | √ | √ | √ |
Secret Store 1.2.376.7 | √ | √ | √ |
Secret Store 1.2.69.2 | √ | √ | √ |
Secret Store 1.2.4.3 | √ | √ | √ |
Secret Store enhanced with FIPS compliance changes.
Secret Store enhanced with security improvements.
Secret Store enhanced with general performance improvements.
You can now authenticate to Secret Store using an existing, external public key infrastructure (PKI) instead of a PKI provisioned by Secret Store.
The original release. The Secret Store is required for installing Relativity.
Follow these steps to install and configure the Secret Store in your Relativity environment:
Note: Whitelisting Relativity machines allows them to be registered, so that they can communicate with the Secret Store. Registering configures the machines for authenticating with the Secret Store by setting up the required certificates and registry values. If a machine attempts to register without being on the whitelist, registration fails. Do not whitelist and register the Secret Store server as its own client.
The Secret Store is installed by running the install.bat batch file provided in the installation package.
Parameter | Description |
---|---|
SERVICEUSERNAME | Optional. Username of the Windows account to run the Secret Store service. Defaults to LocalSystem. |
SERVICEPASSWORD | Optional. Password of the Windows account to run the service. Defaults to LocalSystem. |
SQLINSTANCESERVERNAME | Optional. The SQL Server instance name. Defaults to localhost. |
SQLUSERNAME | Conditional. If using SQL Server authentication, the user ID with permissions to create a new database on your SQL Server. Note: Make sure to specify a SQL Server user account, not a Windows account. |
SQLPASSWORD | Conditional. If using SQL Server authentication, the SQL Server user password. |
USEWINAUTH | Conditional. Configures the installer to use Windows authentication for SQL Server access. If this parameter is set to one, database credentials are not required. |
INSTALLDIR | Optional. Used to specify a custom directory that overrides the default installation directory. The default directory is %Program Files%\Relativity Secret Store. This parameter is available in Secret Store 1.0.314.5. |
Note: Depending on the installation package, the batch file name may vary. For example, it can include the Relativity version number: Relativity 9.6.xx.xx Secret Store BAT File.bat.
Install Secret Store on SQL01 SQL Server instance using Windows authentication:
.\Install.bat SQLINSTANCESERVERNAME=SQL01 USEWINAUTH=1
Install Secret Store on server.testing.corp\EDDSINSTANCE with username password credentials:
.\Install.bat SQLINSTANCESERVERNAME=server.testing.corp\EDDSINSTANCE SQLUSERNAME=Username SQLPASSWORD=Password
Install to a custom directory. Make sure that you include the trailing backslash.
.\Install.bat SQLINSTANCESERVERNAME=SQL01 USEWINAUTH=1 INSTALLDIR=E:\SecretStore\
Note: Windows Command interprets quoted paths that look like F:\Dir\Secret Store\ to end in a double quote. To avoid this error, either use Powershell to perform the installation, or double up the path separators: F:\\Dir\\Secret Store\\.
You can also use an additional command line parameter to repair an existing Secret Store installation:
.\Install.bat /repair SQLINSTANCESERVERNAME=server.testing.corp\EDDSINSTANCE SQLUSERNAME=Username SQLPASSWORD=Password
A successful installation creates the following artifacts:
If the console output displays a failure message, check the log file, InstallLog.txt for additional information.
There are two main points of failure:
Make sure SERVICEUSERNAME and SERVICEPASSWORD are correct unless you are going to run the service as the LocalSystem account.
After you install the Secret Store, you must configure the Secret Store service using the secretstore.exe command-line utility in C:\Program Files\Relativity Secret Store\Client.
Note: The CLI commands used with the Secret Store command line tool are all lowercase. Uppercase versions of these commands will not work.
For example, the following command is invalid:
.\secretstore SEAL-STATUS
This example has the correct form because it uses lowercase for the CLI command:
.\secretstore seal-status
You can specify the service port as the input parameter or use the default 9090 port. The program validates that port is available to host the service. See the following examples:
Configure Secret Store service without port 9090.
.\secretstore configure-service
Configure Secret Store service with default port 9090.
.\secretstore configure-service 9090
When running the configure-service command, you have the option of using a custom TLS certificate. On the machine running Secret Store, disable the use of TLS 1.0 and TLS 1.1. Enable TLS 1.2 on the machine running Secret Store. Secret Store is configured to work with TLS 1.2. For more information, see Microsoft's documentation
Note: You can only use a custom TLS certificate if you are using Secret Store 1.1.27.6 and above.
To use a custom TLS certificate:
.\secretstore.exe configure-service --serverCertificate=0000000000000000000000000000000000000000
Note: If you have already installed Secret Store and would like to migrate to a custom TLS certificate, the steps are the same.
After the installation completes, it starts the Relativity Secret store service and displays the unseal key for the Secret Store in the console. An Issued To <Server Name> Certificate has been generated under the /Personal folder of the Windows Certificates Management application.
Copy the key and save it in a password management system. Use the key to unseal the Secret Store in the next step.
Note: If you lose the unseal key, you lose all your previously stored secrets and they will no longer be recoverable. You must re-install the Secret Store to receive a new key.
The following can cause the Secret Store Service configuration to fail:
Error | Description |
This application could not be started. This application requires one of the following versions of the .NET Framework: .NETFramework,Version=v4.6.2 | Make sure .NET 4.6.2 or 4.7 is installed on the server. |
TLS certificate failed to bind to port (ServicePort). Error code: (error code). | Attempting to bind the TLS certificate to the specified port failed due to a Win32 exception. See the attached error code for more details. You can find descriptions for each error code here: https://msdn.microsoft.com/en-us/library/cc231199.aspx |
ServicePort argument is not valid. Outside valid port range. | The value of the passed in ServicePort parameter is outside the valid port range of 1-65535. |
ServicePort argument is not valid. Invalid integer. | The value of the passed in ServicePort parameter is not a number. |
Failed to change Secret Store start URL to start service over HTTPS. | To automatically restart the service over HTTPS, the installer changes the Windows service parameters inside the registry. If you receive this error, the installer was not able to find the key. The path to this key is setup automatically by windows when registering a new service and should be SYSTEM\CurrentControlSet\Services\Relativity Secret Store. Rerun the installer in repair mode to fix the registry settings. |
Did not receive timely response from Secret Store service while waiting for {status} status | While restarting the service over HTTPS, the command checks to make sure it is stopped and started correctly. If the service does not respond with a status change in less than 30 seconds, it throws this error. Check to make sure the service is set up correctly. |
Access denied to Windows Certificate Store. Run command with administrator privileges. | Writing the PKI certificates failed due to an access denied error. Make sure you are using an admin user. To help remedy this problem, you can also run the command prompt as an administrator. |
Access denied to registry. Run command with administrator privileges. | See above for access denied to Windows Certificate Store. |
The service cannot start. | There may be a local computer policy that denies the user account log on as a service permissions. Make sure the service has the permissions and then run the configure-service command again. |
Timeout occurred and no unsealed key was generated. | If you run the configure-service command and a timeout occurs, you can now rerun it to get your unseal key and client-registration.ps1 file. This functionality is available in Secret Store 1.0.314.5. |
After you configure and start the Secret Store service, the Secret Store is still sealed and cannot be used. You can verify the Secret Store status by running this command:
.\secretstore seal-status
To unseal the Secret Store, execute this command:
.\secretstore unseal <unseal key>
Verify that the Secret Store is unsealed:
.\secretstore seal-status
Note: Every time the Windows Secret Store service is stopped or restarted, you must unseal your Secret Store to allow Relativity to read and write secrets.
After unsealing the Secret Store, you can configure the client machines in your Relativity environment to allow them to access the Secret Store.
First, you must whitelist all machines in your Relativity environment. Then you must register them.
Note: Do not whitelist and register the Secret Store server as its own client. It is already whitelisted by default. Running registration on the server overwrites the already installed certificates, and you will have to reinstall the Secret Store.
Whitelist the machines by adding a single machine name, using wildcards, or by entering a space-delimited list of servers:
.\secretstore whitelist write MyMachine01.mycompany.corp
.\secretstore whitelist write *.mycompany.corp
.\secretstore whitelist write MyMachine01.mycompany.corp MyMachine02.mycompany.corp MyMachine03.mycompany.corp
To view whitelisted machines, run this command:
.\secretstore whitelist read
For more information about the available whitelist operations, see Command reference.
To register the client machines:
.\clientregistration.ps1
The registration installs the following certificates:
After registration is complete, the whitelist is no longer necessary. We recommend leaving the whitelist empty while not actively registering clients. To clean up the whitelist, use the CLI tool.
.\secretstore whitelist delete MyMachine01.mycompany.corp
.\secretstore whitelist delete *.mycompany.corp
.\secretstore whitelist delete MyMachine01.mycompany.corp MyMachine02.mycompany.corp MyMachine03.mycompany.corp
Before finishing up, the whitelist should be empty. You can check using the CLI tool:
.\secretstore whitelist read
Install Relativity. Note the difference in the response file after the installation is complete:
### The password for the EDDSDBO account on the SQL Primary SQL Instance you are installing to. ### The EDDSDBO login must have the same password for all Relativity Database servers (Primary or Distributed). ### If you are installing for the first time and this login doesn't exist, we will attempt to ### create it for you, so ensure this password passes any password strength restrictions that ### may be in place. Otherwise, this must match the existing account's password. ### E.g. EDDSDBOPASSWORD=MySecretPassword ### Value exported to Secret Store ### Domain (or Workgroup) and Username of the Relativity Service Account Windows login. ### This Windows login must already exist. ### E.g. SERVICEUSERNAME=domain\username ### Value exported to Secret Store ### Password for the SERVICEUSERNAME. ### E.g. SERVICEPASSWORD=MySecretPassword ### Value exported to Secret Store
The following secrets are migrated to the Secret Store:
For detailed information about the response file, see Relativity installation.
As of the May release, all Relativity secrets are being migrated to the Secret Store, and you are required to run the Secret Store to use Relativity at all times. Secret Store already supports failover and high availability, and you can set it up the your Relativity environment to ensure reliable system operation.
You can use the following configurations:
The following sections present the general steps for setting up these configurations. The steps may vary depending on your network, load balancer, and IIS version.
You can install the Secret Store on two distinct servers, a primary and a secondary.Then, in the event of a failure of the primary server manually switch over Relativity servers to use the secondary server. Note that this will result in Relativity being down until the manual switch-over is performed. Also, if the secondary Secret Store server fails, there is no backup service.
Note: For Secret Store versions 1.0.314.5 and 1.0.347.1, the secondary server re-initializes as if it was a first-time installation when no secrets exist and causes the first server to break. To avoid this issue, ensure that at least one secret exists in your system before configuring a second Secret Store server. You can do this by installing Relativity, or by executing the following command through the CLI tool: .\secretstore.exe secret write <SECRETNAME> <KEY>=<VALUE>. For example, you would enter your secret as the following: .\secretstore.exe secret write mysecret key=value. This workaround is no longer necessary in Secret Store 1.2.4.3.
After you install Secret Store on the secondary server and unseal it one time, a cluster is automatically formed. Cluster nodes will periodically send requests to each other, checking on seal status and availability. If a server is available but sealed, other secret store nodes will automatically unseal it.
The only time you will need to manually unseal a node is if there are no other cluster nodes up and unsealed. This assumes that Secret Store nodes are capable of making HTTPS requests to each other, and are not blocked by firewalls.
You can also configure the Secret Store for high availability on a load-balanced cluster of servers using an existing IIS server in your Relativity environment with a free load balancing add-on or a third-party load balancer.
The following instructions are for an IIS-based solution:
Note: You cannot use one of the Secret Store servers as the load balancer.
Note: For Secret Store versions 1.0.314.5 and 1.0.347.1, the secondary server re-initializes as if it was a first-time installation when no secrets exist and causes the first server to break. To avoid this issue, ensure that at least one secret exists in your system before configuring a second Secret Store server. You can do this by installing Relativity, or by executing the following command through the CLI tool: .\secretstore.exe secret write <SECRETNAME> <KEY>=<VALUE>. For example, you would enter your secret as the following: .\secretstore.exe secret write mysecret key=value. This workaround is no longer necessary in Secret Store 1.2.4.3.
Note: If you selected No in the previous step and no default rule was created, create the rule: Routing Rules > Advanced Routing > URL Rewrite.
https://localhost/v1/health/authenticators
What to do next:
Even though Relativity Support does not work with network devices such as F5 and NetScaler, Secret Store 1.1.27.6 and above are compatible with them.
Keep the following considerations in mind when using a network device with Secret Store:
Generate TLS certificates for each of your secret store servers. You can buy them with a public CA or generate them with a corporate CA. Either option works as long as the generating CA is trusted. TLS certificates should have the usage flag of Server Authentication set, a subject DNS name matching the FQDN of the server, and a subject alternative name containing the DNS names of both the server and the load balancer.
Once the certificate and associated private key are installed in the windows machine certificate store, set Secret Store to use the certificate by running:
.\secretstore.exe configure-service --serverCertificate=0000000000000000000000000000000000000000
Then, unseal as normal.
To avoid breaking authentication, ensure that your load balancer is not intercepting, terminating, or inspecting TLS traffic to the secret store. The name of this setting varies between products, so consult your load balancer manual, or contact a support representative at the vendor. The setting will usually be called Disable TLS Offloading or Enable TLS Pass-Thru.
A layer 4 load balancer will load balance at a layer beneath TLS, and can be safely used.
To update clientRegistration.ps1 to register with the load balancer:
Relativity infrastructure administrator tasks for maintaining the Secret Store include:
To perform these tasks, use the secretstore.exe command line tool or the Secret Store API. For more information, see Secretstore.exe CLI tool.
The unseal key is a 256-bit key. It is the primary key for Secret Store. If you lose it, the Secret Store is unrecoverable.
In most cases, we recommend that you store the unseal key separately from your Secret Store. If you store this key next to the Secret Store database, an attacker only has to steal one server to get all of your secrets.
For testing and development systems that do not contain sensitive data it is acceptable to store the unseal key on the Secret Store server.
For production systems, consider:
For security reasons, sometimes it may be necessary to change the unseal key. This operation decrypts and re-encrypts all encryption keys. It generates a new root key and destroys the old one. It can be very slow if there are hundreds of encryption keys and it is not transactional. We recommend that you perform it during off-peak hours.
Use the rekey command of the secretstore.exe CLI utility with the old unseal key:
.\secretstore rekey dGhpcyBpcyBhIHRlc3Qgc3RyaW5n=
When the operation completes, the console displays the new unseal key. Make sure to record the new key.
If you attempt to rekey your system and something happens during the operation that causes it to halt, for example, the server crashes due to hardware failure, you will not be able to unseal the Secret Store. You can roll back a failed rekey operation.
Note: This operation, by necessity, is unauthenticated, as the system is current not unsealable.
Send a PUT request to the following endpoint using any REST client:
<Secret Store server URL>:<port>/v1/system/rekey/recover
The request body must include the following:
{ "OldUnsealKey": "<the current unseal key>", "OtherUnsealKeys": [ "<the new unseal key generated in phase 1 of rekey>", "<additional keys, if rekey was attempted more than once>" ] }
When this request completes, the system is in a sealed state. Unseal the system with the original unseal key to complete the rollback. You may now attempt the rekey operation again.
Note: If you have multiple web servers, you must unseal all of them.
The Secret Store is considered sealed if it does not have access to the unseal key. Without the unseal key, the secret store is incapable of accessing any of the secrets in the database.
The Secret Store is considered unsealed if the unseal key is in memory on the Secret Store database. With the unseal key in memory, the Secret Store can decrypt the keyring, composed of one or more encryption keys, and with the decrypted keyring, it can decrypt and re-encrypt all of the secrets.
In general, you must seal the Secret Store only if you believe your network has been breached. Sealing Secret Store excises the unseal key from the server's memory and renders the Secret Store inert.
To change a secret in the Secret Store. For example, Relativity database password:
.\secretstore secret list /
Note: The list operation can be very resource-intensive, and we recommend that you perform it during off-peak hours.
.\secretstore secret write path\to\my\secret foo=bar foo2=bar2
This operation produces a new encryption key and will use it for new secret writes. It does not decrypt any data, and the old encryption keys are still in use. Because the encryption keys live only in memory unprotected, it is typically not required to rotate the encryption keys. You must do this only when the encryption key has encrypted so much data that the mathematics protecting your data starts to break down. To be conservative, do this once per terabyte of encrypted data.
Use the secretstore.exe rotate command:
.\secretstore rotate
When a secret store node is no longer desired, or it has crashed and is not going to be restored, you will need to remove the node from the cluster.
To do this, an API is available through REST.
Note: A new CLI command will be available in a future release.
Use the below Powershell snippet to remove a node from the cluster:
$SecretStoreRegistry = Get-Item -Path Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Relativity\SecretStore $BaseUri = $SecretStoreRegistry.GetValue("SecretStoreUrl") $AuthThumbprint = $SecretStoreRegistry.GetValue("ClientCertThumbprint") $AuthCert = (Get-ChildItem -Path Cert:\\LocalMachine\My\$AuthThumbprint)[0] $node = [Uri]::EscapeDataString("https://<server-fqdn>:<port>") Invoke-WebRequest -Uri ($BaseUri + "/v1/cluster/node?hostname=${node}") -Certificate $AuthCert -Method DELETE
Note: Capitalization matters.
To check the current state of the cluster, which includes a list of nodes, you can call the cluster health API with Powershell:
$SecretStoreRegistry = Get-Item -Path Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Relativity\SecretStore $BaseUri = $SecretStoreRegistry.GetValue("SecretStoreUrl") $AuthThumbprint = $SecretStoreRegistry.GetValue("ClientCertThumbprint") $AuthCert = (Get-ChildItem -Path Cert:\\LocalMachine\My\$AuthThumbprint)[0] Invoke-WebRequest -Uri ($BaseUri + "/v1/cluster/health") -Certificate $AuthCert
To upgrade the Secret Store using a new installation package:
Note: When you configure the Secret Store service after an upgrade, a new unseal key is not generated. You must use the original unseal key.
Note: You don't have to re-register client machines after a Secret Store upgrade.
You may experience the following problems with the Secret Store:
Note: These instructions are for Secret Store release 1.0.278.9 and later. Secret Store is backwards-compatible, and we recommend that you always use the latest available installer.
To migrate the Secret Store to a different server and a database instance for disaster recovery:
To completely uninstall the Secret Store:
The secretstore.exe command line tool is used to interact with the Secret Store. It is installed alongside the Secret Store service in C:\Program Files\Relativity Secret Store\Client. The tool can be used to configure the Secret Store or client machines to access the Secret Store. It can also be used for most Secret Store administration and maintenance tasks.
Note: The CLI commands used with the Secret Store command line tool are all lowercase. Uppercase versions of these commands will not work.
For example, the following command is invalid:
.\secretstore SEAL-STATUS
This example has the correct form because it uses lowercase for the CLI command:
.\secretstore seal-status
Display the executable version:
.\secretstore --version
Display secretstore.exe help:
.\secretstore --help
Unseal the Secret Store:
.\secretstore unseal <unseal key>
Check seal status:
.\secretstore seal-status
Starts the Secret Store Windows service on the specified port. Initializes the Secret Store database if it already has not been set up. Sets up the required certificates and registry settings to run Secret Store and the CLI tool. Does not require the client authentication.
You can also use the repair mode to regenerate the PKI infrastructure in the database. If your secret store server crashed and you lose your client certificate, this command will set you up new root, intermediate, and client certificates. You will be prompted for the unseal key and a confirmation to continue the repair. Other than the certificate regeneration, the repair operates identically to the regular service configuration. Once the repair runs, you must re-register all client machines that connect to the Secret Store.
Parameters:
Example:
.\secretstore configure-service 9090
.\secretstore configure-service --repair
Configures a server to access a Secret Store by installing the following:
Does not require the client authentication. Must be run as administrator.
Example:
.\secretstore register 5555 --url=https://mysecretstore.testing.corp:9090 --tlsCert=26f8b1a83e299874a75092ca68c4b681dc41f9f0
Generates a new unseal key, and rekeys the system to use it. Requires client authentication.
Parameters:
Note: Failure to retain the new unseal key makes your system unusable. There is no way to recover without the unseal key.
Example:
.\secretstore rekey dGhpcyBpcyBhIHRlc3Qgc3RyaW5n=
Rotates the data encryption key. Requires client authentication.
Example:
.\secretstore rotate
Seals the Secret Store so that secrets cannot be read or written until it is unsealed. Requires client authentication.
Example:
.\secretstore seal
Returns the current seal status of the Secret Store, sealed or unsealed. Does not require client authentication.
Example:
.\secretstore seal-status
CRUD and list operations for the secrets in the Secret Store.
Parameters:
Examples:
.\secretstore secret read path\to\my\secret
.\secretstore secret write path\to\my\secret foo=bar foo2=bar2
.\secretstore secret list path\to\my\secret
.\secretstore secret delete path\to\my\secret
Removes the certificates and registry values set during registration. Does not require client authentication. Must be run as administrator. Unregistering on the Secret Store service corrupts the trust chain for HTTPS hosting.
Example:
.\secretstore unregister
Unseals the Secret Store, allowing secrets to be read and written. Does not require client authentication.
Note: Starting in 1.2.12.5, the unseal key may be omitted from the command line. If omitted, you will be prompted for the unseal key. This behavior helps keep the unseal key out of logs. This change is isolated to the command line tool. If you are using an older version of Secret Store and want this enhancement, contact Relativity Support.
Parameters:
Example:
.\secretstore unseal dGhpcyBpcyBhIHRlc3Qgc3RyaW5n=
Configures the registration white list for clients’ self-registration with the specified authority. Currently registers only at with the Relativity-Intermediate authority. Requires client authentication.
Parameters:
url—Optional. The URL of the Secret Store. If not specified, the value is loaded from registry.
clientCert—Optional. Client certificate thumbprint to use for authentication with Secret Store. Read from the local machine store.
Examples:
.\secretstore whitelist write *.mycompany.com
.\secretstore whitelist delete MyMachine1.mycompany.com
Configures the auditing level of the secret store service. Defaults to BestEffort. Requires client authentication.
Parameters:
Some actions are never audited regardless of the above setting, like the ping action that Relativity uses to check connectivity.
Examples:
.\secretstore auditing-level read
.\secretstore auditing-level write StateChange
On this page
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!