kms

func (*KMS) Connect ¶

func (k *KMS) Connect(parentSegment ...*xray.XRayParentSegment) (err error)

Connect will establish a connection to the KMS service

func (*KMS) DecryptViaCmkAes256 ¶

func (k *KMS) DecryptViaCmkAes256(cipherText string) (plainText string, err error)

DecryptViaCmkAes256 will use kms cmk to decrypt cipherText using symmetric aes 256 kms cmk key, and return plainText string, the cipherText can only be decrypted with the symmetric aes 256 kms cmk key

func (*KMS) DecryptViaCmkRsa2048 ¶

func (k *KMS) DecryptViaCmkRsa2048(cipherText string) (plainText string, err error)

DecryptViaCmkRsa2048 will use kms cmk to decrypt cipherText using asymmetric rsa 2048 kms cmk private key, and return plainText string, the cipherText can only be decrypted with the asymmetric rsa 2048 kms cmk private key

func (*KMS) DecryptViaCmkRsa2048PKCS1 ¶ added in v1.5.9

func (k *KMS) DecryptViaCmkRsa2048PKCS1(cipherText string) (plainText string, err error)

DecryptViaCmkRsa2048PKCS1 will use kms cmk to decrypt cipherText using asymmetric rsa 2048 kms cmk private key, and return plainText string, the cipherText can only be decrypted with the asymmetric rsa 2048 kms cmk private key

func (*KMS) DecryptWithDataKeyAes256 ¶

func (k *KMS) DecryptWithDataKeyAes256(cipherText string, cipherKey string) (plainText string, err error)

DecryptWithDataKeyAes256 will decrypt cipherText using cipherKey that was generated via GenerateDataKeyAes256()

cipherKey = encrypted data key in hex (must use KMS CMK to decrypt such key)

Plaintext-handling caveat (F6 pass-3 contrarian 2026-04-14; corrected SP-008 lens-3 2026-04-15):

Same caveat as EncryptWithDataKeyAes256. The string() conversion of the KMS plaintext data key creates an immutable heap copy. The subsequent SetPlaintext([]byte{}) call is a pointer reassignment (per aws-sdk-go/service/kms/api.go) — it does NOT overwrite the original SDK-owned backing slice; it merely rebinds the dataKeyOutput.Plaintext field to an empty slice and leaves the prior backing array live on the heap, unreferenced but intact, until GC. Both the heap string copy and the former SDK slice remain readable in process memory from the string() conversion until GC reclaims them (and may persist on recycled pages even after GC). Treat scrubbing as best-effort reference-drop only. See EncryptWithDataKeyAes256 godoc for the full discussion.

func (*KMS) Disconnect ¶

func (k *KMS) Disconnect()

Disconnect will disjoin from aws session by clearing it

func (*KMS) ECDH ¶ added in v1.5.2

func (k *KMS) ECDH(keyArn, ephemeralPublicKeyB64 string) (sharedSecret []byte, err error)

func (*KMS) EncryptViaCmkAes256 ¶

func (k *KMS) EncryptViaCmkAes256(plainText string) (cipherText string, err error)

EncryptViaCmkAes256 will use kms cmk to encrypt plainText using aes 256 symmetric kms cmk key, and return cipherText string, the cipherText can only be decrypted with aes 256 symmetric kms cmk key

func (*KMS) EncryptViaCmkRsa2048 ¶

func (k *KMS) EncryptViaCmkRsa2048(plainText string) (cipherText string, err error)

EncryptViaCmkRsa2048 will use kms cmk to encrypt plainText with asymmetric rsa 2048 kms cmk public key, and return cipherText string, the cipherText can only be decrypted with the paired asymmetric rsa 2048 kms cmk private key

*** To Encrypt using Public Key Outside of KMS ***

1. Copy Public Key from AWS KMS for the given RSA CMK
2. Using External RSA Public Key Crypto Encrypt Function with the given Public Key to Encrypt

func (*KMS) EncryptWithDataKeyAes256 ¶

func (k *KMS) EncryptWithDataKeyAes256(plainText string, cipherKey string) (cipherText string, err error)

EncryptWithDataKeyAes256 will encrypt plainText using cipherKey that was generated via GenerateDataKeyAes256()

cipherKey = encrypted data key in hex (must use KMS CMK to decrypt such key)

Plaintext-handling caveat (F6 pass-3 contrarian 2026-04-14; corrected SP-008 lens-3 2026-04-15):

This helper converts the KMS plaintext data key to a Go string via string(dataKeyOutput.Plaintext) to pass it to crypto.AesGcmEncrypt. The string() conversion copies the bytes onto the Go heap as an immutable string header. The subsequent dataKeyOutput.SetPlaintext( []byte{}) call does NOT zero-scrub the original SDK-owned backing slice — per aws-sdk-go/service/kms/api.go, SetPlaintext is simply `s.Plaintext = v`, a pointer reassignment that rebinds the struct field to the fresh empty slice and leaves the previous backing array live on the heap, unreferenced but intact, until the Go garbage collector reclaims it.

Concretely, two copies of the plaintext data key coexist in process memory between the string() conversion and the next GC cycle:

1. The immutable Go-heap string copy produced by string(...).
2. The original AWS SDK-owned []byte that is no longer referenced by dataKeyOutput after SetPlaintext but has not been overwritten.

Either copy is visible to heap scanners, debuggers, or a core dump captured during that window. Neither copy is guaranteed to be overwritten even after GC — the memory pages may be recycled and re-used without being zeroed.

Treat the SetPlaintext call as best-effort reference drop only: it makes both copies GC-eligible, but it does NOT overwrite any bytes. Callers that need stronger scrubbing guarantees must use a []byte-based AEAD API that never converts to string and manually overwrites the plaintext slice before release (not currently exposed by this package).

func (*KMS) GenerateDataKeyAes256 ¶

func (k *KMS) GenerateDataKeyAes256() (cipherKey string, err error)

GenerateDataKeyAes256 will return an encrypted data key generated by kms cmk, this data key is encrypted, and able to decrypt only via kms cmk (therefore it is safe to store in memory or at rest)

cipherKey = encrypted data key in hex (must use KMS CMK to decrypt such key)

func (*KMS) GenerateEncryptionDecryptionKeyRsa2048 ¶ added in v1.5.2

func (k *KMS) GenerateEncryptionDecryptionKeyRsa2048(keyName string, keyPolicyJSON string) (encryptedOutput *kms.CreateKeyOutput, err error)

GenerateEncryptionDecryptionKeyRsa2048 will generate a new rsa 2048 key pair using kms cmk, and return the creation output the key pair can only be used for rsa 2048 asymmetric encryption/decryption keyName = the Alias name to create keyPolicy = the key policy json string to apply

keyPolicy := map[string]interface{}{
	"Id":      "key-consolepolicy-3",
	"Version": "2012-10-17",
	"Statement": []map[string]interface{}{
		{
			"Effect":    "Allow",
			"Principal": map[string]interface{}{"AWS": "arn:aws:iam::***************:user/xxxxxxxxxxxxxxxxxxx"}, // Replace with your account ID
			"Action":    "kms:*",
			"Resource":  "*",
		},
		{
			"Sid":       "Allow access for Key Administrators",
			"Effect":    "Allow",
			"Principal": map[string]interface{}{"AWS": "arn:aws:iam::***************:user/xxxxxxxxxxxxxxxxxxx"}, // Replace with your account ID
			"Action":    "kms:*",
			"Resource":  "*",
		},
		{
			"Sid":       "Allow access for Key Administrators",
			"Effect":    "Allow",
			"Principal": map[string]interface{}{"AWS": "arn:aws:iam::***************:user/xxxxxxxxxxxxxxxxxxx"},
			"Action": []string{
				"kms:Create*",
				"kms:Describe*",
				"kms:Enable*",
				"kms:List*",
				"kms:Put*",
				"kms:Update*",
				"kms:Revoke*",
				"kms:Disable*",
				"kms:Get*",
				"kms:Delete*",
				"kms:TagResource",
				"kms:UntagResource",
				"kms:ScheduleKeyDeletion",
				"kms:CancelKeyDeletion",
			},
			"Resource": "*",
		},
		{
			"Sid":       "Allow use of the key",
			"Effect":    "Allow",
			"Principal": map[string]interface{}{"AWS": "arn:aws:iam::***************:user/xxxxxxxxxxxxxxxxxxx"},
			"Action": []string{
				"kms:Encrypt",
				"kms:Decrypt",
				"kms:ReEncrypt*",
				"kms:DescribeKey",
				"kms:GetPublicKey",
			},
			"Resource": "*",
		},
		{
			"Sid":       "Allow attachment of persistent resources",
			"Effect":    "Allow",
			"Principal": map[string]interface{}{"AWS": "arn:aws:iam::***************:user/xxxxxxxxxxxxxxxxxxx"},
			"Action": []string{
				"kms:CreateGrant",
				"kms:ListGrants",
				"kms:RevokeGrant",
			},
			"Resource": "*",
			"Condition": map[string]interface{}{
				"Bool": map[string]interface{}{
					"kms:GrantIsForAWSResource": "true",
				},
			},
		},
	},
}

func (*KMS) GenerateSignVerifyKeyRsa2048 ¶ added in v1.5.2

func (k *KMS) GenerateSignVerifyKeyRsa2048(keyName string, keyPolicy interface{}) (encryptedOutput *kms.CreateKeyOutput, err error)

func (*KMS) GetRSAPublicKey ¶ added in v1.5.2

func (k *KMS) GetRSAPublicKey(alias string) (output *kms.GetPublicKeyOutput, err error)

func (*KMS) ImportECCP256SignVerifyKey ¶ added in v1.5.2

func (k *KMS) ImportECCP256SignVerifyKey(keyAlias, keyPolicyJson string, eccPvk *ecdsa.PrivateKey) (keyArn string, err error)

func (*KMS) KeyDeleteWithAlias ¶ added in v1.5.2

func (k *KMS) KeyDeleteWithAlias(alias string, PendingWindowInDays int64) (output *kms.ScheduleKeyDeletionOutput, err error)

func (*KMS) KeyDeleteWithArnID ¶ added in v1.5.2

func (k *KMS) KeyDeleteWithArnID(arn string, PendingWindowInDays int64) (output *kms.ScheduleKeyDeletionOutput, err error)

func (*KMS) ReEncryptViaCmkAes256 ¶

func (k *KMS) ReEncryptViaCmkAes256(sourceCipherText string, targetKmsKeyName string) (targetCipherText string, err error)

ReEncryptViaCmkAes256 will re-encrypt sourceCipherText using the new targetKmsKeyName via kms, (must be targeting aes 256 key) the re-encrypted cipherText is then returned

func (*KMS) ReEncryptViaCmkRsa2048 ¶

func (k *KMS) ReEncryptViaCmkRsa2048(sourceCipherText string, targetKmsKeyName string) (targetCipherText string, err error)

ReEncryptViaCmkRsa2048 will re-encrypt sourceCipherText using the new targetKmsKeyName via kms, (must be targeting rsa 2048 key) the re-encrypted cipherText is then returned

func (*KMS) SignViaCmkRsa2048 ¶

func (k *KMS) SignViaCmkRsa2048(dataToSign string) (signature string, err error)

SignViaCmkRsa2048 will sign dataToSign using KMS CMK RSA Sign/Verify Key (Private Key on KMS will be used to securely sign)

func (*KMS) UpdateParentSegment ¶ added in v1.1.4

func (k *KMS) UpdateParentSegment(parentSegment *xray.XRayParentSegment)

UpdateParentSegment updates this struct's xray parent segment, if no parent segment, set nil

func (*KMS) VerifyViaCmkRsa2048 ¶

func (k *KMS) VerifyViaCmkRsa2048(dataToVerify string, signatureToVerify string) (signatureValid bool, err error)

VerifyViaCmkRsa2048 will verify dataToVerify with signature using KMS CMK RSA Sign/Verify Key (Public Key on KMS will be used securely to verify)

signatureToVerify = prior signed signature in hex to verify against the dataToVerify parameter

*** To Verify using Public Key Outside of KMS ***

1. Copy Public Key from AWS KMS for the given RSA CMK
2. Using External RSA Public Key Crypto Verify Function with the given Public Key to Verify