luci: go.chromium.org/luci/server/auth/signing Index | Files | Directories

package signing

import "go.chromium.org/luci/server/auth/signing"

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

Package Files

certs.go doc.go info.go signer.go

Constants

const CertsCacheExpiration = 15 * time.Minute

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

func FetchLUCIServiceIdentity Uses

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 Uses

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 Uses

type JSONTime time.Time

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

func (JSONTime) MarshalJSON Uses

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

MarshalJSON implements json.Marshaler.

func (JSONTime) Time Uses

func (t JSONTime) Time() time.Time

Time casts value to time.Time.

func (*JSONTime) UnmarshalJSON Uses

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

UnmarshalJSON implements json.Unmarshaler.

type PublicCertificates Uses

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.
    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 Uses

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 process cache to cache them for CertsCacheExpiration minutes.

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

func FetchCertificatesForServiceAccount Uses

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 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 Uses

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 (*PublicCertificates) CertificateForKey Uses

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

CertificateForKey finds the certificate for given key and deserializes it.

func (*PublicCertificates) CheckSignature Uses

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

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

type ServiceInfo Uses

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 Uses

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 Uses

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 Uses

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.

Directories

PathSynopsis
signingtestPackage signingtest implements signing.Signer interface using fake keys.

Package signing imports 13 packages (graph) and is imported by 29 packages. Updated 2018-08-19. Refresh now. Tools for package owners.