Skip to content
DNSid Docs

Go: package awskms

Generated from the Go source by scripts/gen-docs.sh — do not edit; run it to regenerate. Canonical deep reference: pkg.go.dev/github.com/dnsid-ai/dnsid-go/key/aws. Guides and account setup: https://docs.dnsid.ai.

import "github.com/dnsid-ai/dnsid-go/key/aws"

Package awskms implements the DNSid [dnsid.KeyProvider] interface on top of AWS KMS. An agent’s operational keys are created, stored, and used for signing inside KMS, so private key material never leaves the service; the provider fetches only public keys, exposes them as JWKs, and manages the pending, active, and retained key lifecycle that DNSid key rotation uses.

The main entry points are Load (and its alias New), which constructs a Provider from a Client and a Config, and SDKClient, which adapts a *kms.Client from the AWS SDK for Go v2 to the Client interface:

client := awskms.SDKClient{Client: kms.NewFromConfig(awsCfg)}
provider, err := awskms.Load(ctx, client, awskms.Config{
  State:     awskms.State{ActiveKeyID: activeKeyARN},
  Algorithm: types.SigningAlgorithmSpecEcdsaSha256, // JOSE ES256; the default
})
if err != nil {
  // handle error
}
sig, err := provider.Sign(payload)

A Provider signs with a single configured algorithm. Two KMS signing algorithms are supported: ECDSA_SHA_256 with an ECC_NIST_P256 key (JOSE ES256) and ED25519_SHA_512 with an ECC_NIST_EDWARDS25519 key (JOSE EdDSA). Rotation state is held in memory; persist it across restarts with Provider.State and restore it through Config.State.

See https://docs.dnsid.ai for DNSid guides and account setup.

Index

Section titled “Index”

type Client

Section titled “type Client”

Client is the narrow AWS KMS surface a Provider depends on. SDKClient adapts the AWS SDK for Go v2 KMS client; test doubles can implement Client directly.

type Client interface {
    // CreateSigningKey creates a new SIGN_VERIFY KMS key and returns its ID.
    CreateSigningKey(context.Context, CreateSigningKeyInput) (CreateSigningKeyOutput, error)


    // GetPublicKey returns the public half and metadata of a KMS key.
    GetPublicKey(context.Context, GetPublicKeyInput) (GetPublicKeyOutput, error)


    // Sign signs a raw message or precomputed digest with a KMS key.
    Sign(context.Context, SignInput) (SignOutput, error)


    // ScheduleKeyDeletion schedules a KMS key for deletion.
    ScheduleKeyDeletion(context.Context, ScheduleKeyDeletionInput) error
}

type Config

Section titled “type Config”

Config configures a Provider. The zero value is not usable on its own: State.ActiveKeyID must identify an existing KMS signing key. Load applies the defaults documented on each field.

type Config struct {
    // State is the initial rotation state. State.ActiveKeyID is required.
    State State


    // Algorithm is the KMS signing algorithm used for every signing
    // operation. Supported values are
    // types.SigningAlgorithmSpecEcdsaSha256 (JOSE ES256) and
    // types.SigningAlgorithmSpecEd25519Sha512 (JOSE EdDSA). Defaults to
    // ECDSA_SHA_256.
    Algorithm types.SigningAlgorithmSpec


    // KeySpec is the KMS key spec required of every key the provider uses
    // or creates. If empty it is derived from Algorithm (ECC_NIST_P256 for
    // ECDSA_SHA_256, ECC_NIST_EDWARDS25519 for ED25519_SHA_512); a
    // non-empty value that does not match Algorithm is rejected by Load.
    KeySpec types.KeySpec


    // Description is applied to KMS keys created by GenerateKey.
    Description string


    // Tags are applied to KMS keys created by GenerateKey.
    Tags map[string]string


    // ScheduleDeletionOnPurge schedules KMS key deletion when a key is
    // purged or superseded, and when a key created by GenerateKey fails
    // validation. When false, removed keys are only dropped from the
    // provider's state and remain in KMS.
    ScheduleDeletionOnPurge bool


    // DeletionWindowInDays is the KMS pending-deletion window used when
    // scheduling key deletion. Defaults to 30.
    DeletionWindowInDays int32


    // OperationTimeout bounds each KMS call. Defaults to 30 seconds; a
    // negative value disables the timeout.
    OperationTimeout time.Duration
}

type CreateSigningKeyInput

Section titled “type CreateSigningKeyInput”

CreateSigningKeyInput carries the parameters for Client.CreateSigningKey: the KMS key spec plus the description and tags to apply to the new key.

type CreateSigningKeyInput struct {
    KeySpec     types.KeySpec
    Description string
    Tags        map[string]string
}

type CreateSigningKeyOutput

Section titled “type CreateSigningKeyOutput”

CreateSigningKeyOutput reports the ID — preferably the ARN — of a newly created KMS key.

type CreateSigningKeyOutput struct{ KeyID string }

type GetPublicKeyInput

Section titled “type GetPublicKeyInput”

GetPublicKeyInput identifies the KMS key to fetch with Client.GetPublicKey.

type GetPublicKeyInput struct{ KeyID string }

type GetPublicKeyOutput

Section titled “type GetPublicKeyOutput”

GetPublicKeyOutput carries a KMS key’s DER-encoded (PKIX) public key and the metadata the provider validates: the canonical key ID, key spec, key usage, and supported signing algorithms.

type GetPublicKeyOutput struct {
    KeyID             string
    PublicKey         []byte
    KeySpec           types.KeySpec
    KeyUsage          types.KeyUsageType
    SigningAlgorithms []types.SigningAlgorithmSpec
}

type Provider

Section titled “type Provider”

Provider is an AWS KMS-backed implementation of [dnsid.KeyProvider]. Private key material stays in KMS: the provider fetches and caches public keys as JWKs and delegates every signing operation to the KMS Sign API.

Key IDs (kids) are the canonical identifiers reported by KMS — normally key ARNs. Any KMS key identifier is accepted where a kid parameter allows it, but State, Provider.ListKeyIds, and [dnsid.KeySignature] always carry the canonical form. Rotation state is held in memory only; persist it with Provider.State. Provider is safe for concurrent use.

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

func Load

Section titled “func Load”
func Load(ctx context.Context, client Client, cfg Config) (*Provider, error)

Load constructs a Provider from an existing rotation state. It applies the defaults documented on Config, then canonicalizes every key ID in cfg.State against KMS, verifying that each key exists, is a SIGN_VERIFY key of the configured key spec, and supports the configured signing algorithm. It returns an error if client is nil, cfg.State.ActiveKeyID is empty, the algorithm is unsupported, cfg.KeySpec does not match the algorithm, or any state key fails validation.

func New

Section titled “func New”
func New(ctx context.Context, client Client, cfg Config) (*Provider, error)

New constructs a Provider. It is equivalent to Load.

func (*Provider) Activate

Section titled “func (*Provider) Activate”
func (p *Provider) Activate(kid string) error

Activate promotes a pending key to active and moves the previously active key to the retained list, implementing [dnsid.KeyProvider]. The kid may be any KMS identifier for the key; it returns an error if it does not resolve to a pending key.

func (*Provider) GenerateKey

Section titled “func (*Provider) GenerateKey”
func (p *Provider) GenerateKey(alg dnsid.JoseAlg) (string, error)

GenerateKey creates a new KMS signing key and records it as pending, implementing [dnsid.KeyProvider]. alg must match the JOSE algorithm the provider is configured for (ES256 for ECDSA_SHA_256, EdDSA for ED25519_SHA_512). On success it returns the canonical kid of the new key. If the new key fails post-creation validation, the KMS key ID is returned alongside the error and, when Config.ScheduleDeletionOnPurge is set, deletion of the orphaned key is scheduled.

func (*Provider) JWK

Section titled “func (*Provider) JWK”
func (p *Provider) JWK(kidOpt ...string) jwk.Key

JWK returns one public JWK, implementing [dnsid.KeyProvider]. With no kid it returns the active key. It returns nil when the kid is not the active key or among the retained or pending keys, and also when fetching the public key from KMS fails; use Provider.JWKWithError to distinguish the two. The returned key is a clone, so mutating it does not affect the provider.

func (*Provider) JWKWithError

Section titled “func (*Provider) JWKWithError”
func (p *Provider) JWKWithError(kidOpt ...string) (jwk.Key, error)

JWKWithError is like Provider.JWK but reports fetch failures. It returns (nil, nil) when the kid is not known to the provider, and (nil, err) when the key could not be fetched from KMS or failed validation. Fetched public keys are cached for the life of the provider.

func (*Provider) ListKeyIds

Section titled “func (*Provider) ListKeyIds”
func (p *Provider) ListKeyIds() []string

ListKeyIds returns the active kid first, followed by retained kids, implementing [dnsid.KeyProvider]. Pending kids are not listed.

func (*Provider) Purge

Section titled “func (*Provider) Purge”
func (p *Provider) Purge(kid string) error

Purge removes a pending or retained key, implementing [dnsid.KeyProvider]. The kid must be the canonical form reported by Provider.State; the active key cannot be purged. When Config.ScheduleDeletionOnPurge is set, the underlying KMS key is scheduled for deletion after Config.DeletionWindowInDays days; if scheduling fails, the key is restored to its previous list and the error is returned.

func (*Provider) Sign

Section titled “func (*Provider) Sign”
func (p *Provider) Sign(payload []byte) (*dnsid.KeySignature, error)

Sign signs payload with the active key using the configured algorithm, implementing [dnsid.KeyProvider]. Payloads up to 4096 bytes are sent to KMS as RAW messages; larger payloads are hashed locally with SHA-256 and sent as a DIGEST, which is only possible for ECDSA_SHA_256 — larger Ed25519 payloads return an error. ECDSA signatures are converted from KMS’s ASN.1 DER encoding to the raw R||S form JOSE requires, so the returned KeySignature is always JOSE-ready.

func (*Provider) SignKey

Section titled “func (*Provider) SignKey”
func (p *Provider) SignKey(kid string, payload []byte) (*dnsid.KeySignature, error)

SignKey signs payload with a specific key, implementing [dnsid.KeyProvider]. The kid may be any KMS identifier for the key; it must resolve to the active key or a pending key. Signing with a retained key returns an argument error, and signature encoding follows the rules documented on Provider.Sign.

func (*Provider) State

Section titled “func (*Provider) State”
func (p *Provider) State() State

State returns a copy of the provider’s current rotation state, with all key IDs in canonical (KMS-reported) form. Persist it and supply it back through Config.State to reconstruct the provider later.

func (*Provider) Supersede

Section titled “func (*Provider) Supersede”
func (p *Provider) Supersede(kid string) error

Supersede removes a retained key after a completed rotation, implementing [dnsid.KeyProvider]. The kid must be the canonical form reported by Provider.State or Provider.ListKeyIds; if it does not name a retained key, Supersede returns an argument error. Removal follows the rules documented on Provider.Purge.

type SDKClient

Section titled “type SDKClient”

SDKClient adapts an AWS SDK for Go v2 *kms.Client to the Client interface.

type SDKClient struct{ Client *kms.Client }

func (SDKClient) CreateSigningKey

Section titled “func (SDKClient) CreateSigningKey”
func (c SDKClient) CreateSigningKey(ctx context.Context, in CreateSigningKeyInput) (CreateSigningKeyOutput, error)

CreateSigningKey creates a SIGN_VERIFY KMS key with the requested key spec, description, and tags. It returns the new key’s ARN when KMS reports one, and the bare key ID otherwise.

func (SDKClient) GetPublicKey

Section titled “func (SDKClient) GetPublicKey”
func (c SDKClient) GetPublicKey(ctx context.Context, in GetPublicKeyInput) (GetPublicKeyOutput, error)

GetPublicKey fetches the public key and metadata of the KMS key named by in.KeyID.

func (SDKClient) ScheduleKeyDeletion

Section titled “func (SDKClient) ScheduleKeyDeletion”
func (c SDKClient) ScheduleKeyDeletion(ctx context.Context, in ScheduleKeyDeletionInput) error

ScheduleKeyDeletion schedules the KMS key named by in.KeyID for deletion after in.PendingWindowInDays days.

func (SDKClient) Sign

Section titled “func (SDKClient) Sign”
func (c SDKClient) Sign(ctx context.Context, in SignInput) (SignOutput, error)

Sign asks KMS to sign in.Message with in.KeyID, sending it as a RAW message or, when in.Digest is true, as a precomputed DIGEST.

type ScheduleKeyDeletionInput

Section titled “type ScheduleKeyDeletionInput”

ScheduleKeyDeletionInput carries the parameters for Client.ScheduleKeyDeletion: the key to delete and the KMS pending-deletion window in days.

type ScheduleKeyDeletionInput struct {
    KeyID               string
    PendingWindowInDays int32
}

type SignInput

Section titled “type SignInput”

SignInput carries the parameters for Client.Sign. When Digest is true, Message is a precomputed digest rather than the raw payload.

type SignInput struct {
    KeyID     string
    Message   []byte
    Algorithm types.SigningAlgorithmSpec
    Digest    bool
}

type SignOutput

Section titled “type SignOutput”

SignOutput carries a KMS signature together with the key ID and signing algorithm KMS reports having used.

type SignOutput struct {
    KeyID     string
    Signature []byte
    Algorithm types.SigningAlgorithmSpec
}

type State

Section titled “type State”

State records the key rotation state of a Provider: which KMS key is active, which retained keys remain published for verification, and which pending keys await activation. The provider does not persist state itself; capture it with Provider.State and supply it back through Config.State when reconstructing the provider.

type State struct {
    // ActiveKeyID identifies the KMS key used by Sign. Required.
    ActiveKeyID string


    // RetainedKeyIDs identify previously active keys that are still
    // published for verification.
    RetainedKeyIDs []string


    // PendingKeyIDs identify generated keys that have not been activated.
    PendingKeyIDs []string
}

Generated by gomarkdoc

Known Systems AI, Inc. is an affiliate of Identity Digital that solves identity fragmentation for the AI agent economy. As agents become more autonomous and interoperable, they introduce risk and security challenges existing systems weren't designed for—starting with a consistent way to verify ownership across organizational boundaries. Known Systems AI, Inc. combines Identity Digital's DNS expertise with an Immutable Log to establish a global coordination layer for AI agent identity, and participates in open standards communities, including the Linux Foundation. For more information, visit DNSid.ai.