kms

package
v1.8.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type KMS 

type KMS struct {
	// define the AWS region that KMS is located at
	AwsRegion awsregion.AWSRegion

	// custom http2 client options
	HttpOptions *awshttp2.HttpClientSettings

	// define kms key name
	AesKmsKeyName       string
	RsaKmsKeyName       string
	SignatureKmsKeyName string

	// optional: override AWS endpoint URL for testing (e.g., LocalStack)
	CustomEndpoint string
	// contains filtered or unexported fields
}

KMS struct encapsulates the AWS KMS access functionality

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.