accesscontrol

Documentation

Overview

Package accesscontrol implements an access control authorization scheme based on digital signatures.

Authorizations for specified access types are issued by an entity that digitally signs each authorization. The digital signature is verified by service providers before granting the specified access type. Each authorization includes an expiry date and a unique ID that may be used to mitigate malicious reuse/sharing of authorizations.

In a typical deployment, the signing keys will be present on issuing entities which are distinct from service providers. Only verification keys will be deployed to service providers.

An authorization is represented in JSON, which is then base64-encoded for transport:

{
  "Authorization" : {
	 "ID" : <derived unique ID>,
	 "AccessType" : <access type name; e.g., "my-access">,
	 "Expires" : <RFC3339-encoded UTC time value>
  },
  "SigningKeyID" : <unique key ID>,
  "Signature" : <Ed25519 digital signature>
}

Index

• func IssueAuthorization(signingKey *SigningKey, seedAuthorizationID []byte, expires time.Time) (string, []byte, error)
• func NewKeyPair(accessType string) (*SigningKey, *VerificationKey, error)
• func PackAuthorizations(auths []string, cborEncoding cbor.EncMode) ([]byte, error)
• func UnpackAuthorizations(packedAuthsCBOR []byte) ([]string, error)
• func ValidateSigningKey(signingKey *SigningKey) error
• func ValidateVerificationKeyRing(keyRing *VerificationKeyRing) error
• type Authorization
  • func VerifyAuthorization(keyRing *VerificationKeyRing, encodedSignedAuthorization string) (*Authorization, error)
• type SigningKey
• type VerificationKey
• type VerificationKeyRing

Functions

func IssueAuthorization

func IssueAuthorization(
	signingKey *SigningKey,
	seedAuthorizationID []byte,
	expires time.Time) (string, []byte, error)

IssueAuthorization issues an authorization signed with the specified signing key.

seedAuthorizationID should be a value that uniquely identifies the purchase, subscription, or transaction that backs the authorization; a distinct unique authorization ID will be derived from the seed without revealing the original value. The authorization ID is to be used to mitigate malicious authorization reuse/sharing.

The first return value is a base64-encoded, serialized JSON representation of the signed authorization that can be passed to VerifyAuthorization. The second return value is the unique ID of the signed authorization returned in the first value.

func NewKeyPair

func NewKeyPair(
	accessType string) (*SigningKey, *VerificationKey, error)

NewKeyPair generates a new authorization signing key pair.

func PackAuthorizations

func PackAuthorizations(
	auths []string,
	cborEncoding cbor.EncMode) ([]byte, error)

PackAuthorizations re-encodes a list of authorizations using the more compact encoding that is used in protocol.EncodePackedAPIParameters.

func UnpackAuthorizations

func UnpackAuthorizations(packedAuthsCBOR []byte) ([]string, error)

UnpackAuthorizations re-encodes a list of authorizations encoded with PackAuthorizations back to the standard, IssueAuthorization encoding.

func ValidateSigningKey

func ValidateSigningKey(signingKey *SigningKey) error

ValidateSigningKey checks that a signing key is correctly configured.

func ValidateVerificationKeyRing

func ValidateVerificationKeyRing(keyRing *VerificationKeyRing) error

ValidateVerificationKeyRing checks that a verification key ring is correctly configured.

Types

type Authorization

type Authorization struct {
	ID         []byte
	AccessType string
	Expires    time.Time
}

Authorization describes an authorization, with a unique ID, granting access to a specified access type, and expiring at the specified time.

An Authorization is embedded within a digitally signed object. This wrapping object adds a signature and a signing key ID.

func VerifyAuthorization

func VerifyAuthorization(
	keyRing *VerificationKeyRing,
	encodedSignedAuthorization string) (*Authorization, error)

VerifyAuthorization verifies the signed authorization and, when verified, returns the embedded Authorization struct with the access control information.

The key ID in the signed authorization is used to select the appropriate verification key from the key ring.

type SigningKey

type SigningKey struct {
	ID                 []byte
	AccessType         string
	AuthorizationIDKey []byte
	PrivateKey         []byte
}

SigningKey is the private key used to sign newly issued authorizations for the specified access type. The key ID is included in authorizations and identifies the corresponding verification keys.

AuthorizationIDKey is used to produce a unique authentication ID that cannot be mapped back to its seed value.

type VerificationKey

type VerificationKey struct {
	ID         []byte
	AccessType string
	PublicKey  []byte
}

VerificationKey is the public key used to verify signed authentications issued for the specified access type. The authorization references the expected public key by ID.

type VerificationKeyRing

type VerificationKeyRing struct {
	Keys []*VerificationKey
}

VerificationKeyRing is a set of verification keys to be deployed to a service provider for verifying access authorizations.