security/types.vdl - release.go.v23 - Git at Google

 // Copyright 2015 The Vanadium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 package security

 import "v.io/v23/uniqueid"

 // BlessingPattern is a pattern that is matched by specific blessings.
 //
 // A pattern can either be a blessing (slash-separated human-readable string)
 // or a blessing ending in "/$". A pattern ending in "/$" is matched exactly
 // by the blessing specified by the pattern string with the "/$" suffix stripped
 // out. For example, the pattern "a/b/c/$" is matched by exactly by the blessing
 // "a/b/c".
 //
 // A pattern not ending in "/$" is more permissive, and is also matched by blessings
 // that are extensions of the pattern (including the pattern itself). For example, the
 // pattern "a/b/c" is matched by the blessings "a/b/c", "a/b/c/x", "a/b/c/x/y", etc.
 //
 // TODO(ataly, ashankar): Define a formal BNF grammar for blessings and blessing patterns.
 type BlessingPattern string

 // Hash identifies a cryptographic hash function approved for use in signature algorithms.
 type Hash string

 const (
 	// NoExtension is an optional terminator for a blessing pattern indicating that the pattern
 	// cannot match any extensions of the blessing from that point onwards.
 	NoExtension = BlessingPattern("$")

 	// TODO(ataly, ashankar): The semantics of AllPrincipals breaks monotonicity in
 	// AccessLists with NotIn clauses. For instance, the AccessList "In: {AllPrincipals}, NotIn: {"foo"}
 	// matches the principal that presents no recognizable blessings ([]) however does not
 	// match the principal that presents "foo" as the only recognizable blessings (["foo"])
 	// We need to sort this out.
 	AllPrincipals = BlessingPattern("...") // Glob pattern that matches all blessings.

 	ChainSeparator = ":" // ChainSeparator joins blessing names to form a blessing chain name.

 	SHA1Hash   = Hash("SHA1")   // SHA1 cryptographic hash function defined in RFC3174.
 	SHA256Hash = Hash("SHA256") // SHA256 cryptographic hash function defined  in FIPS 180-4.
 	SHA384Hash = Hash("SHA384") // SHA384 cryptographic hash function defined in FIPS 180-2.
 	SHA512Hash = Hash("SHA512") // SHA512 cryptographic hash function defined in FIPS 180-2.

 	SignatureForMessageSigning       = "S1" // Signature.Purpose used by a Principal to sign arbitrary messages.
 	SignatureForBlessingCertificates = "B1" // Signature.Purpose used by a Principal when signing Certificates for creating blessings.
 	SignatureForDischarge            = "D1" // Signature.Purpose used by a Principal when signing discharges for public-key based third-party caveats.
 )

 // Signature represents a digital signature.
 type Signature struct {
 	// Purpose of the signature. Can be used to prevent type attacks.
 	// (See Section 4.2 of http://www-users.cs.york.ac.uk/~jac/PublishedPapers/reviewV1_1997.pdf for example).
 	// The actual signature (R, S values for ECDSA keys) is produced by signing: Hash(Hash(message), Hash(Purpose)).
 	Purpose []byte
 	// Cryptographic hash function applied to the message before computing the signature.
 	Hash Hash
 	// Pair of integers that make up an ECDSA signature.
 	R, S []byte
 }

 // ThirdPartyRequirements specifies the information required by the third-party
 // that will issue discharges for third-party caveats.
 //
 // These requirements are typically used to construct a DischargeImpetus, which
 // will be sent to the third-party.
 type ThirdPartyRequirements struct {
 	ReportServer    bool // The blessings presented by the server of an IPC call.
 	ReportMethod    bool // The name of the method being invoked.
 	ReportArguments bool // Arguments to the method being invoked.
 }

 // DischargeImpetus encapsulates the motivation for a discharge being sought.
 //
 // These values are reported by a principal that is requesting a Discharge for
 // a third-party caveat on one of its blessings. The third-party issues
 // discharges cannot safely assume that all these values are provided, or that
 // they are provided honestly.
 //
 // Implementations of services that issue discharges are encouraged to add
 // caveats to the discharge that bind the discharge to the impetus, thereby
 // rendering the discharge unsuable for any other purpose.
 type DischargeImpetus struct {
 	Server    []BlessingPattern // The client intends to use the discharge to communicate with a server that has a blessing matching one of the patterns in this set.
 	Method    string            // Name of the method being invoked by the client.
 	Arguments []any             // Arguments to the method invocation.
 }

 // Certificate represents the cryptographic proof of the binding of
 // extensions of a blessing held by one principal to another (represented by
 // a public key) under specific caveats.
 //
 // For example, if a principal P1 has a blessing "alice", then it can
 // extend it with a Certificate to generate the blessing "alice/friend" for
 // another principal P2.
 type Certificate struct {
 	Extension string    // Human-readable string extension bound to PublicKey.
 	PublicKey []byte    // DER-encoded PKIX public key.
 	Caveats   []Caveat  // Caveats on the binding of Name to PublicKey.
 	Signature Signature // Signature by the blessing principal that binds the extension to the public key.
 }

 // CaveatDescriptor defines an association between a caveat validation function
 // (addressed by globally unique identifier) and the data needed by the
 // validation function.
 //
 // For a validator to be invoked, a validation function must be registered with
 // the validator description in the language that the function is defined in.
 type CaveatDescriptor struct {
 	Id        uniqueid.Id // The identifier of the caveat validation function.
 	ParamType typeobject  // The type of the parameter expected by the validation function.
 }

 // Caveat is a condition on the validity of a blessing/discharge.
 //
 // These conditions are provided when asking a principal to create
 // a blessing/discharge and are verified when extracting blessings
 // (Blessings.ForName in the Go API).
 //
 // Given a Hash, the message digest of a caveat is:
 // Hash(Hash(Id), Hash(ParamVom))
 type Caveat struct {
 	Id       uniqueid.Id  // The identifier of the caveat validation function.
 	ParamVom []byte       // VOM-encoded bytes of the parameters to be provided to the validation function.
 }

 // WireBlessings encapsulates wire format of a set of blessings and the
 // corresponding cryptographic proof that binds them to a principal
 // (identified by a public key).
 //
 // This structure is the "wire" format for sending and receiving blessings
 // in RPCs or marshaling to persistent storage. Typically, languages will
 // provide a factory function that converts this wire representation to
 // a more usable object to inspect and manipulate these blessings.
 type WireBlessings struct {
 	// CertificateChains is an array of chains of certificates that bind
 	// a blessing to the public key in the last certificate of the chain.
 	CertificateChains [][]Certificate
 }

 // WireDischarge encapsulates the wire format of a third-party caveat
 // Discharge.
 type WireDischarge union {
 	PublicKey PublicKeyDischarge // Discharge for PublicKeyThirdPartyCaveat
 }

 // RejectedBlessing describes why a blessing failed validation.
 type RejectedBlessing struct {
 	Blessing string
 	Err error
 }

 error (
 	UnrecognizedRoot(rootKey string, details error) {"en": "unrecognized public key {rootKey} in root certificate{:details}"}

 	AuthorizationFailed(remote []string, remoteErr []RejectedBlessing, local []string) { "en": "principal with blessings {remote} (rejected {remoteErr}) is not authorized by principal with blessings {local}"}

 	InvalidSigningBlessingCaveat(id uniqueid.Id) {"en": "blessing has caveat with UUID {id} which makes it unsuitable for signing -- please use blessings with just Expiry caveats"}

 	PublicKeyNotAllowed(got, want string) { "en": "peer has public key {got}, not the authorized public key {want}" }

 	EndpointAuthorizationFailed(endpoint string, remote []string, rejected []RejectedBlessing,) { "en": "blessings in endpoint {endpoint} not matched by blessings presented: {remote} (rejected {rejected})"}
 )
	// Copyright 2015 The Vanadium Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	package security

	import "v.io/v23/uniqueid"

	// BlessingPattern is a pattern that is matched by specific blessings.
	//
	// A pattern can either be a blessing (slash-separated human-readable string)
	// or a blessing ending in "/$". A pattern ending in "/$" is matched exactly
	// by the blessing specified by the pattern string with the "/$" suffix stripped
	// out. For example, the pattern "a/b/c/$" is matched by exactly by the blessing
	// "a/b/c".
	//
	// A pattern not ending in "/$" is more permissive, and is also matched by blessings
	// that are extensions of the pattern (including the pattern itself). For example, the
	// pattern "a/b/c" is matched by the blessings "a/b/c", "a/b/c/x", "a/b/c/x/y", etc.
	//
	// TODO(ataly, ashankar): Define a formal BNF grammar for blessings and blessing patterns.
	type BlessingPattern string

	// Hash identifies a cryptographic hash function approved for use in signature algorithms.
	type Hash string

	const (
	// NoExtension is an optional terminator for a blessing pattern indicating that the pattern
	// cannot match any extensions of the blessing from that point onwards.
	NoExtension = BlessingPattern("$")

	// TODO(ataly, ashankar): The semantics of AllPrincipals breaks monotonicity in
	// AccessLists with NotIn clauses. For instance, the AccessList "In: {AllPrincipals}, NotIn: {"foo"}
	// matches the principal that presents no recognizable blessings ([]) however does not
	// match the principal that presents "foo" as the only recognizable blessings (["foo"])
	// We need to sort this out.
	AllPrincipals = BlessingPattern("...") // Glob pattern that matches all blessings.

	ChainSeparator = ":" // ChainSeparator joins blessing names to form a blessing chain name.

	SHA1Hash = Hash("SHA1") // SHA1 cryptographic hash function defined in RFC3174.
	SHA256Hash = Hash("SHA256") // SHA256 cryptographic hash function defined in FIPS 180-4.
	SHA384Hash = Hash("SHA384") // SHA384 cryptographic hash function defined in FIPS 180-2.
	SHA512Hash = Hash("SHA512") // SHA512 cryptographic hash function defined in FIPS 180-2.

	SignatureForMessageSigning = "S1" // Signature.Purpose used by a Principal to sign arbitrary messages.
	SignatureForBlessingCertificates = "B1" // Signature.Purpose used by a Principal when signing Certificates for creating blessings.
	SignatureForDischarge = "D1" // Signature.Purpose used by a Principal when signing discharges for public-key based third-party caveats.
	)

	// Signature represents a digital signature.
	type Signature struct {
	// Purpose of the signature. Can be used to prevent type attacks.
	// (See Section 4.2 of http://www-users.cs.york.ac.uk/~jac/PublishedPapers/reviewV1_1997.pdf for example).
	// The actual signature (R, S values for ECDSA keys) is produced by signing: Hash(Hash(message), Hash(Purpose)).
	Purpose []byte
	// Cryptographic hash function applied to the message before computing the signature.
	Hash Hash
	// Pair of integers that make up an ECDSA signature.
	R, S []byte
	}

	// ThirdPartyRequirements specifies the information required by the third-party
	// that will issue discharges for third-party caveats.
	//
	// These requirements are typically used to construct a DischargeImpetus, which
	// will be sent to the third-party.
	type ThirdPartyRequirements struct {
	ReportServer bool // The blessings presented by the server of an IPC call.
	ReportMethod bool // The name of the method being invoked.
	ReportArguments bool // Arguments to the method being invoked.
	}

	// DischargeImpetus encapsulates the motivation for a discharge being sought.
	//
	// These values are reported by a principal that is requesting a Discharge for
	// a third-party caveat on one of its blessings. The third-party issues
	// discharges cannot safely assume that all these values are provided, or that
	// they are provided honestly.
	//
	// Implementations of services that issue discharges are encouraged to add
	// caveats to the discharge that bind the discharge to the impetus, thereby
	// rendering the discharge unsuable for any other purpose.
	type DischargeImpetus struct {
	Server []BlessingPattern // The client intends to use the discharge to communicate with a server that has a blessing matching one of the patterns in this set.
	Method string // Name of the method being invoked by the client.
	Arguments []any // Arguments to the method invocation.
	}

	// Certificate represents the cryptographic proof of the binding of
	// extensions of a blessing held by one principal to another (represented by
	// a public key) under specific caveats.
	//
	// For example, if a principal P1 has a blessing "alice", then it can
	// extend it with a Certificate to generate the blessing "alice/friend" for
	// another principal P2.
	type Certificate struct {
	Extension string // Human-readable string extension bound to PublicKey.
	PublicKey []byte // DER-encoded PKIX public key.
	Caveats []Caveat // Caveats on the binding of Name to PublicKey.
	Signature Signature // Signature by the blessing principal that binds the extension to the public key.
	}

	// CaveatDescriptor defines an association between a caveat validation function
	// (addressed by globally unique identifier) and the data needed by the
	// validation function.
	//
	// For a validator to be invoked, a validation function must be registered with
	// the validator description in the language that the function is defined in.
	type CaveatDescriptor struct {
	Id uniqueid.Id // The identifier of the caveat validation function.
	ParamType typeobject // The type of the parameter expected by the validation function.
	}

	// Caveat is a condition on the validity of a blessing/discharge.
	//
	// These conditions are provided when asking a principal to create
	// a blessing/discharge and are verified when extracting blessings
	// (Blessings.ForName in the Go API).
	//
	// Given a Hash, the message digest of a caveat is:
	// Hash(Hash(Id), Hash(ParamVom))
	type Caveat struct {
	Id uniqueid.Id // The identifier of the caveat validation function.
	ParamVom []byte // VOM-encoded bytes of the parameters to be provided to the validation function.
	}

	// WireBlessings encapsulates wire format of a set of blessings and the
	// corresponding cryptographic proof that binds them to a principal
	// (identified by a public key).
	//
	// This structure is the "wire" format for sending and receiving blessings
	// in RPCs or marshaling to persistent storage. Typically, languages will
	// provide a factory function that converts this wire representation to
	// a more usable object to inspect and manipulate these blessings.
	type WireBlessings struct {
	// CertificateChains is an array of chains of certificates that bind
	// a blessing to the public key in the last certificate of the chain.
	CertificateChains [][]Certificate
	}

	// WireDischarge encapsulates the wire format of a third-party caveat
	// Discharge.
	type WireDischarge union {
	PublicKey PublicKeyDischarge // Discharge for PublicKeyThirdPartyCaveat
	}

	// RejectedBlessing describes why a blessing failed validation.
	type RejectedBlessing struct {
	Blessing string
	Err error
	}

	error (
	UnrecognizedRoot(rootKey string, details error) {"en": "unrecognized public key {rootKey} in root certificate{:details}"}

	AuthorizationFailed(remote []string, remoteErr []RejectedBlessing, local []string) { "en": "principal with blessings {remote} (rejected {remoteErr}) is not authorized by principal with blessings {local}"}

	InvalidSigningBlessingCaveat(id uniqueid.Id) {"en": "blessing has caveat with UUID {id} which makes it unsuitable for signing -- please use blessings with just Expiry caveats"}

	PublicKeyNotAllowed(got, want string) { "en": "peer has public key {got}, not the authorized public key {want}" }

	EndpointAuthorizationFailed(endpoint string, remote []string, rejected []RejectedBlessing,) { "en": "blessings in endpoint {endpoint} not matched by blessings presented: {remote} (rejected {rejected})"}
	)