machinetoken

Documentation

Overview

Package machinetoken implements generation of LUCI machine tokens.

Index

• func InspectToken(c context.Context, certs tokensigning.CertificatesSupplier, tok string) (*tokensigning.Inspection, error)
• func Mint(c context.Context, params *MintParams) (*tokenserver.MachineTokenBody, string, error)
• func SignToken(c context.Context, signer signing.Signer, body *tokenserver.MachineTokenBody) (string, error)
• type InspectMachineTokenRPC
  • func (r *InspectMachineTokenRPC) InspectMachineToken(c context.Context, req *admin.InspectMachineTokenRequest) (*admin.InspectMachineTokenResponse, error)
• type MintMachineTokenRPC
  • func (r *MintMachineTokenRPC) MintMachineToken(c context.Context, req *minter.MintMachineTokenRequest) (*minter.MintMachineTokenResponse, error)
• type MintParams
  • func (p *MintParams) MachineFQDN() (string, error)
  • func (p *MintParams) Validate() error
• type MintedTokenInfo
• type TokenLogger
  • func NewTokenLogger(dryRun bool) TokenLogger

Functions

func InspectToken

func InspectToken(c context.Context, certs tokensigning.CertificatesSupplier, tok string) (*tokensigning.Inspection, error)

InspectToken returns information about the machine token.

Inspection.Envelope is either nil or *tokenserver.MachineTokenEnvelope. Inspection.Body is either nil or *tokenserver.MachineTokenBody.

func Mint

func Mint(c context.Context, params *MintParams) (*tokenserver.MachineTokenBody, string, error)

Mint generates a new machine token proto, signs and serializes it.

Returns its body as a proto, and as a signed base64-encoded final token.

func SignToken

func SignToken(c context.Context, signer signing.Signer, body *tokenserver.MachineTokenBody) (string, error)

SignToken signs and serializes the machine subtoken.

It doesn't do any validation. Assumes the prepared subtoken is valid.

Produces base64-encoded token or a transient error.

Types

type InspectMachineTokenRPC

type InspectMachineTokenRPC struct {
	// Signer is mocked in tests.
	//
	// In prod it is the default server signer that uses server's service account.
	Signer signing.Signer
}

InspectMachineTokenRPC implements Admin.InspectMachineToken API method.

It assumes authorization has happened already.

func (*InspectMachineTokenRPC) InspectMachineToken

func (r *InspectMachineTokenRPC) InspectMachineToken(c context.Context, req *admin.InspectMachineTokenRequest) (*admin.InspectMachineTokenResponse, error)

InspectMachineToken decodes a machine token and verifies it is valid.

type MintMachineTokenRPC

type MintMachineTokenRPC struct {
	// Signer is mocked in tests.
	//
	// In prod it is the default server signer that uses server's service account.
	Signer signing.Signer

	// CheckCertificate is mocked in tests.
	//
	// In prod it is certchecker.CheckCertificate.
	CheckCertificate func(c context.Context, cert *x509.Certificate) (*certconfig.CA, error)

	// LogToken is mocked in tests.
	//
	// In prod it is produced by NewTokenLogger.
	LogToken TokenLogger
}

MintMachineTokenRPC implements TokenMinter.MintMachineToken RPC method.

func (*MintMachineTokenRPC) MintMachineToken

func (r *MintMachineTokenRPC) MintMachineToken(c context.Context, req *minter.MintMachineTokenRequest) (*minter.MintMachineTokenResponse, error)

MintMachineToken generates a new token for an authenticated machine.

type MintParams

type MintParams struct {
	// Cert is the certificate used when authenticating the token requester.
	//
	// It's serial number will be put in the token.
	Cert *x509.Certificate

	// Config is a chunk of configuration related to the machine domain.
	//
	// It describes parameters for the token. Fetched from luci-config as part of
	// CA configuration.
	Config *admin.CertificateAuthorityConfig

	// Signer produces RSA-SHA256 signatures using a token server key.
	//
	// Usually it is using SignBytes GAE API.
	Signer signing.Signer
}

MintParams is passed to Mint.

The name of the machine (to put into the machine token) is extracted from the certificate.

func (*MintParams) MachineFQDN

func (p *MintParams) MachineFQDN() (string, error)

MachineFQDN extracts the machine's FQDN from the certificate.

It uses either Common Name or X509v3 Subject Alternative Name DNS field (depending on the presence of the later). If SAN DNS field is present, it will be used, should it be consistent with the Common Name.

The extracted FQDN is convert to lower case.

Returns an error if CN field is empty.

func (*MintParams) Validate

func (p *MintParams) Validate() error

Validate checks that token minting parameters are allowed.

type MintedTokenInfo

type MintedTokenInfo struct {
	Request   *minter.MachineTokenRequest   // the token request, as presented by the client
	Response  *minter.MachineTokenResponse  // the response, as returned by the minter
	TokenBody *tokenserver.MachineTokenBody // deserialized token (same as in Response)
	CA        *certconfig.CA                // CA configuration used to authorize this request
	PeerIP    net.IP                        // caller IP address
	RequestID string                        // GAE request ID that handled the RPC
}

MintedTokenInfo is passed to LogToken.

It carries all information about the token minting operation and the produced token.

type TokenLogger

type TokenLogger func(context.Context, *MintedTokenInfo) error

TokenLogger records info about the token to BigQuery.

func NewTokenLogger

func NewTokenLogger(dryRun bool) TokenLogger

NewTokenLogger returns a callback that records info about tokens to BigQuery.

Tokens themselves are not logged. Only first 16 bytes of their SHA256 hashes (aka 'fingerprint') are. They are used only to identify tokens in logs.

When dryRun is true, logs to the local text log only, not to BigQuery (to avoid accidentally pushing fake data to real BigQuery dataset).