signing

Documentation

Overview

Package signing provides interfaces to sign arbitrary small blobs with RSA-SHA256 signature (PKCS1v15) and verify such signatures.

Each service has its own private keys it uses for signing, with public certificates served over HTTPS. Other services may use the public keys to authenticate data generated by the service. It is useful, for example, for authenticating PubSub messages payload.

Index

• Constants
• func FetchLUCIServiceIdentity(ctx context.Context, serviceURL string) (identity.Identity, error)
• type Certificate
• type JSONTime
  • func (t JSONTime) MarshalJSON() ([]byte, error)
  • func (t JSONTime) Time() time.Time
  • func (t *JSONTime) UnmarshalJSON(data []byte) error
• type PublicCertificates
  • func FetchCertificates(ctx context.Context, url string) (*PublicCertificates, error)
  • func FetchCertificatesForServiceAccount(ctx context.Context, email string) (*PublicCertificates, error)
  • func FetchCertificatesFromLUCIService(ctx context.Context, serviceURL string) (*PublicCertificates, error)
  • func FetchGoogleOAuth2Certificates(ctx context.Context) (*PublicCertificates, error)
  • func (pc *PublicCertificates) CertificateForKey(key string) (*x509.Certificate, error)
  • func (pc *PublicCertificates) CheckSignature(key string, signed, signature []byte) error
• type ServiceInfo
  • func FetchServiceInfo(ctx context.Context, url string) (*ServiceInfo, error)
  • func FetchServiceInfoFromLUCIService(ctx context.Context, serviceURL string) (*ServiceInfo, error)
• type Signer

Constants

const CertsCacheExpiration = time.Hour

CertsCacheExpiration defines how long to cache fetched certificates in local memory.

Functions

func FetchLUCIServiceIdentity

func FetchLUCIServiceIdentity(ctx context.Context, serviceURL string) (identity.Identity, error)

FetchLUCIServiceIdentity returns "service:<app-id>" of a LUCI service.

It is the same thing as inf.AppID returned by FetchServiceInfoFromLUCIService except it is cached more aggressively because service ID is static (unlike some other ServiceInfo fields).

'serviceURL' is root URL of the service (e.g. 'https://example.com').

Types

type Certificate

type Certificate struct {
	// KeyName identifies the key used for signing.
	KeyName string `json:"key_name"`
	// X509CertificatePEM is PEM encoded certificate.
	X509CertificatePEM string `json:"x509_certificate_pem"`
}

Certificate is public certificate of some service. Must not be mutated once initialized.

type JSONTime

type JSONTime time.Time

JSONTime is time.Time that serializes as unix timestamp (in microseconds).

func (JSONTime) MarshalJSON

func (t JSONTime) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (JSONTime) Time

func (t JSONTime) Time() time.Time

Time casts value to time.Time.

func (*JSONTime) UnmarshalJSON

func (t *JSONTime) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type PublicCertificates

type PublicCertificates struct {
	// AppID is GAE app ID of a service that owns the keys if it is on GAE.
	AppID string `json:"app_id,omitempty"`
	// ServiceAccountName is name of a service account that owns the key, if any.
	ServiceAccountName string `json:"service_account_name,omitempty"`
	// Certificates is the list of certificates.
	Certificates []Certificate `json:"certificates"`
	// Timestamp is Unix time (microseconds) of when this list was generated.
	Timestamp JSONTime `json:"timestamp"`
	// contains filtered or unexported fields
}

PublicCertificates is a bundle of recent certificates of some service. Must not be mutated once initialized.

func FetchCertificates

func FetchCertificates(ctx context.Context, url string) (*PublicCertificates, error)

FetchCertificates fetches certificates from the given URL.

The server is expected to reply with JSON described by PublicCertificates struct (like LUCI services do). Uses the process cache to cache them for CertsCacheExpiration minutes.

LUCI services serve certificates at /auth/api/v1/server/certificates.

func FetchCertificatesForServiceAccount

func FetchCertificatesForServiceAccount(ctx context.Context, email string) (*PublicCertificates, error)

FetchCertificatesForServiceAccount fetches certificates of some Google service account.

Works only with Google service accounts (@*.gserviceaccount.com). Uses the process cache to cache them for CertsCacheExpiration minutes.

Usage (roughly):

certs, err := signing.FetchCertificatesForServiceAccount(ctx, <email>)
if certs.CheckSignature(<key id>, <blob>, <signature>) == nil {
  <signature is valid!>
}

func FetchCertificatesFromLUCIService

func FetchCertificatesFromLUCIService(ctx context.Context, serviceURL string) (*PublicCertificates, error)

FetchCertificatesFromLUCIService is shortcut for FetchCertificates that uses LUCI-specific endpoint.

'serviceURL' is root URL of the service (e.g. 'https://example.com').

func FetchGoogleOAuth2Certificates

func FetchGoogleOAuth2Certificates(ctx context.Context) (*PublicCertificates, error)

FetchGoogleOAuth2Certificates fetches root certificates of Google OAuth2 service.

They can be used to verify signatures on various JWTs issued by Google OAuth2 backends (like OpenID identity tokens and GCE signed metadata JWTs).

Uses the process cache to cache them for CertsCacheExpiration minutes.

func (*PublicCertificates) CertificateForKey

func (pc *PublicCertificates) CertificateForKey(key string) (*x509.Certificate, error)

CertificateForKey finds the certificate for given key and deserializes it.

func (*PublicCertificates) CheckSignature

func (pc *PublicCertificates) CheckSignature(key string, signed, signature []byte) error

CheckSignature returns nil if `signed` was indeed signed by given key.

type ServiceInfo

type ServiceInfo struct {
	AppID              string `json:"app_id,omitempty"`
	AppRuntime         string `json:"app_runtime,omitempty"`
	AppRuntimeVersion  string `json:"app_runtime_version,omitempty"`
	AppVersion         string `json:"app_version,omitempty"`
	ServiceAccountName string `json:"service_account_name,omitempty"`
}

ServiceInfo describes identity of some service.

It matches JSON format of /auth/api/v1/server/info endpoint.

func FetchServiceInfo

func FetchServiceInfo(ctx context.Context, url string) (*ServiceInfo, error)

FetchServiceInfo fetches information about the service from the given URL.

The server is expected to reply with JSON described by ServiceInfo struct (like LUCI services do). Uses process cache to cache the response for 1h.

LUCI services serve the service info at /auth/api/v1/server/info.

func FetchServiceInfoFromLUCIService

func FetchServiceInfoFromLUCIService(ctx context.Context, serviceURL string) (*ServiceInfo, error)

FetchServiceInfoFromLUCIService is shortcut for FetchServiceInfo that uses LUCI-specific endpoint.

'serviceURL' is root URL of the service (e.g. 'https://example.com').

type Signer

type Signer interface {
	// SignBytes signs the blob with some active private key.
	//
	// Hashes the blob using SHA256 and then calculates RSASSA-PKCS1-v1_5
	// signature using the currently active signing key.
	//
	// Returns the signature and name of the key used.
	SignBytes(ctx context.Context, blob []byte) (keyName string, signature []byte, err error)

	// Certificates returns a bundle with public certificates for all active keys.
	//
	// The certificates contains public keys that can be used to validate
	// signatures generated with SignBytes. See CheckSignature method of
	// PublicCertificates.
	//
	// Do not modify return value, it may be shared by many callers.
	Certificates(ctx context.Context) (*PublicCertificates, error)

	// ServiceInfo returns information about the current service.
	//
	// It includes app ID and the service account name (that ultimately owns the
	// signing private key).
	//
	// Do not modify return value, it may be shared by many callers.
	ServiceInfo(ctx context.Context) (*ServiceInfo, error)
}

Signer holds private key and corresponding cert and can sign blobs.

It signs using RSA-256 + PKCS1v15. It usually lives in a context, see GetSigner function.