tokensigning

Documentation

Overview

Package tokensigning implements utilities for RSA-signing of proto messages.

Index

• type CertificatesSupplier
• type Inspection
• type Inspector
  • func (i *Inspector) InspectToken(c context.Context, tok string) (*Inspection, error)
• type Lifespan
• type Signer
  • func (s *Signer) SignToken(c context.Context, body proto.Message) (string, error)
• type Unwrapped

Types

type CertificatesSupplier

type CertificatesSupplier interface {
	// Certificates returns certs bundle used to validate the token signature.
	Certificates(c context.Context) (*signing.PublicCertificates, error)
}

CertificatesSupplier produces signing.PublicCertificates.

type Inspection

type Inspection struct {
	Signed           bool          // true if the token is structurally valid and signed
	NonExpired       bool          // true if the token hasn't expire yet (may be bogus for unsigned tokens)
	InvalidityReason string        // human readable reason why the token is invalid or "" if it is valid
	Envelope         proto.Message // deserialized token envelope
	Body             proto.Message // deserialized token body
}

Inspection is the result of token inspection.

type Inspector

type Inspector struct {
	// Certificates returns certs bundle used to validate the token signature.
	Certificates CertificatesSupplier

	// Encoding is base64 encoding to used for token (or RawURLEncoding if nil).
	Encoding *base64.Encoding

	// SigningContext is prepended to the token blob before signature check.
	//
	// See SigningContext in Signer struct for more info.
	SigningContext string

	// Envelope returns an empty message of same type as produced by signer.Wrap.
	Envelope func() proto.Message

	// Body returns an empty messages corresponding to the token body type.
	Body func() proto.Message

	// Unwrap extracts information from envelope proto message.
	//
	// It must set Body, RsaSHA256Sig and KeyID fields.
	Unwrap func(e proto.Message) Unwrapped

	// Lifespan extracts a lifespan from the deserialized body of the token.
	Lifespan func(e proto.Message) Lifespan
}

Inspector knows how to inspect tokens produced by Signer.

It is used by Inspect<something>Token RPCs (available only to admins). It tries to return as much information as possible. In particular, it tries to deserialize the token body even if the signature is no longer valid. This is useful when debugging broken tokens.

Since it is available only to admins, we assume the possibility of abuse is small.

func (*Inspector) InspectToken

func (i *Inspector) InspectToken(c context.Context, tok string) (*Inspection, error)

InspectToken extracts as much information as possible from the token.

Returns errors only if the inspection operation itself fails (i.e we can't determine whether the token valid or not). If the given token is invalid, returns Inspection object with details and nil error.

type Lifespan

type Lifespan struct {
	NotBefore time.Time
	NotAfter  time.Time
}

Lifespan is a time interval when some token is valid.

type Signer

type Signer struct {
	// Signer is the actual signer: it knows how to sign blobs.
	Signer signing.Signer

	// SigningContext is prepended to the token blob before it is signed.
	//
	// It exists to avoid cross-protocol attacks, when same key is used to sign
	// different kinds of tokens. An attacker may get a token of kind A, and use
	// it in place of a token of kind B. This may produce unexpected (possibly
	// bad) results, especially for proto-serialized tokens (that all use small
	// integers for message tags).
	//
	// By using different SigningContext strings per token kind we ensure tokens
	// are recognized as correctly signed only when they are used in an
	// appropriate context.
	//
	// SigningContext should be some arbitrary constant string that designates the
	// usage of the token. We actually prepend SigningContext + '\x00' to the
	// token blob.
	//
	// If SigningContext is "", this mechanism is completely skipped.
	SigningContext string

	// Encoding is base64 encoding to use (or RawURLEncoding if nil).
	Encoding *base64.Encoding

	// Wrap takes a blob with token body, the signature and signing key details
	// and returns a proto to serialize/encode and return as the final signed
	// token.
	Wrap func(unwrapped *Unwrapped) proto.Message
}

Signer knows how to sign protos and serialize/encode signed result.

func (*Signer) SignToken

func (s *Signer) SignToken(c context.Context, body proto.Message) (string, error)

SignToken serializes the body, signs it and returns serialized envelope.

Produces base64 URL-safe token or an error (possibly transient).

type Unwrapped

type Unwrapped struct {
	Body         []byte // serialized proto that was signed
	RsaSHA256Sig []byte // the actual signature
	SignerID     string // service account email that owns the signing key
	KeyID        string // identifier of the signing key
}

Unwrapped carries a serialized token proto and its signature.

It is then converted into some concrete proto, serialized, base64-encoded and returned to the clients.

'Wrap' may use Body, RsaSHA256Sig, SignerID and KeyID fields. 'Unwrap' must initialize Body, RsaSHA256Sig, KeyID.