Encrypt a Riva Connection's Credentials

Rawan Maarouf
Rawan Maarouf
  • Updated

In Riva, all connection details that are used during the authentication process are encrypted. This includes and is not limited to fields like target host address, credentials (user name and password), and OAuth Refresh Tokens.

In order to prevent unauthorized access to the connection details that are persisted in the local Riva server file system, these details are encrypted. Three encryption types are available.

Certificates

With Riva 2.4.43 or higher, a default certificate can be defined and changed at any point. Once defined, this certificate is used to encrypt all new connections. The certificate's private keys are used for the asymmetric encryption process. After a connection has been created, the certificate can be replaced or changed, but this is possible only if the current certificate is available. After a connection has been encrypted with a specific certificate, if that certificate is lost or removed from the system, the connection will be unavailable to the Riva application.

The certificates themselves are stored in the Microsoft Windows Certificate Store. The Windows Certificate Store is the same secure certificate storage used by other Microsoft technologies like Microsoft Exchange and Microsoft IIS, including third-party applications like Google Chrome for Windows.

  • Default Certificate: A default certificate that will be used for encrypting any new connection. The details of the certificate that are used during the creation process are copied to the new connection. Once created, the certificate must be managed either on a per-certificate basis, or the Certificate Update Tool can be used to bulk replace the certificate. To configure default encryption.

Note: The certificates configured, used, defined, and referred to in this article are for "local" encryption of the connection details. These are unrelated to and independent of any kind of SSL, TLS, or HTTPS communication. For communication-related certificate questions, see Secure HTTP communication certification validation.

AmazonKMS

Amazon Key Management Service. In Riva 2.4.48 or higher, instead of managing keys on individual machines in a multi-instance deployment or migrating certificates along with Riva instances, it is possible to manage them in a central location in AWS. See Default persistent credential encryption and Per-connection override credential encryption.

Default Persistent Credential Encryption for New Connections

To configure the default persistent credential encryption for new connections:

  1. In the Riva Manager application, on the menu bar, select Tools, and choose Default Persistent Connection Credential Encryption.
  2. In the window that appears, configure the following settings:


Default Persistent Connection Credential Encryption

Encryption Type:

Default: (Riva 2.4.48 or higher.) The default Windows encryption method is used to encrypt the credentials of new connections.

Certificate: (Riva 2.4.43 or higher.)

  • Certificate Name: The name of the default certificate that is used to encrypt the credentials of new connections. The recommended RSA key size is 2048 bits. It must be at least 1024 bits.

    Note: Certificates that use Cryptography Next Generation (CNG) API require .NET 4.6 or higher.

    Microsoft Graph Tip: Microsoft Graph supports 4096-bit RSA keys for application authentication, so a 4096-bit key should not cause issues if the certificate is properly formed and exported.

    • Graph Compatibility: Microsoft Graph key credentials for applications support RSA key sizes between 2048 and 4096 bits.

    • Best Practices: While 4096-bit keys offer high security, they are more computationally expensive than 2048-bit keys, which may slightly impact performance, though they are perfectly valid.

    • Requirements: Ensure the certificate is in Base64-encoded X.509 format and you are submitting only the public key information (key value) when updating the application registration. 

    If you are encountering issues, they are more likely related to certificate expiration, formatting (base64/PEM), or the application permissions, rather than the 4096-bit key length itself. 

  • Browse button Three-dots-(selection-button-for-persistent-credential-encryption).png: Opens the Windows Security Certificate Selection window to select a certificate.
    Tip: Before selecting Three-dots-(selection-button-for-persistent-credential-encryption).png, partially type the certificate name in the Certificate Name field to filter the results.

  • Store Name: The name of the Certificate Store that contains the certificate used to encrypt the credentials.
    Note: The identified certificate must be present in the Certificate Store for the connection to be used during the synchronization.

  • Store Location: The default value is LocalMachine. This is because the Riva Sync Service is installed by default to execute as a "Local System", which does not have access to the CurrentUser store. In order to use the CurrentUser store, the "Log On As" of the Windows Service must be configured to have access to the certificate. At a minimum, both the "Log On As" service user and the user managing Riva would need to have the certificate installed in the CurrentUser store in order to manage Riva. This additional complexity is error-prone and effectively requires that all users who access the server must use the same user identity to manage Riva.

  • View Certificate: Displays the currently identified certificate.

  • Export Settings: Exports only the values of the Certificate Name, Store Name, and Store Location fields. The exported information does not contain the certificate itself or any private keys. Exporting does not modify the certificate.

  • Import Settings: Imports only three values and places them in the Certificate Name, Store Name, and Location fields. The certificate itself is not imported.

  • Export App.Settings Format: Exports the advanced options (keys and values) used by Riva to configure the default persistent connection credential encryption. The keys and values are copied from the RivaApp.exe.config appSettings file. They are exported in an XML file that has a .cfg extension. You can rename this file and choose where to export it.

    • Benefit: The exported XML file can be useful for a Riva admin who wants to replicate the configuration of a Riva server on another one: the exported keys and values can be copied to the other server.

  • Certificate Update Tool: Opens a window where the certificate can be mass replaced. This tool is usually used when many (support thousands) existing connections are configured with an expired certificate that must be replaced.

AmazonKMS: (Riva 2.4.48 or higher.) Amazon Key Management Service. Instead of managing keys on individual machines in a multi-instance deployment or migrating certificates along with Riva instances, it is possible to manage them in a central location in AWS. The settings are saved in the appSettings RivaApp.exe-config file.

Default Riva AmazonKMS Settings Code Examples in the appSettings RivaApp.exe.config File
CmkArn: Used by default for all new connections. Amazon resource name (Arn) for the Customer Master Key (Cmk). It points to the Master Key that is used to create, encrypt, and decrypt the data keys that will be used to encrypt new connections. 

The CmkArn value is added to the Riva instance's appSettings file in two places. See the bolded XML code in the example:		 <?xml version="1.0" encoding="utf-8"?> <configuration> <appSettings> <add key="Encryption.Provider" value="AmazonKMS" /> <add key="Encryption.Kms.CmkArn" value="[any name, such as AwsKmsEncryption]" /> </appSettings> <connectionStrings> <add name="[any name, such as AwsKmsEncryption]" connectionString="[see the examples on the following rows]" providerName="AmazonKMS" /> </connectionStrings> </configuration>
Configure AWS Connection Settings: Opens the Configure AWS Connection Settings window, where three configuration options are available: The following examples show only the contents of the <connectionStrings> tag.
  • Use Instance Profile: The AWS access keys are obtained from the EC2 instance profile. For more information, see Using instance profiles.
 <add name="[any name, such as AwsKmsEncryption]" connectionString="UseInstanceProfile=True" providerName="AmazonKMS" />
  • Profile Name: The name of an AWS CLI profile stored locally that provides the AWS access keys. 

    The Log On As of the Windows Service must have the specified profile configured in the AWS configuration files. At a minimum, both the "Log On As" service user and the user managing Riva need to have the specified profile configured in the AWS configuration and credential files stored at respectively %UserProfile%\.aws\config and %UserProfile%\.aws\credentials. 

    For more information, see AWS CLI configuration and credential files and Named profiles.
 <add name="[any name, such as AwsKmsEncryption]" connectionString="Profile=[name-of-AWS-CLI-Profile]" providerName="AmazonKMS" />
  • Access Key + Secret: The credentials required to connect to an AWS KMS server.
 <add name="[any name, such as AwsKmsEncryption]" connectionString="AccessKey=&quot;[value of the Access Key]&quot;;SecretKey=[value of the Secret Key]" providerName="AmazonKMS" />

Export App.Settings Format: Exports the advanced options (keys and values) used by Riva to configure the default persistent connection credential encryption. The keys and values are copied from the RivaApp.exe.config appSettings file. They are exported in an XML file that has a .cfg extension. You can rename this file and choose where to export it.

  • Benefit: The exported XML file can be useful for a Riva admin who wants to replicate the configuration of a Riva server on another one: the exported keys and values can be copied to the other server.
  

 

Per-Connection Override Encryption

To configure persistent credential encryption for one connection:

  1. In the Riva Manager application, on the menu bar, select Setup.
  2. In the right pane, double-click a connection to edit it.
  3. In the window that appears, select the Advanced Options tab.
  4. On the Advanced Options page, configure the following settings:


Persistent Connection Credential encryption:

Encryption Type:

Default: (Riva 2.4.48 or higher.) The default Windows encryption method is used to encrypt the credentials of this connection.

Certificate: (Riva 2.4.43 or higher.)

  • Certificate Name: The name of the default certificate that is used to encrypt the credentials of this connection. The recommended RSA key size is 2048 bits. It must be at least 1024 bits.
    Note: Certificates that use Cryptography Next Generation (CNG) API require .NET 4.6 or higher.

    Microsoft Graph Tip: Microsoft Graph supports 4096-bit RSA keys for application authentication, so a 4096-bit key should not cause issues if the certificate is properly formed and exported.

    • Graph Compatibility: Microsoft Graph key credentials for applications support RSA key sizes between 2048 and 4096 bits.

    • Best Practices: While 4096-bit keys offer high security, they are more computationally expensive than 2048-bit keys, which may slightly impact performance, though they are perfectly valid.

    • Requirements: Ensure the certificate is in Base64-encoded X.509 format and you are submitting only the public key information (key value) when updating the application registration. 

    If you are encountering issues, they are more likely related to certificate expiration, formatting (base64/PEM), or the application permissions, rather than the 4096-bit key length itself. 

  • Browse button Three-dots-(selection-button-for-persistent-credential-encryption).png: Opens the Windows Security Certificate Selection window to select a certificate.
    Tip: Before selecting Three-dots-(selection-button-for-persistent-credential-encryption).png, partially type the certificate name in the Certificate Name field to filter the results.

  • Store Name: The name of the Certificate Store that contains the certificate used to encrypt the credentials.
    Note: The identified certificate must be present in the Certificate Store for the connection to be used during the synchronization.

  • Store Location: The default value is LocalMachine. This is because the Riva Sync Service is installed by default to execute as a "Local System", which does not have access to the CurrentUser store. In order to use the CurrentUser store, the "Log On As" of the Windows Service must be configured to have access to the certificate. At a minimum, both the "Log On As" service user and the user managing Riva would need to have the certificate installed in the CurrentUser store in order to manage Riva. This additional complexity is error-prone and effectively requires that all users who access the server must use the same user identity to manage Riva.

  • View Certificate: Displays the currently identified certificate.

  • Export Settings: Exports only the values of the Certificate Name, Store Name, and Store Location fields. The exported information does not contain the certificate itself or any private keys. Exporting does not modify the certificate.

  • Import Settings: Imports only three values and places them in the Certificate Name, Store Name, and Location fields. The certificate itself is not imported.

  • Export App.Settings Format: Exports the advanced options (keys and values) used by Riva to configure the persistent connection credential encryption for this connection. The keys and values are copied from the RivaApp.exe.config appSettings file. They are exported in an XML file that has a .cfg extension. You can rename this file and choose where to export it.

    • Benefit: The exported XML file can be useful for a Riva admin who wants to replicate the configuration of a Riva server on another one: the exported keys and values can be copied to the other server.

AmazonKMS: (Riva 2.4.48 or higher.) Amazon Key Management Service. Instead of managing keys on individual machines in a multi-instance deployment or migrating certificates along with Riva instances, it is possible to manage them in a central location in Amazon.

Per-Connection Settings Code Examples in the appSettings RivaApp.exe.config File

CmkArn: Used to encrypt this connection. It overrides the default CmkArn (Amazon resource name (Arn) for the Customer Master Key (Cmk)). The CmkArn points to the Master Key that is used to create, encrypt, and decrypt the data keys that will be used to encrypt this connection. 

The CmkArn value is added to two files:

  • the Riva instance's appSettings .config file, and
  • either the Omni.Riva.CrmAgentEx64.exe.config file or the Omni.Riva.CrmAgentEx.exe.config file.

In each file, it is added in two places. See the bolded XML code in the example:

 <?xml version="1.0" encoding="utf-8"?> <configuration> <appSettings> <add key="Encryption.Provider" value="AmazonKMS" /> <add key="Encryption.Kms.CmkArn" value="[any name, such as AwsKmsEncryptionForConnection2]" /> </appSettings> <connectionStrings> <add name="[any name, such as AwsKmsEncryptionForConnection2]" connectionString="[see the examples on the following row]" providerName="AmazonKMS" /> </connectionStrings> </configuration>

Override connection string name: (Default: [Cleared].) If you want to override the default connectionString and specify the connectionString for this connection, select the check box and enter the string in the text box. The connectionString entered here will override the default connectionString. The connectionString value is added to two files:

  • the Riva instance's appSettings .config file, and
  • either the Omni.Riva.CrmAgentEx64.exe.config file or the Omni.Riva.CrmAgentEx.exe.config file.

The override connectionString can take any of these three forms:

 <add name="[any name, such as AwsKmsEncryptionForConnection2]" connectionString="UseInstanceProfile=True" providerName="AmazonKMS" /> <add name="[any name, such as AwsKmsEncryptionForConnection2]" connectionString="Profile=[name-of-AWS-CLI-Profile]" providerName="AmazonKMS" /> <add name="[any name, such as AwsKmsEncryptionForConnection2]" connectionString="AccessKey=&quot;[value of the Access Key]&quot;;SecretKey=[value of the Secret Key]" providerName="AmazonKMS" />

 

Additional Resources

TechNet: How private keys are stored.