machinetoken

Documentation

Overview

Package machinetoken implements generation of LUCI machine tokens.

Index

• func FlushTokenLog(c context.Context) error
• func InspectToken(c context.Context, certs tokensigning.CertificatesSupplier, tok string) (*tokensigning.Inspection, error)
• func LogToken(c context.Context, i *MintedTokenInfo) 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

Functions

func FlushTokenLog

func FlushTokenLog(c context.Context) error

FlushTokenLog sends all buffered logged tokens to BigQuery.

It is fine to call FlushTokenLog concurrently from multiple request handlers, if necessary (it will effectively parallelize the flush).

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 LogToken

func LogToken(c context.Context, i *MintedTokenInfo) error

LogToken records information about the token in the BigQuery.

The signed token itself is not logged. Only first 16 bytes of its SHA256 hash (aka 'fingerprint') is. It is used only to identify this particular token in logs.

On dev server, logs to the GAE log only, not to BigQuery (to avoid accidentally pushing fake data to real BigQuery dataset).

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 gaesigner.Signer.
	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 gaesigner.Signer.
	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 LogToken from bigquery_logger.go.
	LogToken func(c context.Context, info *MintedTokenInfo) error
}

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 should be singular, it should contain machine's FQDN, and Common Name should match the hostname part of the FQDN.

The extracted FQDN is convert to lower case.

Returns an error if values of CN and SAN DNS fields are not consistent.

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.