The adapter translates AWS KMS requests to Google Cloud KMS.
#### Key identity and lifecycle The adapter keeps durable records for AWS key identities, aliases, tags, and lifecycle state. Key creation provisions the corresponding target key. Later requests resolve the AWS identity to that key; the target service performs cryptographic operations and retains its wrapping key material. An alias is a mutable reference in adapter state. Updating it changes which key subsequent alias-based requests select; it does not move key material or rewrite existing ciphertext. Back up adapter state and retain the target keys and versions needed to decrypt stored data. Scheduled deletion records a recovery window of 7-30 days, with 30 days as the default. Cancelling the request returns the key to a disabled state; enable it explicitly before using it again. Final target destruction follows the target's retention rules, which may delay physical removal beyond the adapter's recovery window. #### The key ring and its crypto keys A Cloud KMS key belongs to a key ring in a location. Each key has immutable versions, with a primary version for symmetric encryption. The adapter resolves AWS key IDs to `google_kms_crypto_key` resources and maintains `alias/…` mappings because Cloud KMS has no native alias object. The key ring's location controls where cryptographic operations run, for example `us-east1` or the `us` multi-region. Symmetric encryption uses the primary version; decryption uses the version recorded in the ciphertext. Signing, MAC, and public-key export operations address a specific version.
A location-specific key ring holds versioned keys. Symmetric encryption uses the primary version.
#### One purpose per key: symmetric, asymmetric, and MAC `CreateKey` translates AWS key usage and specification into a Cloud KMS `purpose` and `version_template.algorithm`. Symmetric `ENCRYPT_DECRYPT` uses `GOOGLE_SYMMETRIC_ENCRYPTION`; signing uses `ASYMMETRIC_SIGN` with an RSA or EC algorithm; HMAC uses `MAC`. Purpose is fixed at creation. Symmetric keys use `cryptoKeys.encrypt` and `decrypt`. Signing uses `asymmetricSign`; verification checks the signature against the public key returned by `getPublicKey`. HMAC uses `macSign` and `macVerify`. A request incompatible with the key's purpose returns an error.
Key purpose selects encryption, signing, or MAC operations and their algorithms.
#### How GenerateDataKey works `GenerateDataKey` returns a plaintext data key and an encrypted (wrapped) copy. The application uses the plaintext key to encrypt its data locally, then discards that key and stores the wrapped copy beside the encrypted data. To read the data later, it asks the key service to decrypt the wrapped key. The adapter generates a random data key of the requested size and calls `cryptoKeys.encrypt` to wrap it. It returns the AWS-shaped `{Plaintext, CiphertextBlob}` pair and uses `cryptoKeys.decrypt` to unwrap it later. Both calls include the encryption context as AAD. The adapter includes key identity with Cloud KMS ciphertext so Decrypt can locate the key. Applications must treat this blob as opaque.
The adapter generates a random data key and wraps it with cryptoKeys.encrypt .
#### Encryption context and authenticated data An encryption context is a non-secret key/value map bound to ciphertext as additional authenticated data (AAD). Decryption requires the same context. Applications can use it to bind encrypted values to a tenant or purpose. Cloud KMS accepts up to 64 KiB of `additionalAuthenticatedData`. The adapter serializes the context map into a stable byte encoding so map insertion order does not affect decryption. It supplies the same encoding for direct encryption and data-key wrapping. A different context causes decryption to fail.
The adapter encodes the encryption context as additionalAuthenticatedData . Decryption requires the same context.
#### Rotation without breaking old ciphertexts Key rotation creates a new version for subsequent encryption. Retained, enabled older versions remain available to decrypt existing ciphertext. `rotation_period` schedules new key versions and promotes each to `primary`. `RotateKeyOnDemand` creates and promotes a version immediately; `GetKeyRotationStatus` reports whether a rotation period is configured. Previous enabled versions remain usable until disabled or destroyed.
Rotation creates a primary version for new encryption. Earlier enabled versions can still decrypt existing data.
#### Limitations **Access policies and grants.** The mapping uses Google IAM for target-key access and does not reproduce AWS key-policy or grant APIs. Constrained grants are rejected; encryption-context authentication alone does not replace a grant that limits permitted callers or contexts. **Ciphertext format.** The adapter wraps Cloud KMS ciphertext with the key identity needed for a later Decrypt request. Treat CiphertextBlob as opaque. Existing AWS ciphertext is not directly decryptable with a new Google key. **Import and regions.** Import material through the configured Cloud KMS import job. AWS runtime import-handshake APIs are outside this mapping. A key-ring location does not provide independently addressable AWS multi-region replica keys. **Composed operations.** GenerateDataKey generates a random key and wraps it with Cloud KMS. ReEncrypt decrypts and encrypts under the destination key; plaintext exists temporarily in the adapter but is not returned to the caller. DeriveSharedSecret is outside this mapping. #### Other considerations **Configure access and protection.** Grant the deployment identity the required Cloud KMS operations at the appropriate key or key-ring scope. Workload identity supplies credentials. Google operates the key service; choose software or HSM protection for the required keys. **Keep data recoverable.** Retain old key versions while ciphertext requires them. Preserve adapter identity and alias records alongside the target-key inventory. Test disable, cancellation, rotation, and recovery before changing production key state. **Migrate ciphertext.** Use the old AWS key to decrypt ciphertext or unwrap data keys, then encrypt or wrap under the target key. Keep AWS available until migration and target decryption are verified. Provisioning a key does not transform stored ciphertext. ## On Azure | Operation | Area | Support | Depth | Notes | | ----------------------------------- | --------------------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CreateAlias | Aliases | Supported | Most usage | the adapter maintains the alias-to-key mapping and resolves alias references, since Key Vault addresses a key by name with no separate alias object | | DeleteAlias | Aliases | Supported | Full surface | removes an alias from the mapping | | ListAliases | Aliases | Supported | Most usage | lists aliases retained in adapter state | | UpdateAlias | Aliases | Supported | Full surface | changes the key referenced by an alias in adapter state | | DeriveSharedSecret | Asymmetric | Out of scope | Full surface | elliptic-curve shared-secret derivation has no Key Vault equivalent op and is rejected | | GetPublicKey | Asymmetric | Supported | Most usage | returns the public half of the RSA or EC key | | Sign | Asymmetric | Supported | Most usage | signs natively with an RSA or EC key via Key Vault sign | | Verify | Asymmetric | Supported | Most usage | verifies natively via Key Vault verify | | GenerateDataKey | Envelope / data keys | Partial | Common | the envelope is served as wrap-key: a fresh random data key is generated and wrapped by an RSA key (RSA-OAEP); the returned pair round-trips, but the wrapping key is RSA, not a symmetric AES key | | GenerateDataKeyPair | Envelope / data keys | Partial | Most usage | an asymmetric data-key pair is generated and its private half wrapped by an RSA key | | GenerateDataKeyPairWithoutPlaintext | Envelope / data keys | Partial | Full surface | the same, returning only the wrapped private half | | GenerateDataKeyWithoutPlaintext | Envelope / data keys | Partial | Most usage | the same wrap-key path, returning only the wrapped data key | | CreateGrant | Grants | Out of scope | Most usage | authorization is governed by Azure role assignments rather than KMS grants, so a grant is rejected | | ListGrants | Grants | Out of scope | Most usage | there is no grant to list; access is an Azure role assignment | | ListRetirableGrants | Grants | Out of scope | Full surface | there is no grant to list | | RetireGrant | Grants | Out of scope | Full surface | there is no grant to retire | | RevokeGrant | Grants | Out of scope | Full surface | there is no grant to revoke | | GenerateMac | HMAC | Out of scope | Most usage | Key Vault Standard has no HMAC keys; Managed HSM and Premium oct-HSM preview use separate configurations | | VerifyMac | HMAC | Out of scope | Most usage | there is no HMAC key on a standard vault to verify against | | DeleteImportedKeyMaterial | Imported key material | Out of scope | Full surface | there is no runtime imported-material lifecycle to drive | | GetParametersForImport | Imported key material | Out of scope | Full surface | imported key material is loaded through Key Vault's own key-import flow at provisioning, not through the native import handshake, so the runtime import ops are rejected | | ImportKeyMaterial | Imported key material | Out of scope | Full surface | the import handshake is not served at runtime; material is imported at provisioning | | CancelKeyDeletion | Key management | Supported | Full surface | cancels pending deletion in adapter state; native recovery also applies if target deletion has begun | | CreateKey | Key management | Partial | Common | an RSA or EC key is created natively; symmetric AES keys require a separate Azure configuration and are outside this Standard mapping | | DescribeKey | Key management | Supported | Common | returns the key metadata: identifier, type, size or curve, operations, and enabled/validity attributes | | DisableKey | Key management | Supported | Most usage | clears the key's enabled attribute | | EnableKey | Key management | Supported | Most usage | sets the key's enabled attribute | | ListKeys | Key management | Supported | Common | lists the keys in the vault | | ScheduleKeyDeletion | Key management | Partial | Most usage | records the adapter recovery window; vault retention and purge protection govern final target removal | | UpdateKeyDescription | Key management | Partial | Full surface | a Key Vault key has no description field, so the label is stored as a tag | | GetKeyPolicy | Key policy | Out of scope | Most usage | there is no per-key policy document to read | | ListKeyPolicies | Key policy | Out of scope | Full surface | there is no per-key policy document to list | | PutKeyPolicy | Key policy | Out of scope | Most usage | access is governed by Azure role assignments rather than a per-key policy document, so a per-key policy is rejected | | ReplicateKey | Multi-region | Out of scope | Full surface | a key lives in a single vault and region; cross-region key replication is rejected | | UpdatePrimaryRegion | Multi-region | Out of scope | Full surface | there is no multi-region key set whose primary can be moved | | GenerateRandom | Random | Supported | Full surface | cryptographic random bytes are generated by the adapter; no key is touched | | DisableKeyRotation | Rotation | Supported | Full surface | clears the rotation policy | | EnableKeyRotation | Rotation | Supported | Most usage | turns on rotation via the key's rotation policy | | GetKeyRotationStatus | Rotation | Supported | Most usage | reads the key's rotation policy | | RotateKeyOnDemand | Rotation | Supported | Full surface | rotates the key on demand, creating a new version | | Decrypt | Symmetric crypto | Partial | Common | served as RSA-OAEP decrypt on the RSA key | | Encrypt | Symmetric crypto | Partial | Common | a standard Key Vault holds RSA/EC keys only, so encrypt is served as RSA-OAEP on an RSA key rather than symmetric AES; the payload is bounded by the RSA modulus, and symmetric AES uses a separate Azure configuration | | ReEncrypt | Symmetric crypto | Partial | Most usage | served as a decrypt-then-encrypt across the two RSA keys under the adapter; the plaintext is never returned to the caller | | ListResourceTags | Tags | Supported | Full surface | lists the tags on the key | | TagResource | Tags | Supported | Full surface | attaches key/value tags to the key | | UntagResource | Tags | Supported | Full surface | removes tags | #### How it works Tensor9 runs a KMS adapter in the customer environment and sets `AWS_ENDPOINT_URL_KMS` to its loopback endpoint. The adapter accepts the application's AWS SDK calls, including `Encrypt`, `Decrypt`, and `GenerateDataKey`, and translates them to Azure Key Vault. The service retains the wrapping key; data-key operations can return a plaintext data key for the application to use. A standard Key Vault supports RSA and EC keys. It handles asymmetric signing and RSA encryption, but has no symmetric AES or HMAC key type. The adapter implements data-key generation with RSA wrapping. Requests with an encryption context are rejected because this RSA path cannot bind AAD. Azure Managed HSM is a separate symmetric-key service. Key Vault Premium also offers oct-HSM AES/HMAC in public preview. Neither is part of this Standard RSA/EC mapping.
The adapter translates AWS KMS requests to an Azure Key Vault key.
#### Key identity and lifecycle The adapter keeps durable records for AWS key identities, aliases, tags, and lifecycle state. Key creation provisions the corresponding target key. Later requests resolve the AWS identity to that key; the target service performs cryptographic operations and retains its wrapping key material. An alias is a mutable reference in adapter state. Updating it changes which key subsequent alias-based requests select; it does not move key material or rewrite existing ciphertext. Back up adapter state and retain the target keys and versions needed to decrypt stored data. Scheduled deletion records a recovery window of 7-30 days, with 30 days as the default. Cancelling the request returns the key to a disabled state; enable it explicitly before using it again. Final target destruction follows the target's retention rules, which may delay physical removal beyond the adapter's recovery window. #### RSA and EC keys The adapter uses an `azurerm_key_vault_key`. `CreateKey` selects an RSA key size or EC curve through `key_type`, `key_size`, and `curve`. The `key_opts` list restricts the key to operations such as `encrypt`, `decrypt`, `wrapKey`, `unwrapKey`, `sign`, and `verify`. Requests for symmetric AES keys are rejected. `DescribeKey` uses Get Key to report identifier, type, size or curve, permitted operations, and validity. `EnableKey` and `DisableKey` update the enabled attribute. The adapter stores the AWS key description as a tag and maintains `alias/…` mappings. Key Vault retains immutable key versions.
key\_opts restricts operations on the RSA or EC key. Standard vaults do not support symmetric AES keys.
#### Envelope encryption via wrapKey / unwrapKey `GenerateDataKey` returns a plaintext data key and an encrypted (wrapped) copy. The application uses the plaintext key to encrypt its data locally, then discards that key and stores the wrapped copy beside the encrypted data. To read the data later, it asks the key service to decrypt the wrapped key. The adapter generates a random data key, wraps it through RSA-OAEP `wrapKey`, and returns plaintext and encrypted copies. `unwrapKey` recovers it later. This uses an RSA wrapping key; it does not provide a symmetric AES KMS key.
The adapter generates a data key, uses RSA wrapKey to encrypt it, and uses unwrapKey to recover it.
#### Encryption-context limitations An encryption context is a non-secret key/value map bound to ciphertext as additional authenticated data (AAD). Decryption requires the same context. Applications can use it to bind encrypted values to a tenant or purpose. The standard-vault RSA-OAEP path has no AAD parameter for an AWS encryption context. Context-bearing requests return errors. Applications that require context binding need a supported AES-GCM service, such as the separate Azure Managed HSM service.
The standard-vault RSA path cannot bind an encryption context, so context-bearing requests are rejected.
#### Supported key types AWS KMS distinguishes symmetric encryption keys, asymmetric RSA or EC keys, and HMAC keys. Standard Azure Key Vault supports the asymmetric family. Its RSA key size limits the amount of data that can be encrypted in one operation. `Sign`, `Verify`, `GetPublicKey`, and RSA `Encrypt`/`Decrypt` use Key Vault operations. Data keys use RSA wrapping. Symmetric AES key creation, encryption-context binding, and `GenerateMac`/`VerifyMac` are unsupported on this standard-vault path.
Key Vault Standard supports RSA and EC keys. Symmetric-key options use other Azure configurations.
#### Rotation via a key rotation policy Key rotation creates a new version for subsequent encryption. Retained, enabled older versions remain available to decrypt existing ciphertext. The key's rotation policy sets `expire_after` and a `time_after_creation` or `time_before_expiry` trigger. `EnableKeyRotation` configures it, `GetKeyRotationStatus` reads it, and `RotateKeyOnDemand` creates a new version immediately. Previous usable versions remain available for decryption. Removing access to an old key prevents decryption of data encrypted under it.
Rotation creates a key version while retaining older versions for existing ciphertext.
#### Limitations **Standard-vault algorithms.** This mapping uses RSA and EC keys in Key Vault Standard. RSA encryption has a payload limit determined by its modulus and padding. Data-key generation uses RSA wrapping; the wrapping key is not a symmetric AES key. **Authenticated context and HMAC.** The mapped RSA-OAEP operations cannot authenticate an AWS encryption context and reject context-bearing requests. Standard vaults have no HMAC key type. Azure Managed HSM supports symmetric keys; Key Vault Premium also offers oct-HSM AES/HMAC in public preview, outside this Standard mapping. **Authorization and import.** AWS grant and key-policy APIs are not recreated. Use Azure role assignments for target access. Imported material uses the provider key-import procedure; the AWS runtime import handshake is outside this mapping. **Regions and retention.** This mapping does not create shared-material AWS multi-region replica keys. The adapter recovery window and the vault's native soft-delete retention are distinct; native retention and purge protection can delay final removal. #### Other considerations **Choose key protection.** Key Vault Premium can protect RSA and EC keys with an HSM; Managed HSM is a separate service. The Standard RSA/EC profile described here does not claim their additional symmetric-key capabilities. **Grant access.** Use the deployment's Azure identity and narrowly scoped role assignments. Separate permission to manage keys from permission to decrypt or unwrap data keys. **Retain and migrate.** Keep old key versions available while ciphertext requires them. Decrypt or unwrap AWS values with the old key and encrypt or wrap under the new key before retiring AWS access. Test context requirements early: this RSA mapping cannot preserve them. ## On OCI | Operation | Area | Support | Depth | Notes | | ----------------------------------- | --------------------- | ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CreateAlias | Aliases | Supported | Most usage | the adapter maintains the alias-to-key mapping and resolves alias references, since OCI has no separate alias object | | DeleteAlias | Aliases | Supported | Full surface | removes an alias from the mapping | | ListAliases | Aliases | Supported | Most usage | lists aliases retained in adapter state | | UpdateAlias | Aliases | Supported | Full surface | changes the key referenced by an alias in adapter state | | DeriveSharedSecret | Asymmetric | Out of scope | Full surface | elliptic-curve shared-secret derivation has no OCI KMS equivalent op and is rejected | | GetPublicKey | Asymmetric | Supported | Most usage | returns the public half from the key version | | Sign | Asymmetric | Supported | Most usage | signs a message or digest with an RSA or ECDSA key via OCI Sign | | Verify | Asymmetric | Supported | Most usage | verifies natively via OCI Verify | | GenerateDataKey | Envelope / data keys | Supported | Common | served natively by OCI's GenerateDataEncryptionKey with the plaintext key included: one call returns the plaintext data key alongside its wrapped copy, one data-key operation | | GenerateDataKeyPair | Envelope / data keys | Partial | Most usage | the native data-key op is symmetric; an asymmetric data-key pair is generated and its private half wrapped by the key, with no native data-key-pair op | | GenerateDataKeyPairWithoutPlaintext | Envelope / data keys | Partial | Full surface | the same, returning only the wrapped private half | | GenerateDataKeyWithoutPlaintext | Envelope / data keys | Supported | Most usage | the same native op with the plaintext key excluded, returning only the wrapped data key | | CreateGrant | Grants | Out of scope | Most usage | authorization is governed by OCI IAM policies on the compartment rather than KMS grants, so a grant is rejected | | ListGrants | Grants | Out of scope | Most usage | there is no grant to list; access is an OCI IAM policy | | ListRetirableGrants | Grants | Out of scope | Full surface | there is no grant to list | | RetireGrant | Grants | Out of scope | Full surface | there is no grant to retire | | RevokeGrant | Grants | Out of scope | Full surface | there is no grant to revoke | | GenerateMac | HMAC | Out of scope | Most usage | OCI KMS has no HMAC key type (its key shapes are AES, RSA, and ECDSA), so a MAC request is rejected | | VerifyMac | HMAC | Out of scope | Most usage | there is no HMAC key to verify against | | DeleteImportedKeyMaterial | Imported key material | Out of scope | Full surface | there is no runtime imported-material lifecycle to drive | | GetParametersForImport | Imported key material | Out of scope | Full surface | material is imported through OCI wrapping-key and key-import operations at provisioning; EXTERNAL key-manager references are separate | | ImportKeyMaterial | Imported key material | Out of scope | Full surface | the AWS runtime import handshake is outside this mapping; material uses the OCI import workflow at provisioning | | CancelKeyDeletion | Key management | Supported | Full surface | cancels the scheduled deletion and leaves the adapter key disabled until EnableKey | | CreateKey | Key management | Supported | Common | the equivalent OCI key is created with the matching key shape (AES, RSA, or ECDSA) and protection mode; the key usage and material spec translate to the shape's algorithm, length, and curve | | DescribeKey | Key management | Supported | Common | reads the key metadata off the key: identifier, shape, protection mode, state, and rotation | | DisableKey | Key management | Supported | Most usage | sets the key's desired state to disabled | | EnableKey | Key management | Supported | Most usage | sets the key's desired state to enabled | | ListKeys | Key management | Supported | Common | lists the keys in the vault | | ScheduleKeyDeletion | Key management | Partial | Most usage | schedules deletion at an absolute time-of-deletion within the same 7-30-day window as AWS KMS, rather than a relative pending-window duration | | UpdateKeyDescription | Key management | Supported | Full surface | updates the key's display name | | GetKeyPolicy | Key policy | Out of scope | Most usage | there is no per-key policy document to read | | ListKeyPolicies | Key policy | Out of scope | Full surface | there is no per-key policy document to list | | PutKeyPolicy | Key policy | Out of scope | Most usage | access is governed by OCI IAM rather than a per-key policy document, so a per-key policy is rejected | | ReplicateKey | Multi-region | Partial | Full surface | multi-region is served by vault replication, which replicates the whole vault rather than a single key, so the scope differs from a per-key replica | | UpdatePrimaryRegion | Multi-region | Out of scope | Full surface | replication is whole-vault, so there is no per-key primary region to move | | GenerateRandom | Random | Supported | Full surface | cryptographic random bytes are generated by the adapter; no key is touched | | DisableKeyRotation | Rotation | Supported | Full surface | turns off automatic rotation | | EnableKeyRotation | Rotation | Supported | Most usage | turns on automatic rotation via the key's auto-rotation setting | | GetKeyRotationStatus | Rotation | Supported | Most usage | reports whether rotation is on and the configured interval | | RotateKeyOnDemand | Rotation | Supported | Full surface | rotates the key on demand, creating a new key version | | Decrypt | Symmetric crypto | Supported | Common | decrypts and re-checks the associated data; a mismatch fails the decrypt, exactly as it does natively | | Encrypt | Symmetric crypto | Supported | Common | encrypts under a symmetric AES key via the vault's crypto endpoint; the encryption context is passed as OCI associated data, so a matching context is required to decrypt | | ReEncrypt | Symmetric crypto | Partial | Most usage | there is no single re-encrypt op; the adapter serves it as a decrypt-then-encrypt across the two keys, and the plaintext is never returned to the caller | | ListResourceTags | Tags | Supported | Full surface | lists the tags on the key | | TagResource | Tags | Supported | Full surface | attaches key/value tags (as freeform or defined tags) | | UntagResource | Tags | Supported | Full surface | removes tags | #### How it works Tensor9 runs a KMS adapter in the customer environment and sets `AWS_ENDPOINT_URL_KMS` to its loopback endpoint. The adapter accepts the application's AWS SDK calls, including `Encrypt`, `Decrypt`, and `GenerateDataKey`, and translates them to OCI KMS. The service retains the wrapping key; data-key operations can return a plaintext data key for the application to use. OCI KMS supports symmetric AES keys, authenticated encryption context, asymmetric signing, and a native data-key generation operation. HMAC and AWS key-policy and grant APIs are unsupported; key access uses OCI IAM.
The adapter translates AWS KMS requests to OCI KMS.
#### Key identity and lifecycle The adapter keeps durable records for AWS key identities, aliases, tags, and lifecycle state. Key creation provisions the corresponding target key. Later requests resolve the AWS identity to that key; the target service performs cryptographic operations and retains its wrapping key material. An alias is a mutable reference in adapter state. Updating it changes which key subsequent alias-based requests select; it does not move key material or rewrite existing ciphertext. Back up adapter state and retain the target keys and versions needed to decrypt stored data. Scheduled deletion records a recovery window of 7-30 days, with 30 days as the default. Cancelling the request returns the key to a disabled state; enable it explicitly before using it again. Final target destruction follows the target's retention rules, which may delay physical removal beyond the adapter's recovery window. #### The Vault and its master keys An OCI Vault holds master encryption keys. `protection_mode` selects `SOFTWARE`, `HSM` (a hardware security module), or `EXTERNAL` (a reference to an external key manager). `DEFAULT` vaults share an HSM partition; `VIRTUAL_PRIVATE` vaults have a dedicated partition. The adapter uses two OCI clients. Cryptographic requests, including encryption, decryption, data-key generation, and signing, use `crypto_endpoint`. Key creation, rotation configuration, and scheduled deletion use `management_endpoint`.
Cryptographic requests use crypto\_endpoint ; key management uses management\_endpoint .
#### The native single-call envelope `GenerateDataKey` returns a plaintext data key and an encrypted (wrapped) copy. The application uses the plaintext key to encrypt its data locally, then discards that key and stores the wrapped copy beside the encrypted data. To read the data later, it asks the key service to decrypt the wrapped key. `GenerateDataEncryptionKey` returns both `plaintext` and `ciphertext` when `include_plaintext_key` is true. With it false, the call returns only the wrapped key, corresponding to `GenerateDataKeyWithoutPlaintext`. The adapter translates these results to AWS response fields without generating the data key locally.
GenerateDataEncryptionKey returns a plaintext data key and its encrypted copy in one call.
#### The encryption context, bound as associated data An encryption context is a non-secret key/value map bound to ciphertext as additional authenticated data (AAD). Decryption requires the same context. Applications can use it to bind encrypted values to a tenant or purpose. The adapter sends the encryption context as OCI `associatedData`. AES-GCM authenticates it with the ciphertext. Decryption with different associated data fails authentication.
OCI authenticates associatedData with the ciphertext. A different context causes decryption to fail.
#### Symmetric and asymmetric keys An OCI key's `key_shape` specifies `algorithm` (`AES`, `RSA`, or `ECDSA`), `length`, and a `curve_id` where applicable. These correspond to AWS symmetric encryption and asymmetric key families. AES keys support `Encrypt`, `Decrypt`, and `GenerateDataEncryptionKey`. RSA and ECDSA keys support signing, verification, and public-key export. OCI has no HMAC key type, so `GenerateMac` and `VerifyMac` return unsupported-operation errors.
OCI supports AES, RSA, and ECDSA key types. HMAC is unsupported.
#### Rotation Key rotation creates a new version for subsequent encryption. Retained, enabled older versions remain available to decrypt existing ciphertext. `is_auto_rotation_enabled` and `rotation_interval_in_days` configure automatic rotation. `RotateKeyOnDemand` creates a version immediately. New encryption uses the new version; decryption of existing ciphertext uses its recorded version. Both AWS and OCI express the rotation interval in days.
Automatic or on-demand rotation creates a version for new encryption and retains previous versions.
#### Limitations **Authorization and HMAC.** Target access uses OCI IAM; AWS key-policy and grant APIs are not recreated. OCI key shapes in this mapping are AES, RSA, and ECDSA, without an HMAC key type. **Replication scope.** OCI vault replication copies a vault rather than one independently managed key. ReplicateKey therefore has broader scope; UpdatePrimaryRegion does not move an individual key's primary region. **Deletion timing.** The adapter records the requested 7-30-day recovery window and translates the date to OCI's time\_of\_deletion. Retain the keys and versions required by existing ciphertext before scheduling destruction. **Imported material.** OCI imports externally generated material through its wrapping-key and key-import workflow. That differs from protection\_mode=EXTERNAL, which references a key manager outside OCI. The AWS runtime import handshake is outside this mapping. #### Other considerations **Configure custody and access.** Choose the vault and each key's software, HSM, or external protection configuration. Oracle operates the managed service; the customer configures keys, compartment permissions, and deployment identity. **Retain versions.** Rotation creates a version for new encryption. Existing ciphertext needs its original version. Plan recovery and replication for the vault holding those versions, and verify access from the destination environment. **Migrate ciphertext.** Decrypt AWS ciphertext or unwrap its data keys with the old key, then encrypt or wrap through the target adapter. Keep AWS available until migration and target decryption are verified. Creating an OCI key does not transfer AWS material or ciphertext. ## On Private Kubernetes | Operation | Area | Support | Depth | Notes | | ----------------------------------- | --------------------- | ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CreateAlias | Aliases | Supported | Most usage | the adapter maintains the alias-to-key mapping and resolves alias references, since a Transit key is addressed by name with no separate alias object | | DeleteAlias | Aliases | Supported | Full surface | removes an alias from the mapping | | ListAliases | Aliases | Supported | Most usage | lists aliases retained in adapter state | | UpdateAlias | Aliases | Supported | Full surface | changes the key referenced by an alias in adapter state | | DeriveSharedSecret | Asymmetric | Out of scope | Full surface | elliptic-curve shared-secret derivation has no Transit equivalent endpoint and is rejected | | GetPublicKey | Asymmetric | Supported | Most usage | returns the public half of an asymmetric key from the Transit key read | | Sign | Asymmetric | Supported | Most usage | signs server-side with an ed25519, ECDSA, or RSA key via the Transit sign endpoint | | Verify | Asymmetric | Supported | Most usage | verifies natively via the Transit verify endpoint | | GenerateDataKey | Envelope / data keys | Supported | Common | served natively by the Transit plaintext-datakey endpoint: one call returns the plaintext data key alongside its wrapped copy, one data-key operation | | GenerateDataKeyPair | Envelope / data keys | Partial | Most usage | the native datakey endpoint is symmetric; an asymmetric data-key pair is generated and its private half wrapped by the key, with no native data-key-pair endpoint | | GenerateDataKeyPairWithoutPlaintext | Envelope / data keys | Partial | Full surface | the same, returning only the wrapped private half | | GenerateDataKeyWithoutPlaintext | Envelope / data keys | Supported | Most usage | served natively by the Transit wrapped-datakey endpoint, returning only the wrapped data key | | CreateGrant | Grants | Out of scope | Most usage | authorization is governed by Vault ACL policies rather than KMS grants, so a grant is rejected | | ListGrants | Grants | Out of scope | Most usage | there is no grant to list; access is a Vault ACL policy | | ListRetirableGrants | Grants | Out of scope | Full surface | there is no grant to list | | RetireGrant | Grants | Out of scope | Full surface | there is no grant to retire | | RevokeGrant | Grants | Out of scope | Full surface | there is no grant to revoke | | GenerateMac | HMAC | Supported | Most usage | computes an HMAC server-side via the Transit HMAC endpoint; Transit computes the HMAC within Vault | | VerifyMac | HMAC | Supported | Most usage | verifies an HMAC via the Transit verify endpoint | | DeleteImportedKeyMaterial | Imported key material | Out of scope | Full surface | there is no runtime imported-material lifecycle to drive | | GetParametersForImport | Imported key material | Out of scope | Full surface | key material is loaded through Transit's own key-import flow at provisioning, not through the native import handshake, so the runtime import ops are rejected | | ImportKeyMaterial | Imported key material | Out of scope | Full surface | the import handshake is not served at runtime; material is imported at provisioning | | CancelKeyDeletion | Key management | Partial | Full surface | cancels the recovery window the adapter holds, before the delete is applied to Transit | | CreateKey | Key management | Supported | Common | the equivalent Transit key is created with the matching type (aes256-gcm96, RSA, ECDSA, ed25519, or hmac); the key usage and material spec translate to the Transit key type | | DescribeKey | Key management | Supported | Common | returns the key metadata held on the Transit key: type, versions, rotation, and configuration | | DisableKey | Key management | Partial | Most usage | requires adapter state and Vault access controls; minimum-version settings alone do not disable every operation | | EnableKey | Key management | Partial | Most usage | restores permitted adapter operations with the required Vault access; version thresholds govern version selection separately | | ListKeys | Key management | Supported | Common | lists the Transit keys in the mount | | ScheduleKeyDeletion | Key management | Partial | Most usage | Transit deletes immediately once deletion is allowed; the 7-30-day recovery window is held as state by the adapter, not by Transit | | UpdateKeyDescription | Key management | Partial | Full surface | a Transit key has no description field, so the label is held as metadata by the adapter | | GetKeyPolicy | Key policy | Out of scope | Most usage | there is no per-key policy document to read | | ListKeyPolicies | Key policy | Out of scope | Full surface | there is no per-key policy document to list | | PutKeyPolicy | Key policy | Out of scope | Most usage | access is governed by Vault ACL policies rather than a per-key policy document, so a per-key policy is rejected | | ReplicateKey | Multi-region | Out of scope | Full surface | a Transit key lives in a single cluster; cross-region key replication is rejected | | UpdatePrimaryRegion | Multi-region | Out of scope | Full surface | there is no multi-region key set whose primary can be moved | | GenerateRandom | Random | Supported | Full surface | returns cryptographic random bytes from Vault's random endpoint; no key is involved | | DisableKeyRotation | Rotation | Supported | Full surface | clears the auto-rotate period | | EnableKeyRotation | Rotation | Supported | Most usage | turns on automatic rotation via the key's auto-rotate period | | GetKeyRotationStatus | Rotation | Supported | Most usage | reports whether rotation is on and the configured period | | RotateKeyOnDemand | Rotation | Supported | Full surface | served natively by the Transit key-rotate endpoint, creating a new key version | | Decrypt | Symmetric crypto | Supported | Common | decrypts server-side and re-checks the associated data; a mismatch fails the decrypt, exactly as it does natively | | Encrypt | Symmetric crypto | Supported | Common | encrypts server-side via the Transit encrypt endpoint; the encryption context is supplied as Transit associated data, so a matching context is required to decrypt | | ReEncrypt | Symmetric crypto | Supported | Most usage | same-key rotation uses Transit rewrap; a different key or changed context uses adapter decrypt-then-encrypt without returning plaintext to the caller | | ListResourceTags | Tags | Partial | Full surface | lists tags retained in adapter state | | TagResource | Tags | Partial | Full surface | a Transit key has no native tag map, so tags are held as key metadata by the adapter | | UntagResource | Tags | Partial | Full surface | removes a tag from adapter metadata | #### How it works Tensor9 runs a KMS adapter in the customer environment and sets `AWS_ENDPOINT_URL_KMS` to its loopback endpoint. The adapter accepts the application's AWS SDK calls, including `Encrypt`, `Decrypt`, and `GenerateDataKey`, and translates them to HashiCorp Vault Transit. The service retains the wrapping key; data-key operations can return a plaintext data key for the application to use. Vault Transit performs cryptographic operations within Vault and retains its wrapping keys there. It supports data-key generation, rewrapping, signing, verification, and HMAC. You operate the Vault cluster, including storage, unsealing, authentication, and the Transit mount; Tensor9 operates the KMS adapter.
The adapter serves the AWS KMS API using Vault Transit in the customer environment.
#### Key identity and lifecycle The adapter keeps durable records for AWS key identities, aliases, tags, and lifecycle state. Key creation provisions the corresponding target key. Later requests resolve the AWS identity to that key; the target service performs cryptographic operations and retains its wrapping key material. An alias is a mutable reference in adapter state. Updating it changes which key subsequent alias-based requests select; it does not move key material or rewrite existing ciphertext. Back up adapter state and retain the target keys and versions needed to decrypt stored data. Scheduled deletion records a recovery window of 7-30 days, with 30 days as the default. Cancelling the request returns the key to a disabled state; enable it explicitly before using it again. Final target destruction follows the target's retention rules, which may delay physical removal beyond the adapter's recovery window. #### The Transit engine and its versioned keys Transit receives plaintext or ciphertext and returns the result of the requested operation. Encryption and wrapping keys remain in Vault; generated plaintext data keys can be returned to applications. Rotating a Transit key creates a version for new encryption and retains older versions. The `rewrap` operation updates ciphertext to the latest version; `min_decryption_version` controls which older versions may still decrypt.
Transit performs cryptographic operations in Vault and retains versioned wrapping keys there.
#### The native data key and rewrap `GenerateDataKey` returns a plaintext data key and an encrypted (wrapped) copy. The application uses the plaintext key to encrypt its data locally, then discards that key and stores the wrapped copy beside the encrypted data. To read the data later, it asks the key service to decrypt the wrapped key. Transit implements this with `/transit/datakey/plaintext/:name`; `/transit/datakey/wrapped/:name` returns only the encrypted copy for `GenerateDataKeyWithoutPlaintext`. For rewrapping under the same Transit key, `/transit/rewrap/:name` decrypts the stored value and encrypts it with the current key version within Vault. It does not return plaintext to the caller. A different destination key or changed context requires a decrypt-and-encrypt sequence through the adapter, where plaintext is held temporarily.
The data-key endpoint returns a plaintext key and its encrypted copy. Rewrap updates the encrypted copy without returning plaintext.
#### Signing, verification, and HMAC Transit key types include symmetric `aes256-gcm96` and asymmetric `rsa`, `ecdsa`, and `ed25519`. Symmetric keys support encryption, data-key wrapping, rewrap, and HMAC. Asymmetric keys support signing, verification, and public-key export. `GenerateMac` and `VerifyMac` use Transit's server-side HMAC operations. `DeriveSharedSecret` is unsupported because Transit has no corresponding endpoint.
Transit supports encryption, data keys, rewrap, signing, verification, and HMAC.
#### Encryption context, bound as associated data An encryption context is a non-secret key/value map bound to ciphertext as additional authenticated data (AAD). Decryption requires the same context. Applications can use it to bind encrypted values to a tenant or purpose. The adapter sends encryption context as `associated_data` for encryption, decryption, rewrap, and data-key generation. A mismatch causes decryption to fail. This differs from Transit's `context` parameter, which is used for key derivation.
Transit authenticates the encryption context through associated\_data . Decryption requires the same context.
#### Minimum decryption version Key rotation creates a new version for subsequent encryption. Retained, enabled older versions remain available to decrypt existing ciphertext. Transit's `min_decryption_version` limits which retained versions can decrypt. Its usual value of 1 permits all versions. Raising it prevents decryption of ciphertext using a lower version; rotation alone does not impose that restriction. The adapter keeps `min_decryption_version = 1` on the keys it manages. Raising it or destroying an old version prevents access to affected ciphertext and must be handled as a separate change.
The adapter sets min\_decryption\_version = 1 . Raising it prevents older versions from decrypting their ciphertext.
#### Limitations **Deletion and disabled state.** Transit has no AWS scheduled-deletion window or single enabled flag. The adapter records the recovery window. Version thresholds restrict particular versions; they do not disable every operation on a key. Coordinate adapter state with Vault access policy. **Authorization and regions.** Vault ACL policies control Transit paths. AWS grant and key-policy APIs are not recreated. Vault Enterprise replication is separate cluster configuration; it does not provide this mapping's ReplicateKey or UpdatePrimaryRegion API. **Re-encryption.** Transit rewrap changes the version of the same named key. ReEncrypt to a different key or with a changed encryption context requires decrypting and encrypting through the adapter. Intermediate plaintext is not returned to the caller. **Version retention and import.** Raising min\_decryption\_version prevents older versions from decrypting. Imported material uses Transit's import workflow; asymmetric data-key pairs require local generation and wrapping. DeriveSharedSecret is outside this mapping. #### Other considerations **Operate Vault.** The platform team runs Vault storage, unsealing, authentication, backups, and the Transit mount. The adapter uses its configured Vault identity; restrict its ACL paths to the required key operations. **Protect both state stores.** Back up adapter key identities and aliases as well as Vault storage. A surviving alias cannot decrypt data if its target key or required version has been lost. **Migrate ciphertext.** Keep AWS available to decrypt values or unwrap data keys, then encrypt or wrap them under Transit before retiring AWS access. Existing AWS ciphertext cannot be used directly with a newly created Transit key. [Service Catalog](/service-adapters/catalog).