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

    View Source
    const CertsCacheExpiration = time.Hour

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

      Variables

      This section is empty.

      Functions

      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').

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

                                        Directories

                                        Path Synopsis
                                        Package signingtest implements signing.Signer interface using small random keys.
                                        Package signingtest implements signing.Signer interface using small random keys.