Create symmetric encryption keys and aliases, encrypt and decrypt local files, and manage development keys. Task types live in io.github.gregwhitaker.awsemulator.aws.kms.

Provision Before Tests

import io.github.gregwhitaker.awsemulator.aws.kms.CreateKmsKeyTask
import io.github.gregwhitaker.awsemulator.aws.kms.EncryptKmsFileTask
import io.github.gregwhitaker.awsemulator.aws.kms.DecryptKmsFileTask

plugins {
    java
    id("io.github.gregwhitaker.aws-emulator") version "0.3.0"
}

val key = tasks.register<CreateKmsKeyTask>("createTestKey") {
    aliasName.set("alias/application-tests")
}
val encrypt = tasks.register<EncryptKmsFileTask>("encryptFixture") {
    dependsOn(key)
    keyId.set("alias/application-tests")
    inputFile.set(layout.projectDirectory.file("fixtures/plaintext.txt"))
    outputFile.set(layout.buildDirectory.file("fixtures/ciphertext.bin"))
    encryptionContext.put("application", "tests")
}
val decrypt = tasks.register<DecryptKmsFileTask>("decryptFixture") {
    keyId.set("alias/application-tests")
    inputFile.set(encrypt.flatMap { it.outputFile })
    outputFile.set(layout.buildDirectory.file("fixtures/decrypted.txt"))
    encryptionContext.put("application", "tests")
}
val tests = tasks.named<Test>("test") { dependsOn(decrypt) }
awsEmulator { useWith(tests) }

The output provider makes decryption depend on encryption. The key and both file tasks use the same managed runtime as the tests.

Task Properties

  • CreateKmsKeyTask: aliasName. Creates/reuses an enabled SYMMETRIC_DEFAULT encryption key. The alias makes repeated setup stable.

  • CreateKmsAliasTask: aliasName, keyId, overwrite (default false). Changing an existing alias’s target requires explicit overwrite.

  • ListKmsKeysTask: lists key IDs and ARNs.

  • DeleteKmsAliasTask: aliasName; does not delete its key.

  • ScheduleKmsKeyDeletionTask: keyId, pendingWindowInDays (7–30; default 30). Already-pending keys are left alone. This is scheduled deletion, not immediate deletion.

  • EncryptKmsFileTask and DecryptKmsFileTask: keyId, inputFile, outputFile, optional encryptionContext map (default empty). Use the same context for encryption and decryption.

File Encryption And Decryption

Encryption accepts up to 4096 plaintext bytes. Decryption accepts up to 6144 ciphertext bytes. Files are binary, not Base64 strings. Input and output must differ. Result files are replaced atomically when supported and use owner-only permissions on POSIX filesystems. Bodies are not printed. A managed key disappears when its emulator stops, so both tasks must share that runtime; the runnable example wires the decrypt input to the encrypt task’s output provider.

Development Commands

Predefined commands: listKmsKeys, deleteKmsAlias --aliasName=…​, and scheduleKmsKeyDeletion --keyId=…​. Managed aliases starting with alias/aws/ are reserved. Asymmetric keys, signing, imported key material, grants, and policy enforcement testing are outside this scope.

./gradlew listKmsKeys
./gradlew deleteKmsAlias --aliasName=alias/application-tests
./gradlew scheduleKmsKeyDeletion --keyId=<key-id>

Runtime Selection

Custom resource tasks inherit awsEmulator.defaultMode, initially MANAGED. Make the consuming test or application task depend on provisioning and opt that consumer in with awsEmulator.useWith(…​). Provisioning and consumers must select the same runtime name and mode; see resource task defaults to configure a shared development default.

Every task accepts runtimeName (default default), mode, and apiCallTimeoutSeconds (default 30, positive). Predefined inspection and deletion commands default to DEVELOPMENT; select another mode with --mode=MANAGED or another declared runtime with --runtime <name>. For persistent setup, see development resource tasks.

Resource tasks always execute against live emulator state and do not use the build cache. Configuration-cache reuse is supported. Applying the plugin and listing tasks do not start Docker. Task input values may be stored in Gradle’s configuration cache; fixtures should contain local test values.

Runnable Example

./gradlew -p examples/services verifyServices --configuration-cache

The example creates a key alias and verifies a file encryption and decryption round trip with an encryption context. Run the command twice to check configuration-cache reuse against a fresh managed emulator. -PfailExample=true deliberately fails the application test to demonstrate cleanup. See the runnable example for its complete setup and persistent development commands.

Verified Scope

The examples exercise these workflows against the pinned AWS Emulator 1.0.385, using AWS SDK for Java v2 2.39.6. They establish the behavior used by these tasks, not complete AWS service equivalence. AWS Emulator fidelity varies by operation and release.