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(c context.Context, serviceURL string) (identity.Identity, error)
- type Certificate
- type JSONTime
- type PublicCertificates
- func FetchCertificates(c context.Context, url string) (*PublicCertificates, error)
- func FetchCertificatesForServiceAccount(c context.Context, email string) (*PublicCertificates, error)
- func FetchCertificatesFromLUCIService(c context.Context, serviceURL string) (*PublicCertificates, error)
- func FetchGoogleOAuth2Certificates(c context.Context) (*PublicCertificates, error)
- type ServiceInfo
- type Signer
Constants ¶
const CertsCacheExpiration = time.Hour
CertsCacheExpiration defines how long to cache fetched certificates in local memory.
Variables ¶
This section is empty.
Functions ¶
func FetchLUCIServiceIdentity ¶
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 ¶
JSONTime is time.Time that serializes as unix timestamp (in microseconds).
func (JSONTime) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (*JSONTime) UnmarshalJSON ¶
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package signingtest implements signing.Signer interface using small random keys.
|
Package signingtest implements signing.Signer interface using small random keys. |