Setting up encryption

When you use the encrypt option for a secure context, the secured information is stored in an encrypted format. This ensures that it cannot be viewed by most people, but may be retrieved by authorized personnel who have access to the related private key. Encrypted waveforms, and call logs that include encrypted material, end in a *.enc extension.

To support encryption in your application, you must first generate the public and private keys. You must then copy the public key to your application’s session.xml file, and secure the private key. For information on decrypting the encrypted logs and waveforms, see Decrypting encrypted files.

Using a separate mechanism, you can also encrypt the values of sensitive parameters. See Encrypting sensitive configurations.

Note: Sensitive information in Voice Browser service diagnostic logs is suppressed, not encrypted.

Samples for test purposes

At installation, Voice Platform includes a sample example_session.xml file that uses example public and private encryption keys that you can use for testing purposes. These items may be found at the following locations:

• Sample session.xml file: %NSSSVRSDK%/config/example_session.xml
• Sample public key: %NSSSVRSDK%/certs/example_key.prv
• Sample private key: %NSSSVRSDK%/certs/example_key.pub

To use these samples for testing, assign the location of the example_session.xml file (formerly default_session.xml) as the value for the server.default.session.xml.path service property on the Speech Server.

Note: Since these keys are installed with Voice Platform and thus generally available, they cannot be considered secure. It is strongly recommended that you use them for testing and illustration only. For actual production, generate your own keys as described below.

Generating the public and private keys

To generate the encryption keys, use the nr_gen_encryption_keys utility. This tool is located in the %SWISRSDK%\amd64\bin directory.

To use the utility, specify the files where it places the public and private keys. Optionally, specify a password and the length for the private key:

nr_gen_encryption_keys -pub publicKeyFile -prv privateKeyFile 

    [-pass privateKeyPassword] 

    [-len keyLength] 

For example:

nr_gen_encryption_keys -pub myPublicKey -prv mySecretKey 

    -pass abracadabra 

This command generates two files in the current directory:

• The myPublicKey file contains the public key to be used for encryption.
• The mySecretKey file contains the private key. This file is itself encrypted using OpenSSL, and “abracadabra” is the password required to decrypt it.

The private key (and its password, if applicable) is necessary for decryption of the encrypted logs and waveforms. Make sure that the private key is made available only to authorized personnel.

Once you have generated the keys and secured the private key, you must include the public key in your application’s session.xml file, as described in the next section.

Putting the public key in the session configuration file

The session.xml session configuration file includes a <logging> section that lists parameters affecting encryption. To use encryption in your application, you must assign the pathname of your public key to the encryption_key parameter in this section:

<?xml version="1.0"?>

<sessionconfig version="1.0.0" xml:base="${APP_PROVISION_DIR}">

  <sessionparameters>

  <global>

    ...

  </global>

    <logging>

      <param name="encryption_key"><value>myPublicKey</value></param>

    </logging>

    <speechrecog name="NR10">

      <param name="swirec_default_language"><value>en-US</value></param>

      ...

    ...

  ...

</sessionconfig>

The Speech Server can then use this public key to encrypt information in the application.

Note: If an application attempts an encryption when no public key is specified in the session.xml file, Voice Platform generates an alarm, and all encrypted data is lost. Events are still replaced with _ENCRYPTED in the call logs, but no encrypted data is written to the log. The *.wav.enc audio files are still generated, but do not contain actual audio.

Optionally, you can also specify a simple label for the public key by assigning it to the encryption_key_tag parameter:

    <logging>

      <param name="encryption_key"><value>myPublicKey</value></param>

      <param name="encryption_key_tag"><value>myLabel</value></param>

    </logging>

This label is written to files encrypted with the key, making it easier to keep track of which public key was used to encrypt a given set of files.

You can also optionally specify the encryption method, by specifying a value for the internal_encryption parameter:

    <logging>

      <param name="encryption_key"><value>myPublicKey</value></param>

      <param name="encryption_key_tag"><value>myLabel</value></param>

      <param name="internal_encryption"><value>AES-256</value></param>

    </logging>

The parameter takes one of two possible values: AES-192 (the default), or AES-256.

Rotating the encryption key

For extra security, you can periodically change the encryption key. This practice is known as key rotation, and it is intended to reduce risk, in case unauthorized users gain access to your private key. Key rotation limits the data vulnerable to a compromised key.

Changing the key is simple:

1. Back up the existing data.
2. Generate a new pair of public and private keys as described above.
3. Change the encryption_key in the session.xml file to the new public key.

After you update the session.xml file, all subsequent encryptions use the new public key, and require the new private key for decryption.

Example of an encrypted entry

The encrypted material in a call log file is all appended to a single Enc event that appears at the end of the file.

TIME=20101111111524975|CHAN=0a03168f_00003b68_4cdc1628_0002_0001|
EVNT=Enc|HDR=AQCAhZECf85el+7r79 [...]

The HDR item represents the encrypted result. It is a single long string of text that can fill several lines of the file.

Decrypting encrypted files

To decrypt encrypted call logs or waveforms, use the nr_decrypt utility. This tool is located in the or %SWISRSDK%\amd64\bin directory.

Note: On Linux, you must source the recognition file SETUP-ENV.sh prior to running any Recognizer utility. You must do this whenever you open a Linux shell. The command is:

> source /usr/local/Nuance/Recognizer/SETUP-env.sh

To use the utility, you must specify the input file or directory containing the encrypted information, and the private key that matches the public key used to perform the original encryption. If there is a password for the private key, that too is required:

nr_decrypt -i target [-r] [-d] [-f] -prv privateKeyFile 

    [-pass privateKeyPassword] [-reenc pubKeyFile]

The nr_decrypt utility accepts a log file with or without the *.enc extension (for example, NUAN-33-16-myhost-0a0314b4_000000f8_4cd0285f_0002_0001-LOG), or audio files that end in a *.enc extension. Decrypted files have the same name as the original encrypted file, minus the *.enc extension. If the original file did not end in the *.enc extension, the decrypted file is prefixed with an underscore (_).

The options that apply for the nr_decrypt utility are:

Option	Description
-i target	Specifies the input file, or a directory containing encrypted files.
-r	If -i is a directory, this optional flag instructs the utility to proceed recursively through all files in all subdirectories.
-d	Deletes encrypted files upon decryption. To be used with caution.
-f	Forces replacement of previously decrypted files (if any).
-prv privateKeyFile	Specifies the private key that matches the public key that was used for the original encryption.
-pass privateKeyPassword	Specifies the password for the private key, if applicable.
-reenc pubKeyFile	Specifies that the file(s) are to be re-encrypted with a new key after decrypting the file with the privateKeyFile. For example, this can be used when you need to provide data to Nuance for troubleshooting purposes, without revealing your private key or risking exposure of secure data to a third party.

A few examples of nr_decrypt utility commands appear below:

Example 1

nr_decrypt.exe -i myWaveFile.wav.enc -prv mySecretKey 

This simple example decrypts a single waveform file (myWaveFile.wav.enc) using the specified private key file (mySecretKey). The decrypted file is named myWaveFile.wav.

Example 2

nr_decrypt.exe -i myLOG.enc -prv mySecretKey -pass abracadabra 

This example decrypts a single log file (myLOG.enc). The password (abracadabra) is required because the user encrypted the private key during generation (see Generating the public and private keys). The decrypted file is named myLOG.log.

Example 3

nr_decrypt.exe -i $SWISRSDK/data -r -d -f -prv mySecretKey 

This command decrypts all call logs and audio waveforms in the $SWISRSDK\data directory and its subdirectories.

• The -r option tells the utility to continue through all subdirectories of the $SWISRSDK\data directory, and decrypt any encrypted files it finds there.
• The -d option deletes the original encrypted files after decrypting them. If a file cannot be decrypted—for example, if one of the subdirectories contains an audio file that does not end in the *.enc extension—it is not deleted. However, if an encrypted file is incorrectly decrypted with the wrong key pair, the deletion proceeds.

• The -f option ensures that if there is an existing version of a decrypted file in a given directory, it is replaced with the result of the current decryption.
• The -prv mySecretKey option specifies the mySecretKey file containing the private key information required to decrypt this set of files.

The resulting files have the same names as the originals, but without the *.enc extension. If the original file did not end in *.enc, the new files prefix the name with an underscore (_).