A site-specific passphrase is used to encrypt any private and symmetric keys used in Rhapsody configurations. The passphrase prevents the keys from being exposed when the configuration repository is copied.

The passphrase is stored in an encrypted form in a Configuration Passphrase Store which is a text file located at <Rhapsody>/rhapsody/data/config/passphrases.txt (also known as the passphrases file). If Rhapsody cannot locate the passphrases file during startup, then Rhapsody creates the file with a randomly generated passphrase.

The passphrases file is automatically included in Rhapsody configuration backups.

A typical passphrases file has the following content:

# Rhapsody Configuration Passphrase Store
#
# This text file is used to store passphrases used to encrypt private and 
# symmetric keys stored in the Rhapsody configuration. The first valid 
# passphrase in this file is used for encryption; all passphrases in the
# file can be used for decryption.
#
# Blank lines and lines beginning with the hash (#) character are ignored.
# If the hash (#) character appears as anything other than the first non-
# whitespace character then it is treated as part of a passphrase.
#
# A new passphrase can be added by adding it as the first one in the file.
# Rhapsody will find it when it is next restarted, and then re-write this
# file with the new passphrase in an encrypted form. The encrypted form 
# uses a prefix of REN - it is recommended that new passphrases do not use
# this prefix to prevent them from being mis-identified as an encrypted 
# passphrase. Encrypted passphrases that cannot be decrypted are logged 
# and ignored.
#
# If no valid passphrases are found in this file at startup, a new random 
# passphrase is generated and stored in this file in encrypted form.
#
# Old passphrases can optionally be removed from this file, however, any
# private and symmetric keys that were added while that passphrase was in
# effect will no longer be usable. They will still be visible in the IDE,
# but need to be re-imported in order to be used again, at which point they
# are instead encrypted using the first passphrase in the list.

# Passphrase generated by Rhapsody at 7/21/14 3:12 PM.
REN6003a9b5649bad7821b04747d1c492f13e2be1e93c7828298e614e2ad45c70a739439d08d2efb6d10f3e6fca6ae97c9379705a336d4bad295351555cee645

Custom Passphrases

While it is possible for you to provide their own passphrase, it is recommended that you use the default passphrase generated by Rhapsody. If you provide one yourself, then it is recommended that this passphrase be at least 20 characters long, and contains a range of uppercase, lowercase, numbers, and special characters. The passphrases file must be UTF-8 encoded if any characters beyond the ASCII range are to be used.

To change a passphrase, you can edit the passphrases file directly. Encrypted passphrases start with a prefix of REN, therefore it is recommended that this prefix is not used for custom passphrases. During Rhapsody startup, the file is loaded and any unencrypted passphrases are encrypted and the file is re-written.

Any number of passphrases can be provided in the file. Rhapsody uses the first valid passphrase listed in the file to encrypt any changes made to private and symmetric keys. However, any valid passphrase can be used to decrypt the private and symmetric keys. This allows the passphrase for new keys to be changed, while allowing existing and historical keys to be viewed using older passphrases.

Rhapsody reads from and writes to the file only during startup. Any changes you make to the file take effect when Rhapsody is next started.

Error Scenarios

If Rhapsody cannot read or write to the passphrases file, Rhapsody is designed to fail to start.

If a passphrase appears to be encrypted, but cannot be decrypted when Rhapsody starts, an error is logged and the passphrase is ignored. If this was the only passphrase in the passphrases file, then Rhapsody generates a new one.

If Rhapsody cannot decrypt a private or symmetric key, the key remains visible in the Rhapsody IDE and through the REST API, but is marked as invalid. Such keys cannot be used by communication points, filters, or web services, but can be deleted through the Rhapsody IDE or REST API.