Cryptographic Keys
Store strings in NSO that are encrypted and decrypted using cryptographic keys.
Last updated
Was this helpful?
NSO 6.5
Store strings in NSO that are encrypted and decrypted using cryptographic keys.
Last updated
Was this helpful?
By using the NSO built-in encrypted YANG extension types tailf:aes-cfb-128-encrypted-string or tailf:aes-256-cfb-128-encrypted-string, it is possible to store encrypted string values in NSO. See the man page for more details on the encrypted string YANG extension types.
NSO supports defining one or more sets of cryptographic keys directly in ncs.conf and in an external key file read by an external command. Three methods can be used to configure the keys in ncs.conf:
External keys under /ncs-config/encrypted-strings/external-keys.
Key rotation under /ncs-config/encrypted-strings/key-rotation.
Legacy (single generation) format: /ncs-config/encrypted-strings/AESCFB128 and /ncs-config/encrypted-strings/AES256CFB128 .
Local installation: Dummy keys are provided in legacy format in ncs.conf for development purposes. For deployment, the keys must be changed to random values. Example local installation ncs.conf (do not reuse):
System installation: Random keys are generated in the legacy format stored in ${NCS_CONFIG_DIR}/ncs.crypto_keys, and read using the ${NCS_DIR}/bin/ncs_crypto_keys external command as configured in ${NCS_CONFIG_DIR}/ncs.conf. Example system installation ncs.conf:
Example system installationncs.crypto_keys file (do not reuse):
For details on using a custom external command to read the encryption keys, see .
To provide keys that can be rotated in ncs.conf, each generation of cryptographic keys must be encapsulated in a /ncs-config/encrypted-strings/key-rotation list, and a /ncs-config/encrypted-strings/key-rotation/generation list key starting from 0 must be included and incremented for each set of cryptographic keys. Example (do not reuse):
External keys that can be rotated must be provided with the initial line EXTERNAL_KEY_FORMAT=2 and the generation within square brackets. Example (do not reuse):
There is always an active generation:
Active generation is the generation in the set of keys currently used to encrypt and decrypt all leafs with an encrypted string type.
The active generation is persisted.
If using the legacy method of providing keys in ncs.conf or when providing keys using the /ncs-config/encrypted-strings/key-rotation method without providing the initial line EXTERNAL_KEY_FORMAT=2 in the application, the active generation will be -1.
If starting NSO without any previous keys using the /ncs-config/encrypted-strings/key-rotation method or the external-keys method with the initial line EXTERNAL_KEY_FORMAT=2, the highest provided generation will be selected as the active generation.
Rotating cryptographic keys means replacing an old cryptographic key with a new one while maintaining the functionality of the encryption and decryption of encrypted string values in NSO. It is a standard practice in cryptography and key management to enhance security and mitigate risks associated with key exposure or compromise. Key rotation helps ensure that sensitive data remains secure over time. It reduces the impact of potential key compromise and adheres to best practices for cryptographic hygiene. Key benefits:
If a cryptographic key is compromised, rotating it reduces the amount of data exposed to the attacker since previously encrypted values can be re-encrypted with a new key.
Regular rotation minimizes the time a single key is in use, thereby reducing the potential damage an attacker could do if they gain access to it.
Reusing the same key for a prolonged period increases the risk of data correlation attacks (e.g., frequency analysis). Rotation ensures unique keys are used for encrypting strings, reducing this risk.
Regularly rotating keys helps organizations maintain and test their key management processes. This ensures the system is prepared to handle key management tasks effectively in an emergency.
To rotate to a new generation of keys and re-encrypt the data:
Check the currently active generation using the /key-rotation/get-active-generation action.
Re-encrypt all encrypted values with a new set of keys using the /key-rotation/apply-new-key action with the new-key-generation to rotate to as input.
The commit queue must be empty before running the action, or the action will fail, as the snapshot database is re-initialized. To wait for the commit queue to become empty, use the wait-commit-queue argument with the number of seconds to wait before failing.
CLI example:
The data in CDB that is subject to re-encryption when executing the /key-rotation/apply-new-key action:
Encrypted types.
Unions of encrypted types.
Service metadata (original attribute, reverse and forward diff set).
NED secrets.
Rollback files.
History log.
Under the hood, the/key-rotation/apply-new-keys action, when executed, performs the following steps:
Starts an upgrade transaction that will be used when re-encrypting the datastore.
Load the new active cryptographic keys into CDB and persist them.
Sync HA.
Re-encrypt data.
Drops the CDB snapshot database.
Commits data.
Restart NSO VMs.
End upgrade.
Suppose you have previously provided keys in the legacy format and wish to switch to /ncs-config/encrypted-strings/key-rotation or external-keys with the initial line EXTERNAL_KEY_FORMAT=2. In that case, you must provide the currently used keys as generation -1. The new keys can have any non-negative generation number.
Replace the external key file or ncs.conf file depending on where the keys are stored.
Issue ncs --reload to reload the cryptographic keys.
Ensure commit queues are empty or wait for them to become empty.
Execute/key-rotation/apply-new-keys action to change the active generation, for example, from -1 to new-key-generation 0 as shown in the CLI example above.
NSO 6.5 removed support for 3DES encryption since the algorithm is no longer deemed sufficiently secure. If you are migrating from an older version and you have data using the tailf:des3-cbc-encrypted-string YANG type, NSO will no longer be able to read this data. In fact, compiling a YANG module using this type will produce an error.
To avoid losing data when upgrading to NSO 6.5 or later, you must first update all the YANG data models and change the tailf:des3-cbc-encrypted-string type to either tailf:aes-cfb-128-encrypted-string or tailf:aes-256-cfb-128-encrypted-string. Compile the updated models and then perform a package upgrade for the affected packages.
While upgrading the packages, the automatic CDB schema upgrade will re-encrypt the data in the new (AES) format. At this point you are ready to upgrade to the new NSO version that no longer supports 3DES.
For ncs.conf details, see the under /ncs-config/encrypted-strings.
Always using .
Before changing the cryptographic keys, always using . Also, back up the external key file, default ${NCS_CONFIG_DIR}/ncs.crypto_keys, or the ${NCS_CONFIG_DIR}/ncs.conf file, depending on where the keys are stored.