Migrating from 0.29

0.30 replaces the ring-only API with a choice of crypto backends, adds store-less DEK reuse, the DEK cache, deterministic encryption and the local KMS, and makes ring optional. It writes Tink’s KMS envelope format for every provider, so values written by 0.29 and earlier read only with the deprecated legacy-formats feature, which also rewrites them in the new format, see Old values. The default algorithm of the envelope is AES-256-GCM, see Default algorithm.

Features

ring is no longer turned on by the provider features. A 0.29 build that relied on it fails with “kms-aead needs a crypto backend for its KMS providers”, so add a backend feature. aws-lc adds no second crypto library to a cloud provider build, see Choosing a backend.

The crate declares rust-version = "1.99".

Names

HashiCorp Vault Transit types have the Hc prefix:

Traits replaced by inherent methods

AeadEncryption and KmsAeadEnvelopeEncryption are gone. Their methods are inherent methods of AeadCipher and KmsAeadEnvelope, so delete the trait imports. The AAD is any &(impl AsRef<[u8]> + ?Sized), like 0.29’s Aad: AsRef<[u8]>, so &aad still compiles, and the calls that make no KMS call are not async:

Every cipher text is an Encrypted<T, F>, see Formats. It has its own value() and into_value(). Those of EncryptedDataEncryptionKey come from ValueStruct, which the crate re-exports: use kms_aead::ValueStruct. DataEncryptionKey no longer implements ValueStruct, and has its own value().

Your own provider

An application’s own implementation of the provider trait:

• implements KmsAeadEncryptionProvider instead of KmsAeadRingEncryptionProvider;
• adds fn kek(&self) -> &KekRef, with KekProvider::Other and a key name that identifies the key;
• deletes generate_encryption_key when it returned the backend’s key. The replacement, generate_key_material(&self, len), has a default implementation that lets the backend generate the key, and is implemented only for a KMS generator;
• returns EncryptedDataEncryptionKey::new(bytes). A KMS that needs the key version to decrypt gets it from those bytes, as the Azure provider’s do.

The plaintext the provider encrypts is the DEK serialised as a Tink key, see Formats. The library never inspects the provider’s own bytes.

Errors

KmsAeadError is #[non_exhaustive], so an exhaustive match on it needs a _ arm. It has two new variants, UnsupportedAlgorithm and LegacyFormat. code() returns the code of any variant, and source() returns the root cause.

The From conversions of SDK errors into KmsAeadError are gone: gcloud_sdk::error::Error, gcloud_sdk::tonic::Status, the AWS SdkError, the hyper client error, azure_core::Error and SystemTimeError. Map an SDK error in the application.

ConstantTimeEq is no longer implemented on the public types. == still compares in constant time. The Debug of Encrypted prints only the length, and == is gone from randomised values: only an Encrypted<T, Deterministic> has it.

Error codes that changed:

The other 0.29 codes keep their spelling. The new codes are listed in Error handling.

AWS KMS decryption names the key

The AWS provider sends the configured key as KeyId on every decryption. In 0.29 a decryption left it out, so AWS KMS decrypted under whichever key the encrypted DEK named, for any key the principal may decrypt with. A 0.30 process refuses a DEK encrypted under another key with IncorrectKeyException. A deployment that relied on decrypting under a second key configures a provider per key.

An alias name such as alias/orders becomes an alias ARN, where 0.29 built a key ARN of it. Configure the key ARN rather than an alias, see AWS KMS.

Default algorithm

The default algorithm of KmsAeadEnvelope is AES-256-GCM, which every Tink implementation reads in a KMS envelope. The default of 0.29 was ChaCha20-Poly1305.

A value does not record its algorithm. Values sealed under the default of 0.29 open only with ChaCha20-Poly1305 configured, and an envelope on the new default fails them with DECRYPT. A 0.29 envelope that named no algorithm becomes:

use kms_aead::backends::Ring;
use kms_aead::providers::{GcpKmsKeyRef, GcpKmsProvider};
use kms_aead::{AeadAlgorithm, KmsAeadEnvelope, KmsAeadEnvelopeOptions};

async fn example(key_ref: GcpKmsKeyRef) -> kms_aead::KmsAeadResult<()> {
// 0.29: KmsAeadRingEnvelopeEncryption::new(provider).await?
let envelope = KmsAeadEnvelope::<GcpKmsProvider, Ring>::with_options(
    GcpKmsProvider::new(&key_ref).await?,
    KmsAeadEnvelopeOptions::new().with_algorithm(AeadAlgorithm::ChaCha20Poly1305),
)?;
let _ = envelope;
Ok(())
}

Configure it on every envelope that reads those values, on the one that upgrades them, see Old values, and on every envelope that writes new values beside them: a reader cannot tell the two algorithms apart. AES-256-GCM suits a column that holds no 0.29 values.

Old values

0.30 writes Tink’s KMS envelope, and encrypts every DEK but Azure’s as a serialised Tink key. 0.29 wrote envelope layout v1 and the encrypted DEK layout v1 [0xFF][0x01]…, and 0.28.1 and earlier a length-prefixed envelope, all with the raw DEK encrypted. 0.30 reads them only with the deprecated legacy-formats feature, and fails with LEGACY_FORMAT without it, see Formats.

The envelopes that read and upgrade those values keep the algorithm they were sealed with, see Default algorithm.

To move stored values to the new format:

1. upgrade every process that reads the values to 0.30 with legacy-formats. 0.29 and earlier cannot read Tink’s format, so no process writes it before every reader has the upgrade;
2. rewrite the stored values with upgrade_legacy_value and upgrade_legacy_encrypted_dek of KmsAeadEnvelope, one or two KMS calls per value, see Upgrading stored values. upgrade_legacy_value takes the value’s AAD, and fails with DECRYPT on a value that does not open under the envelope’s algorithm and that AAD;
3. turn the feature off.

Encrypted::<T, Envelope>::separate reads Tink’s format only, with or without the feature, so code that separated stored 0.29 values runs after the sweep.