Cryptography Client for Azure Key Vault

👁 reference
👁 ci
👁 codecov

This module provides a cryptography client for the Azure Key Vault Keys client module for Go. This project is not supported by the Azure SDK team, but does align with the cryptography clients in other supported languages like the CryptographyClient I wrote for the Azure SDK for .NET. See related projects for more information.

Getting started

Install packages

Install azcrypto and azidentity with go get:

go get github.com/heaths/azcrypto
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

azidentity is used for Azure Active Directory authentication as demonstrated below.

Prerequisites

• An Azure subscription.
• An Azure key vault or managed HSM. If you need to create one, see the Key Vault documentation for instructions using the Azure Portal or the Azure CLI.

Authentication

This document demonstrates using azidentity.NewDefaultAzureCredential to authenticate. This credential type works in both local development and production environments. We recommend using a managed identity in production.

NewClient accepts any azcore.TokenCredential including those from azidentity. See the azidentity documentation for more information about other credential types.

Create a client

Constructing the client requires your key's URL, called a key ID, which you can get from the Azure Portal or Azure CLI. You should store this key ID including the version used to encrypt, sign, or wrap with your data to make sure you can decrypt, verify, and unwrap.

import (
 "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
 "github.com/heaths/azcrypto"
)

func main() {
 cred, err := azidentity.NewDefaultAzureCredential(nil)
 if err != nil {
 // TODO: handle error
 }

 client, err := azcrypto.NewClient(
 "https://{vault-name}.vault.azure.net/keys/{key-name}/{key-version}",
 cred,
 nil,
 )
 if err != nil {
 // TODO: handle error
 }
}

You can also create a Client from a JSON Web Key (JWK) using NewClientFromJSONWebKey. No attempt to connect to Azure Key Vault or Managed HSM will be made.

Key concepts

The Client will attempt to download the specified public key when first used. This will improve throughput while reducing the risk of getting throttled by Key Vault's rate limits.

Encrypt and decrypt

You can encrypt with a public key, but decryption requires a private key to which Azure Key Vault or Managed HSM does not provide access. The following encryption operation will be performed locally if the caller has the keys/get data action permission, and decrypted remotely.

import (
 "context"

 "github.com/heaths/azcrypto"
)

func encryptAndDecrypt(client *azcrypto.Client, plaintext string) (string, error) {
 encryptResult, err := client.Encrypt(
 context.TODO(),
 azcrypto.EncryptAlgorithmRSAOAEP256,
 []byte(plaintext),
 nil,
 )
 if err != nil {
 return "", err
 }

 decryptResult, err := client.Decrypt(
 context.TODO(),
 azcrypto.EncryptAlgorithmRSAOAEP256,
 encryptResult.Ciphertext,
 nil,
 )
 if err != nil {
 return "", err
 }

 return string(decryptResult.Plaintext), nil
}

Sign and verify

You can verify a signature with a public key, but signing requires a private key to which Azure Key Vault or Managed HSM does not provide access. The following signing operation will be performed on Key Vault or Managed HSM, but verification will be performed locally if the caller has the keys/get data action permission.

import (
 "context"
 "crypto/sha256"

 "github.com/heaths/azcrypto"
)

func signAndVerify(client *azcrypto.Client, plaintext string) (bool, error) {
 // Performed remotely by Azure Key Vault or Managed HSM.
 signResult, err := client.SignData(
 context.TODO(),
 azcrypto.SignAlgorithmES256,
 []byte(plaintext),
 nil,
 )
 if err != nil {
 return false, err
 }

 // Performed locally if the public key could be retrieved.
 verifyResult, err := client.VerifyData(
 context.TODO(),
 signResult.Algorithm,
 []byte(plaintext),
 signResult.Signature,
 nil,
 )
 if err != nil {
 return false, err
 }

 return verifyResult.Valid, nil
}

Key wrap and unwrap

You can wrap a key - typically a key used for symmetric algorithms such as AES - with a public key, but unwrapping the key requires a private key to which Azure Key Vault or Managed HSM does not provide access. The following wrapping operation will be performed locally if the caller has the keys/get data action permission, and unwrapped remotely on Key Vault or Managed HSM.

This is useful for keeping symmetric algorithm keys such as AES secure while taking advantage of symmetric keys' speed for use in block ciphers.

import (
 "context"

 "github.com/heaths/azcrypto"
)

func wrapAndUnwrapKey(client *azcrypto.Client, key []byte) ([]byte, error) {
 wrappedKey, err := client.WrapKey(
 context.TODO(),
 azcrypto.WrapKeyAlgorithmRSAOAEP256,
 key,
 nil,
 )
 if err != nil {
 return nil, err
 }

 unwrappedKey, err := client.Decrypt(
 context.TODO(),
 azcrypto.WrapKeyAlgorithmRSAOAEP256,
 wrappedKey.EncryptedKey,
 nil,
 )
 if err != nil {
 return nil, err
 }

 return unwrappedKey.Key, nil
}

Examples

Get started with our examples.

Related projects

Though not officially part of the Azure SDKs, this module was developed using the same guidelines. Convenience methods have been added to help call cryptographic key operations correctly, as well as support for caching public keys when permitted, and using a JWK in scenarios it may be stored as an Azure Key Vault secret.

For more information about the other Key Vault SDKs, see https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/security/keyvault or, for individual packages:

• github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azcertificates (source)
• github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys (source)
• github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets (source)

License

Licensed under the MIT license.

Constants ¶

Variables ¶

Functions ¶

Types ¶

type Client struct {
	// contains filtered or unexported fields
}

func NewClient(keyID string, credential azcore.TokenCredential, options *ClientOptions) (*Client, error)

func NewClientFromJSONWebKey(key azkeys.JSONWebKey, options *ClientOptions) (*Client, error)

func (client *Client) Decrypt(ctx context.Context, algorithm EncryptAlgorithm, ciphertext []byte, options *DecryptOptions) (DecryptResult, error)

func (client *Client) DecryptAESCBC(ctx context.Context, algorithm EncryptAESCBCAlgorithm, ciphertext, iv []byte, options *DecryptAESCBCOptions) (DecryptAESCBCResult, error)

func (client *Client) DecryptAESGCM(ctx context.Context, algorithm EncryptAESGCMAlgorithm, ciphertext, nonce, authenticationTag, additionalAuthenticatedData []byte, options *DecryptAESGCMOptions) (DecryptAESGCMResult, error)

func (client *Client) Encrypt(ctx context.Context, algorithm EncryptAlgorithm, plaintext []byte, options *EncryptOptions) (EncryptResult, error)

func (client *Client) EncryptAESCBC(ctx context.Context, algorithm EncryptAESCBCAlgorithm, plaintext, iv []byte, options *EncryptAESCBCOptions) (EncryptAESCBCResult, error)

func (client *Client) EncryptAESGCM(ctx context.Context, algorithm EncryptAESCBCAlgorithm, plaintext, additionalAuthenticatedData []byte, options *EncryptAESGCMOptions) (EncryptAESGCMResult, error)

func (client *Client) KeyID() string

func (client *Client) Sign(ctx context.Context, algorithm SignAlgorithm, digest []byte, options *SignOptions) (SignResult, error)

func (client *Client) SignData(ctx context.Context, algorithm SignAlgorithm, data []byte, options *SignDataOptions) (SignResult, error)

func (client *Client) UnwrapKey(ctx context.Context, algorithm WrapKeyAlgorithm, encryptedKey []byte, options *UnwrapKeyOptions) (UnwrapKeyResult, error)

func (client *Client) Verify(ctx context.Context, algorithm SignAlgorithm, digest, signature []byte, options *VerifyOptions) (VerifyResult, error)

func (client *Client) VerifyData(ctx context.Context, algorithm SignAlgorithm, data, signature []byte, options *VerifyDataOptions) (VerifyResult, error)

func (client *Client) WrapKey(ctx context.Context, algorithm WrapKeyAlgorithm, key []byte, options *WrapKeyOptions) (WrapKeyResult, error)

type ClientOptions struct {
	azkeys.ClientOptions

	// Rand should be a cryptographically random number generator.
	// The default is crypto/Rand.Reader.
	Rand io.Reader
	// contains filtered or unexported fields
}

type DecryptAESCBCOptions struct {
	azkeys.DecryptOptions
}

type DecryptAESCBCResult = alg.DecryptResult

type DecryptAESGCMOptions struct {
	azkeys.DecryptOptions
}

type DecryptAESGCMResult = alg.DecryptResult

type DecryptOptions struct {
	azkeys.DecryptOptions
}

type DecryptResult = alg.DecryptResult

type EncryptAESCBCAlgorithm = alg.EncryptAESCBCAlgorithm

const (
	// EncryptAESCBCAlgorithmA128CBC uses A128-CBC with a message length appropriately padded to a multiple of 16 bytes.
	//
	// You should not use CBC without first ensuring the integrity of the ciphertext using an HMAC.
	EncryptAESCBCAlgorithmA128CBC EncryptAESCBCAlgorithm = azkeys.EncryptionAlgorithmA128CBC

	// EncryptAESCBCAlgorithmA128CBC uses A128-CBCPAD to pad a message using PKCS7 to a multiple of 16 bytes.
	//
	// You should not use CBC without first ensuring the integrity of the ciphertext using an HMAC.
	EncryptAESCBCAlgorithmA128CBCPAD EncryptAESCBCAlgorithm = azkeys.EncryptionAlgorithmA128CBCPAD

	// EncryptAESCBCAlgorithmA192CBC uses A192-CBC with a message length appropriately padded to a multiple of 16 bytes.
	//
	// You should not use CBC without first ensuring the integrity of the ciphertext using an HMAC.
	EncryptAESCBCAlgorithmA192CBC EncryptAESCBCAlgorithm = azkeys.EncryptionAlgorithmA192CBC

	// EncryptAESCBCAlgorithmA192CBC uses A192-CBCPAD to pad a message using PKCS7 to a multiple of 16 bytes.
	//
	// You should not use CBC without first ensuring the integrity of the ciphertext using an HMAC.
	EncryptAESCBCAlgorithmA192CBCPAD EncryptAESCBCAlgorithm = azkeys.EncryptionAlgorithmA192CBCPAD

	// EncryptAESCBCAlgorithmA256CBC uses A256-CBC with a message length appropriately padded to a multiple of 16 bytes.
	//
	// You should not use CBC without first ensuring the integrity of the ciphertext using an HMAC.
	EncryptAESCBCAlgorithmA256CBC EncryptAESCBCAlgorithm = azkeys.EncryptionAlgorithmA256CBC

	// EncryptAESCBCAlgorithmA256CBC uses A256-CBCPAD to pad a message using PKCS7 to a multiple of 16 bytes.
	//
	// You should not use CBC without first ensuring the integrity of the ciphertext using an HMAC.
	EncryptAESCBCAlgorithmA256CBCPAD EncryptAESCBCAlgorithm = azkeys.EncryptionAlgorithmA256CBCPAD
)

type EncryptAESCBCOptions struct {
	azkeys.EncryptOptions
}

type EncryptAESCBCResult struct {
	// Algorithm is encryption algorithm used to encrypt.
	Algorithm EncryptAlgorithm

	// KeyID is the key ID used to encrypt. This key ID should be retained.
	KeyID string

	// Ciphertext is the encryption result.
	Ciphertext []byte

	// IV is the initialization vector used to encrypt using AES-CBC.
	IV []byte
}

type EncryptAESGCMAlgorithm = alg.EncryptAESGCMAlgorithm

const (
	// EncryptAESGCMAlgorithmA128GCM uses A128-GCM with optional authenticated data.
	EncryptAESGCMAlgorithmA128GCM EncryptAESGCMAlgorithm = azkeys.EncryptionAlgorithmA128GCM

	// EncryptAESGCMAlgorithmA192GCM uses A192-GCM with optional authenticated data.
	EncryptAESGCMAlgorithmA192GCM EncryptAESGCMAlgorithm = azkeys.EncryptionAlgorithmA192GCM

	// EncryptAESGCMAlgorithmA256GCM uses A256-GCM with optional authenticated data.
	EncryptAESGCMAlgorithmA256GCM EncryptAESGCMAlgorithm = azkeys.EncryptionAlgorithmA256GCM
)

type EncryptAESGCMOptions struct {
	azkeys.EncryptOptions
}

type EncryptAESGCMResult struct {
	// Algorithm is encryption algorithm used to encrypt.
	Algorithm EncryptAlgorithm

	// KeyID is the key ID used to encrypt. This key ID should be retained.
	KeyID string

	// Ciphertext is the encryption result.
	Ciphertext []byte

	// Nonce is the nonce used to encrypt using AES-GCM.
	Nonce []byte

	// AdditionalAuthenticatedData passed to EncryptAESGCM.
	AdditionalAuthenticatedData []byte

	// AuthenticationTag returned from EncryptAESGCM.
	AuthenticationTag []byte
}

type EncryptAlgorithm = alg.EncryptAlgorithm

const (
	// EncryptAlgorithmRSA15 uses RSA 1.5.
	EncryptAlgorithmRSA15 EncryptAlgorithm = azkeys.EncryptionAlgorithmRSA15

	// EncryptAlgorithmRSAOAEP uses RSA-OAEP.
	EncryptAlgorithmRSAOAEP EncryptAlgorithm = azkeys.EncryptionAlgorithmRSAOAEP

	// EncryptAlgorithmRSAOAEP256 uses RSA-OAEP-256.
	EncryptAlgorithmRSAOAEP256 EncryptAlgorithm = azkeys.EncryptionAlgorithmRSAOAEP256
)

type EncryptOptions struct {
	azkeys.EncryptOptions
}

type EncryptResult struct {
	// Algorithm is encryption algorithm used to encrypt.
	Algorithm EncryptAlgorithm

	// KeyID is the key ID used to encrypt. This key ID should be retained.
	KeyID string

	// Ciphertext is the encryption result.
	Ciphertext []byte
}

type SignAlgorithm = alg.SignAlgorithm

const (
	// SignAlgorithmES256 uses the P-256 curve requiring a SHA-256 hash.
	SignAlgorithmES256 SignAlgorithm = azkeys.SignatureAlgorithmES256

	// SignAlgorithmES256K uses the P-256K curve requiring a SHA-256 hash.
	SignAlgorithmES256K SignAlgorithm = azkeys.SignatureAlgorithmES256K

	// SignAlgorithmES384 uses the P-384 curve requiring a SHA-384 hash.
	SignAlgorithmES384 SignAlgorithm = azkeys.SignatureAlgorithmES384

	// SignAlgorithmES512 uses the P-521 curve requiring a SHA-512 hash.
	SignAlgorithmES512 SignAlgorithm = azkeys.SignatureAlgorithmES512

	// SignAlgorithmPS256 uses RSASSA-PSS using a SHA-256 hash.
	SignAlgorithmPS256 SignAlgorithm = azkeys.SignatureAlgorithmPS256

	// SignAlgorithmPS384 uses RSASSA-PSS using a SHA-384 hash.
	SignAlgorithmPS384 SignAlgorithm = azkeys.SignatureAlgorithmPS384

	// SignAlgorithmPS512 uses RSASSA-PSS using a SHA-512 hash.
	SignAlgorithmPS512 SignAlgorithm = azkeys.SignatureAlgorithmPS512

	// SignAlgorithmRS256 uses RSASSA-PKCS1-v1_5 using a SHA256 hash.
	SignAlgorithmRS256 SignAlgorithm = azkeys.SignatureAlgorithmRS256

	// SignAlgorithmRS384 uses RSASSA-PKCS1-v1_5 using a SHA384 hash.
	SignAlgorithmRS384 SignAlgorithm = azkeys.SignatureAlgorithmRS384

	// SignAlgorithmRS512 uses RSASSA-PKCS1-v1_5 using a SHA512 hash.
	SignAlgorithmRS512 SignAlgorithm = azkeys.SignatureAlgorithmRS512
)

type SignDataOptions struct {
	SignOptions
}

type SignOptions struct {
	azkeys.SignOptions
}

type SignResult = alg.SignResult

type UnwrapKeyOptions struct {
	azkeys.UnwrapKeyOptions
}

type UnwrapKeyResult = alg.UnwrapKeyResult

type VerifyDataOptions struct {
	VerifyOptions
}

type VerifyOptions struct {
	azkeys.VerifyOptions
}

type VerifyResult = alg.VerifyResult

type WrapKeyAlgorithm = alg.WrapKeyAlgorithm

const (
	// WrapKeyAlgorithmRSA15 uses RSA 1.5.
	WrapKeyAlgorithmRSA15 WrapKeyAlgorithm = azkeys.EncryptionAlgorithmRSA15

	// WrapKeyAlgorithmRSAOAEP uses RSA-OAEP.
	WrapKeyAlgorithmRSAOAEP WrapKeyAlgorithm = azkeys.EncryptionAlgorithmRSAOAEP

	// WrapKeyAlgorithmRSAOAEP256 uses RSA-OAEP-256.
	WrapKeyAlgorithmRSAOAEP256 WrapKeyAlgorithm = azkeys.EncryptionAlgorithmRSAOAEP256

	// WrapKeyAlgorithmA128KW uses A128-KW.
	WrapKeyAlgorithmA128KW WrapKeyAlgorithm = azkeys.EncryptionAlgorithmA128KW

	// WrapKeyAlgorithmA192KW uses A192-KW.
	WrapKeyAlgorithmA192KW WrapKeyAlgorithm = azkeys.EncryptionAlgorithmA192KW

	// WrapKeyAlgorithmA256KW uses A256-KW.
	WrapKeyAlgorithmA256KW WrapKeyAlgorithm = azkeys.EncryptionAlgorithmA256KW
)

type WrapKeyOptions struct {
	azkeys.WrapKeyOptions
}

type WrapKeyResult = alg.WrapKeyResult