Encryption, Decryption, and MAC Operations Using Versioned Key

Encrypt, Sign, MAC Operations using versioned key

To encrypt, sign, and generate MACs, your code must create an instance of a key. When using a versioned key, you can create an instance of the default version, a specific version, or all versions. The code is similar for each operation.

Note

• Encryption/decryption is done using symmetric keys.

• Sign and MAC operations are done using asymmetric keys.

To access the default version of a versioned key, call the method the same way you access a non-versioned key. The Key Manager will return the latest active version.

// for encryption and MAC
NAEKey defaultVersion = NAEKey.getSecretKey(symkey, session);
// for sign
NAEPrivateKey defaultVersion = NAEKey.getPrivateKey(RSAkey, session);

To create an instance of a specific key version you must append a # plus the version number. These statements will return version two of the key:

// for encryption and MAC
NAEKey secondVersion = NAEKey.getSecretKey(symkey+"#2", session);
// for sign
NAEPrivateKey secondVersion = NAEKey.getPrivateKey(RSAkey+"#2", session);

To create an instance of the key that contains all key versions:

// for encryption and MAC
NAEKey allVersions = NAEKey.getSecretKey(symkey+"#all", session);
// for sign
NAEPrivateKey allVersions = NAEKey.getPrivateKey(RSAkey+"#all", session);

Decrypt, SignV, MACV Operations using versioned key

When data is encrypted, signed, or MACed using a versioned key, the resulting ciphertext contains information in its header indicating which version of the key was used. This header is 3 bytes long. During decryption or verification, the Key Manager parses this information and applies the correct key version. There is no need to specify the key version.

If the data requires a retired key version, you will get an exception.