minter

type ErrorCode int32

type LuciMachineToken struct {
	MachineToken string                     `protobuf:"bytes,1,opt,name=machine_token,json=machineToken" json:"machine_token,omitempty"`
	Expiry       *google_protobuf.Timestamp `protobuf:"bytes,2,opt,name=expiry" json:"expiry,omitempty"`
}

type MachineTokenRequest struct {
	// The certificate that identifies a caller (as ASN1-serialized blob).
	//
	// It will be used to extract machine FQDN (it's CN of the cert) and CA name
	// to use to check the cert.
	Certificate []byte `protobuf:"bytes,1,opt,name=certificate,proto3" json:"certificate,omitempty"`
	// The signature algorithm used to sign this request.
	//
	// Defines what's in MintMachineTokenRequest.signature field.
	SignatureAlgorithm SignatureAlgorithm `` /* 152-byte string literal not displayed */
	// Timestamp when this request was created, by the issuer clock.
	IssuedAt *google_protobuf.Timestamp `protobuf:"bytes,3,opt,name=issued_at,json=issuedAt" json:"issued_at,omitempty"`
	// The token type being requested.
	//
	// Defines what fields of the response are set.
	TokenType tokenserver.MachineTokenType `protobuf:"varint,4,opt,name=token_type,json=tokenType,enum=tokenserver.MachineTokenType" json:"token_type,omitempty"`
}

type MachineTokenResponse struct {
	// Identifier of the service and its version that produced the token.
	//
	// Has the form "<app-id>/<module-version>". Reported to the monitoring by
	// the client. This is _not_ a part of the token.
	ServiceVersion string `protobuf:"bytes,2,opt,name=service_version,json=serviceVersion" json:"service_version,omitempty"`
	// The generated token.
	//
	// The exact field set here depends on a requested type of the token, see
	// MachineTokenRequest.token_type.
	//
	// Types that are valid to be assigned to TokenType:
	//	*MachineTokenResponse_LuciMachineToken
	TokenType isMachineTokenResponse_TokenType `protobuf_oneof:"token_type"`
}

type MachineTokenResponse_LuciMachineToken struct {
	LuciMachineToken *LuciMachineToken `protobuf:"bytes,21,opt,name=luci_machine_token,json=luciMachineToken,oneof"`
}

type MintDelegationTokenRequest struct {
	// Identity whose authority is delegated.
	//
	// A string of the form "user:<email>" or a special token "REQUESTOR" that
	// means to delegate caller's own identity. The token server will check its
	// ACLs to make sure the caller is authorized to impersonate this identity.
	//
	// Required.
	DelegatedIdentity string `protobuf:"bytes,1,opt,name=delegated_identity,json=delegatedIdentity" json:"delegated_identity,omitempty"`
	// How long the token should be considered valid (in seconds).
	//
	// Default is 3600 sec.
	ValidityDuration int64 `protobuf:"varint,2,opt,name=validity_duration,json=validityDuration" json:"validity_duration,omitempty"`
	// Who will be able to use the new token.
	//
	// Each item can be an identity string (e.g. "user:<email>"), a "group:<name>"
	// string, special "*" string which means "Any bearer can use the token", or
	// "REQUESTOR" string which means "Whoever is making this call can use the
	// token".
	//
	// This is semantically is a set, the order of elements doesn't matter.
	//
	// Required.
	Audience []string `protobuf:"bytes,3,rep,name=audience" json:"audience,omitempty"`
	// What services should accept the new token.
	//
	// List of LUCI services (specified as service identities, e.g.
	// "service:app-id" or as https:// root URLs e.g. "https://<host>") that
	// should accept this token. May also contain special "*" string, which
	// means "All LUCI services".
	//
	// This is semantically is a set, the order of elements doesn't matter.
	//
	// Required.
	Services []string `protobuf:"bytes,4,rep,name=services" json:"services,omitempty"`
	// Optional reason why the token is created.
	//
	// Used only for logging and auditing purposes. Doesn't become part of the
	// token.
	Intent string `protobuf:"bytes,5,opt,name=intent" json:"intent,omitempty"`
}

type MintDelegationTokenResponse struct {
	// The actual base64-encoded signed token.
	Token string `protobuf:"bytes,1,opt,name=token" json:"token,omitempty"`
	// Same data as in 'token' in deserialized form, just for convenience.
	//
	// Mostly for JSON encoding users, since they may not understand proto-encoded
	// tokens.
	DelegationSubtoken *messages.Subtoken `protobuf:"bytes,2,opt,name=delegation_subtoken,json=delegationSubtoken" json:"delegation_subtoken,omitempty"`
	// Identifier of the service and its version that produced the token.
	//
	// Has the form "<app-id>/<module-version>". This is _not_ part of the token.
	// Used only for logging and monitoring.
	ServiceVersion string `protobuf:"bytes,3,opt,name=service_version,json=serviceVersion" json:"service_version,omitempty"`
}

type MintMachineTokenRequest struct {
	// The protobuf-serialized MachineTokenRequest message, signed by the private
	// key that matches MachineTokenRequest.certificate.
	//
	// We have to send it as a byte blob to avoid dealing with possible protobuf
	// serialization inconsistencies when checking the signature.
	SerializedTokenRequest []byte `` /* 129-byte string literal not displayed */
	// The signature of 'serialized_token_parameters' blob.
	//
	// See MachineTokenRequest.signature_algorithm for exact meaning.
	Signature []byte `protobuf:"bytes,2,opt,name=signature,proto3" json:"signature,omitempty"`
}

type MintMachineTokenResponse struct {
	// Possible kinds of fatal errors.
	//
	// Non fatal errors are returned as grpc.Internal errors instead.
	ErrorCode ErrorCode `protobuf:"varint,1,opt,name=error_code,json=errorCode,enum=tokenserver.minter.ErrorCode" json:"error_code,omitempty"`
	// Optional detailed error message.
	ErrorMessage string `protobuf:"bytes,2,opt,name=error_message,json=errorMessage" json:"error_message,omitempty"`
	// On success (SUCCESS error code) contains the produced token.
	TokenResponse *MachineTokenResponse `protobuf:"bytes,3,opt,name=token_response,json=tokenResponse" json:"token_response,omitempty"`
	// Identifier of the service and its version that produced the response.
	//
	// Set for both successful responses and errors. On success, it is identical
	// to token_response.service_version.
	ServiceVersion string `protobuf:"bytes,4,opt,name=service_version,json=serviceVersion" json:"service_version,omitempty"`
}

type MintOAuthTokenGrantRequest struct {
	// Service account identity the end user wants to act as.
	//
	// A string of the form "user:<email>".
	//
	// Required.
	ServiceAccount string `protobuf:"bytes,1,opt,name=service_account,json=serviceAccount" json:"service_account,omitempty"`
	// How long the generated grant should be considered valid (in seconds).
	//
	// Default is 3600 sec.
	ValidityDuration int64 `protobuf:"varint,2,opt,name=validity_duration,json=validityDuration" json:"validity_duration,omitempty"`
	// An end user that wants to act as the service account (perhaps indirectly).
	//
	// A string of the form "user:<email>". On Swarming, this is an identity of
	// a user that posted the task.
	//
	// TODO(vadimsh): Verify that this user is present during MintOAuthTokenGrant
	// RPC by requiring the end user's credentials, e.g make Swarming forward
	// user's OAuth token to the token server, where it can be validated.
	//
	// Required.
	EndUser string `protobuf:"bytes,3,opt,name=end_user,json=endUser" json:"end_user,omitempty"`
	// Optional reason why the grant is created.
	//
	// Used only for logging and auditing purposes. Doesn't become part of the
	// grant.
	Intent string `protobuf:"bytes,4,opt,name=intent" json:"intent,omitempty"`
}

type MintOAuthTokenGrantResponse struct {
	GrantToken string                     `protobuf:"bytes,1,opt,name=grant_token,json=grantToken" json:"grant_token,omitempty"`
	Expiry     *google_protobuf.Timestamp `protobuf:"bytes,2,opt,name=expiry" json:"expiry,omitempty"`
	// Identifier of the service and its version that produced the token.
	//
	// Has the form "<app-id>/<module-version>". This is _not_ part of the token.
	// Used only for logging and monitoring.
	ServiceVersion string `protobuf:"bytes,3,opt,name=service_version,json=serviceVersion" json:"service_version,omitempty"`
}

type MintOAuthTokenViaGrantRequest struct {
	// A previously generated grant, as returned by MintOAuthTokenGrant.
	GrantToken string `protobuf:"bytes,1,opt,name=grant_token,json=grantToken" json:"grant_token,omitempty"`
	// The list of OAuth scopes the access token should have.
	//
	// The server may reject the request if some scopes are not allowed.
	OauthScope []string `protobuf:"bytes,2,rep,name=oauth_scope,json=oauthScope" json:"oauth_scope,omitempty"`
	// Minimally accepted validity duration of the returned OAuth token (seconds).
	//
	// The server may return a token that lives longer than this. The maximum is
	// 1h. An attempt to get a token that lives longer than 1h will result in
	// an error.
	//
	// The returned token validity duration doesn't depend on the lifetime of
	// the grant: it's possible to use a grant that expires in 1 sec to get an
	// access token that lives for 1h.
	//
	// Default is 300 sec.
	MinValidityDuration int64 `protobuf:"varint,3,opt,name=min_validity_duration,json=minValidityDuration" json:"min_validity_duration,omitempty"`
}

type MintOAuthTokenViaGrantResponse struct {
	AccessToken string                     `protobuf:"bytes,1,opt,name=access_token,json=accessToken" json:"access_token,omitempty"`
	Expiry      *google_protobuf.Timestamp `protobuf:"bytes,2,opt,name=expiry" json:"expiry,omitempty"`
	// Identifier of the service and its version that produced the token.
	//
	// Has the form "<app-id>/<module-version>". Used only for logging and
	// monitoring.
	ServiceVersion string `protobuf:"bytes,3,opt,name=service_version,json=serviceVersion" json:"service_version,omitempty"`
}

type SignatureAlgorithm int32

type TokenMinterClient interface {
	// MintMachineToken generates a new token for an authenticated machine.
	//
	// It checks that provided certificate was signed by some trusted CA, and it
	// is still valid (non-expired and hasn't been revoked). It then checks that
	// the request was signed by the corresponding private key. Finally it checks
	// that the caller is authorized to generate requested kind of token.
	//
	// If everything checks out, it generates and returns a new machine token.
	//
	// On fatal error it returns detailed error response via same
	// MintMachineTokenResponse. On transient errors it returns generic
	// grpc.Internal error.
	MintMachineToken(ctx context.Context, in *MintMachineTokenRequest, opts ...grpc.CallOption) (*MintMachineTokenResponse, error)
	// MintDelegationToken generates a new bearer delegation token.
	//
	// Such token can be sent in 'X-Delegation-Token-V1' header (alongside regular
	// credentials like OAuth2 access token) to convey that the caller should be
	// authentication as 'delegated_identity' specified in the token.
	//
	// The delegation tokens are subject to multiple restrictions (embedded in
	// the token):
	//   * They have expiration time.
	//   * They are usable only if presented with a credential of someone from
	//     the 'audience' list.
	//   * They are usable only on services specified in the 'services' list.
	//
	// The token server must be configured in advance with all expected
	// combinations of (caller identity, delegated identity, audience, service)
	// tuples. See DelegationRule in config.proto.
	MintDelegationToken(ctx context.Context, in *MintDelegationTokenRequest, opts ...grpc.CallOption) (*MintDelegationTokenResponse, error)
	// MintOAuthTokenGrant generates a new grant for getting an OAuth2 token.
	//
	// This is a special (opaque for clients) token that asserts that the caller
	// at the time of the call was allowed to act as a particular service account
	// to perform a task authorized by an end-user.
	//
	// The returned grant can be used later (when the end-user is no longer
	// present) to get a real OAuth2 access token via MintOAuthTokenViaGrant call.
	//
	// This pair of RPCs is used to "delay" generation of service account OAuth
	// token until some later time, when it is actually needed. This is used by
	// Swarming:
	//   1. When the task is posted, Swarming calls MintOAuthTokenGrant to verify
	//      that the end-user is allowed to act as the requested service account
	//      on Swarming. On success, Swarming stores the grant in the task
	//      metadata.
	//   2. At a later time, when the task is executing and it needs an access
	//      token, Swarming calls MintOAuthTokenViaGrant to convert the grant into
	//      a real OAuth2 token.
	//
	// The returned grant can be used multiple times (as long as its validity
	// duration and the token server policy allows).
	//
	// The token server must be configured in advance with all expected
	// combinations of (caller identity, service account name, end users) tuples.
	// See ServiceAccountRule in config.proto.
	//
	// MintOAuthTokenGrant will check that the requested usage is allowed by the
	// rules. Later, MintOAuthTokenViaGrant will recheck this too.
	MintOAuthTokenGrant(ctx context.Context, in *MintOAuthTokenGrantRequest, opts ...grpc.CallOption) (*MintOAuthTokenGrantResponse, error)
	// MintOAuthTokenViaGrant converts an OAuth2 token grant into an access token.
	//
	// The grant must be previously generated by MintOAuthTokenGrant function, see
	// its docs for more details.
	MintOAuthTokenViaGrant(ctx context.Context, in *MintOAuthTokenViaGrantRequest, opts ...grpc.CallOption) (*MintOAuthTokenViaGrantResponse, error)
}

type TokenMinterServer interface {
	// MintMachineToken generates a new token for an authenticated machine.
	//
	// It checks that provided certificate was signed by some trusted CA, and it
	// is still valid (non-expired and hasn't been revoked). It then checks that
	// the request was signed by the corresponding private key. Finally it checks
	// that the caller is authorized to generate requested kind of token.
	//
	// If everything checks out, it generates and returns a new machine token.
	//
	// On fatal error it returns detailed error response via same
	// MintMachineTokenResponse. On transient errors it returns generic
	// grpc.Internal error.
	MintMachineToken(context.Context, *MintMachineTokenRequest) (*MintMachineTokenResponse, error)
	// MintDelegationToken generates a new bearer delegation token.
	//
	// Such token can be sent in 'X-Delegation-Token-V1' header (alongside regular
	// credentials like OAuth2 access token) to convey that the caller should be
	// authentication as 'delegated_identity' specified in the token.
	//
	// The delegation tokens are subject to multiple restrictions (embedded in
	// the token):
	//   * They have expiration time.
	//   * They are usable only if presented with a credential of someone from
	//     the 'audience' list.
	//   * They are usable only on services specified in the 'services' list.
	//
	// The token server must be configured in advance with all expected
	// combinations of (caller identity, delegated identity, audience, service)
	// tuples. See DelegationRule in config.proto.
	MintDelegationToken(context.Context, *MintDelegationTokenRequest) (*MintDelegationTokenResponse, error)
	// MintOAuthTokenGrant generates a new grant for getting an OAuth2 token.
	//
	// This is a special (opaque for clients) token that asserts that the caller
	// at the time of the call was allowed to act as a particular service account
	// to perform a task authorized by an end-user.
	//
	// The returned grant can be used later (when the end-user is no longer
	// present) to get a real OAuth2 access token via MintOAuthTokenViaGrant call.
	//
	// This pair of RPCs is used to "delay" generation of service account OAuth
	// token until some later time, when it is actually needed. This is used by
	// Swarming:
	//   1. When the task is posted, Swarming calls MintOAuthTokenGrant to verify
	//      that the end-user is allowed to act as the requested service account
	//      on Swarming. On success, Swarming stores the grant in the task
	//      metadata.
	//   2. At a later time, when the task is executing and it needs an access
	//      token, Swarming calls MintOAuthTokenViaGrant to convert the grant into
	//      a real OAuth2 token.
	//
	// The returned grant can be used multiple times (as long as its validity
	// duration and the token server policy allows).
	//
	// The token server must be configured in advance with all expected
	// combinations of (caller identity, service account name, end users) tuples.
	// See ServiceAccountRule in config.proto.
	//
	// MintOAuthTokenGrant will check that the requested usage is allowed by the
	// rules. Later, MintOAuthTokenViaGrant will recheck this too.
	MintOAuthTokenGrant(context.Context, *MintOAuthTokenGrantRequest) (*MintOAuthTokenGrantResponse, error)
	// MintOAuthTokenViaGrant converts an OAuth2 token grant into an access token.
	//
	// The grant must be previously generated by MintOAuthTokenGrant function, see
	// its docs for more details.
	MintOAuthTokenViaGrant(context.Context, *MintOAuthTokenViaGrantRequest) (*MintOAuthTokenViaGrantResponse, error)
}