Documentation

Overview

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

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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.