azure

README

Azure KMS

In order to use Azure KMS (Key Vault) with the sigstore project you need to have a few things setup in Azure first. The key creation will be handled in sigstore, however the Azure Key Vault and the required permission will have to be configured before.

Azure Prerequisites

• Resource Group
• Key Vault
• Key Vault permissions
• Container Registry (not required, but used in below examples)

Permissions (Access Policies)

Different commands require different Key Vault access policies. For more information check the official Azure Docs.

Using Azure KMS with Cosign

An Azure KMS key must be provided in the following format: azurekms://[Key Vault Name].vault.azure.net/[Key Name]

A specific key version can optionally be provided: azurekms://[Key Vault Name].vault.azure.net/[Key Name]/[Key Version]

cosign generate-key-pair

Required access policies (keys): get, create

cosign generate-key-pair --kms azurekms://[Key Vault Name].vault.azure.net/[Key Name]

cosign sign

Required access policies (keys): get, sign

az acr login --name [Container Registry Name]
cosign sign --key azurekms://[Key Vault Name].vault.azure.net/[Key Name] [Container Registry Name].azurecr.io/[Image Name]

cosign verify

Required access policy (keys): verify

az acr login --name [Container Registry Name]
cosign verify --key azurekms://[Key Vault Name].vault.azure.net/[Key Name] [Container Registry Name].azurecr.io/[Image Name]

Authentication

There are multiple authentication methods supported for Azure Key Vault and by default they will be evaluated in the following order:

1. Client credentials (FromEnvironment)
2. Client certificate (FromEnvironment)
3. Username password (FromEnvironment)
4. MSI (FromEnvironment)
5. CLI (FromCLI)

You can force either FromEnvironment or FromCLI by configuring the environment variable AZURE_AUTH_METHOD to either environment or cli.

For backward compatibility, if you configure AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET, FromEnvironment will be used.

If you would like to use a cloud other than the Azure public cloud, configure AZURE_ENVIRONMENT. The following values are accepted:

• AZUREUSGOVERNMENT, AZUREUSGOVERNMENTCLOUD uses the Azure US Government Cloud
• AZURECHINACLOUD uses Azure China Cloud
• AZURECLOUD, AZUREPUBLICCLOUD uses the public cloud

If AZURE_ENVIRONMENT is not configured, Azure public cloud is used.

Integration Testing

In addition to unit tests in this module, there is integration_test.go, which requires you to provide either environment or CLI credentials. Because the Sigstore project does not use Azure, the tests are not run as part of any CI/CD. These tests are for Azure client developers to test that changes work as expected against their own Azure subscription.

Run the integration tests with go test -tags=integration ./... in the root of this module.

Documentation

Overview

Package azure implement the interface with microsoft azure kms service

Package azure contains utilities related to Microsoft Azure KMS.

Index

• Constants
• func ValidReference(ref string) error
• type SignerVerifier
  • func LoadSignerVerifier(defaultCtx context.Context, referenceStr string) (*SignerVerifier, error)
  • func (a *SignerVerifier) CreateKey(ctx context.Context, _ string) (crypto.PublicKey, error)
  • func (a *SignerVerifier) CryptoSigner(ctx context.Context, errFunc func(error)) (myhash.Signer, myhash.SignerOpts, error)
  • func (*SignerVerifier) DefaultAlgorithm() string
  • func (a *SignerVerifier) PublicKey(_ ...signature.PublicKeyOption) (crypto.PublicKey, error)
  • func (a *SignerVerifier) SignMessage(message io.Reader, opts ...signature.SignOption) ([]byte, error)
  • func (*SignerVerifier) SupportedAlgorithms() []string
  • func (a *SignerVerifier) VerifySignature(sig, message io.Reader, opts ...signature.VerifyOption) error

Constants

const (
	AlgorithmES256 = "ES256"
	AlgorithmES384 = "ES384"
	AlgorithmES512 = "ES512"
)

const (
	// ReferenceScheme schemes for various KMS services are copied from https://github.com/google/go-cloud/tree/master/secrets
	ReferenceScheme = "azurekms://"
)

Functions

func ValidReference

func ValidReference(ref string) error

ValidReference returns a non-nil error if the reference string is invalid

Types

type SignerVerifier

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

SignerVerifier creates and verifies digital signatures over a message using Azure KMS service

func LoadSignerVerifier

func LoadSignerVerifier(defaultCtx context.Context, referenceStr string) (*SignerVerifier, error)

LoadSignerVerifier generates signatures using the specified key in Azure Key Vault and hash algorithm.

It also can verify signatures locally using the public key. hashFunc must not be crypto.Hash(0).

func (*SignerVerifier) CreateKey

func (a *SignerVerifier) CreateKey(ctx context.Context, _ string) (crypto.PublicKey, error)

CreateKey attempts to create a new key in Vault with the specified algorithm.

func (*SignerVerifier) CryptoSigner

func (a *SignerVerifier) CryptoSigner(ctx context.Context, errFunc func(error)) (myhash.Signer, myhash.SignerOpts, error)

CryptoSigner returns a crypto.Signer object that uses the underlying SignerVerifier, along with a crypto.SignerOpts object that allows the KMS to be used in APIs that only accept the standard golang objects

func (*SignerVerifier) DefaultAlgorithm

func (*SignerVerifier) DefaultAlgorithm() string

DefaultAlgorithm returns the default algorithm for the Azure KMS service

func (*SignerVerifier) PublicKey

func (a *SignerVerifier) PublicKey(_ ...signature.PublicKeyOption) (crypto.PublicKey, error)

PublicKey returns the public key that can be used to verify signatures created by this signer. All options provided in arguments to this method are ignored.

func (*SignerVerifier) SignMessage

func (a *SignerVerifier) SignMessage(message io.Reader, opts ...signature.SignOption) ([]byte, error)

SignMessage signs the provided message using Azure Key Vault. If the message is provided, this method will compute the digest according to the hash function specified when the Signer was created.

SignMessage recognizes the following Options listed in order of preference:

- WithContext()

- WithDigest()

- WithCryptoSignerOpts()

All other options are ignored if specified.

func (*SignerVerifier) SupportedAlgorithms

func (*SignerVerifier) SupportedAlgorithms() []string

SupportedAlgorithms returns the list of algorithms supported by the Azure KMS service

func (*SignerVerifier) VerifySignature

func (a *SignerVerifier) VerifySignature(sig, message io.Reader, opts ...signature.VerifyOption) error

VerifySignature verifies the signature for the given message. Unless provided in an option, the digest of the message will be computed using the hash function specified when the SignerVerifier was created.

This function returns nil if the verification succeeded, and an error message otherwise.

This function recognizes the following Options listed in order of preference:

- WithDigest()

All other options are ignored if specified.