KMS/AEAD envelope encryption for GCP/AWS KMS and Ring AEAD for Rust

Features:

• Envelope encryption using automatically generated or provided data encryption keys;
• Provides a public and simple implementation for Ring based AEAD encryption without using KMS;
• Opt-in for KMS based secure random generator for GCP and AWS instead of Ring;

Available KMS providers:

• Google Cloud Platform KMS
• Amazon Web Services KMS

Quick start

Cargo.toml:

[dependencies]
kms-aead = { version = "0.15", features=["..."] }

See security consideration below about versioning.

Available features:

• gcp-kms-encryption for Google KMS envelope encryption support
• aws-kms-encryption for Amazon KMS envelope encryption support
• ring-aead-encryption using API for Ring AEAD only without any KMS envelope encryption

Example

 let kms_ref = kms_aead::providers::AwsKmsKeyRef::new(aws_account_id, aws_key_id);

 let encryption: KmsAeadRingEnvelopeEncryption<AwsKmsProvider> =
     kms_aead::KmsAeadRingEnvelopeEncryption::new(providers::AwsKmsProvider::new(&kms_ref).await?)
         .await?;

 let secret_value = SecretValue::from("test-secret");
 let test_aad = "test-aad".to_string();

 let cipher_text = encryption.encrypt_value(&test_aad, &secret_value).await?;

 let secret_value: SecretValue = encryption
     .decrypt_value(&test_aad, &cipher_text)
     .await?;

All examples available at examples directory.

GCP/AWS secure random generators

To use GCP/AWS KMS API for secure random generator you should enable it using options.

For AWS:

    providers::AwsKmsProvider::with_options(
            &kms_ref,
            AwsKmsProviderOptions::new().with_use_kms_random_gen(true),
    ).await?

For GCP:

    providers::GcpKmsProvider::with_options(
            &kms_ref,
            GcpKmsProviderOptions::new().with_use_kms_random_gen(true),
    ).await?

Security considerations and risks

OSS

Open source code is created through voluntary collaboration of software developers. The original authors license the code so that anyone can see it, modify it, and distribute new versions of it. You should manage all OSS using the same procedures and tools that you use for commercial products. As always, train your employees on cyber security best practices that can help them securely use and manage software products. You should not solely rely on individuals, especially on the projects like this reading sensitive information.

Versioning

Please don't use broad version dependency management not to include a new version of dependency automatically without auditing the changes.

Security implementation details and recommendations

The library uses 96 bit nonces and ChaCha20-Poly1305 algorithm by default.

Nonces generates as (depends on options):

• A random 96-bit buffer generated by cryptographic pseudo-random number generator;
• (default) A mix of time (last 48 bit of UNIX epoch) + random 48-bit buffer by cryptographic pseudo-random number generator;

This is the example how to configure nonces and algorithm for GCP KMS:

let encryption = kms_aead::KmsAeadRingEnvelopeEncryption::with_algorithm_options(
        kms_aead::providers::GcpKmsProvider::new(&kms_ref).await?,
        &ring::aead::CHACHA20_POLY1305,
        KmsAeadRingEnvelopeEncryptionOptions::new().with_encryption_options(
            kms_aead::ring_encryption::RingAeadEncryptionOptions::new().with_nonce_kind(
                kms_aead::ring_encryption::RingAeadEncryptionNonceKind::Random
            )
        )
    )
    .await?;

Licence

Apache Software License (ASL)

Author

Abdulla Abdurakhmanov