Back to godoc.org

Package signing

v0.0.0-...-b04b005
Latest Go to latest

The latest major version is .

Published: Aug 6, 2020 | License: Apache-2.0 | Module: go.chromium.org/luci

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

const CertsCacheExpiration = time.Hour

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

func FetchLUCIServiceIdentity

func FetchLUCIServiceIdentity(c 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').

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(c 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(c 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(c 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(c 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(c 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(c 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(c 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(c 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(c 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.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier