luci: Index | Files

package tokensigning

import ""

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


Package Files

common.go inspector.go signer.go

type CertificatesSupplier Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Lifespan is a time interval when some token is valid.

type Signer Uses

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 Uses

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 Uses

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.

Package tokensigning imports 10 packages (graph) and is imported by 6 packages. Updated 2021-01-24. Refresh now. Tools for package owners.