Documentation ¶
Index ¶
- Constants
- func LoadKeyring(path string) (openpgp.EntityList, error)
- type ArtifactVerifier
- type BuildManifestVerifier
- type BuildVerifier
- type CompositeVerifier
- type DeployPol
- type Digest
- type DigestFetcher
- type DpGroup
- type DpUserEmail
- type Error
- type FileKeyringPolicy
- type FixedKeyringPolicy
- type Manifest
- type NullPolicy
- type Policy
- func LoadKeyringPolicy(keyringPath string, authorizedDeployers map[types.PodID][]string) (Policy, error)
- func NewFileKeyringPolicy(keyringPath string, authorizedDeployers map[types.PodID][]string) (Policy, error)
- func NewUserPolicy(keyringPath string, deployPolicyPath string, preparerApp types.PodID, ...) (p Policy, err error)
- type RawDeployPol
- type Signed
- type UserPolicy
- func (p UserPolicy) Authorize(email, appUser string) bool
- func (p UserPolicy) AuthorizeApp(manifest Manifest, logger logging.Logger) error
- func (p UserPolicy) AuthorizePod(podUser string, manifest Signed, logger logging.Logger) error
- func (p UserPolicy) CheckDigest(digest Digest) error
- func (p UserPolicy) Close()
- type VerificationData
Constants ¶
const ( Null = "none" Keyring = "keyring" User = "user" )
These string constants are used to determine the requested auth policy type both in the "auth" section of preparer config and in p2-launch flags
const VerifyBuild = "build"
const VerifyEither = "either"
const VerifyManifest = "manifest"
const VerifyNone = "none"
Variables ¶
This section is empty.
Functions ¶
func LoadKeyring ¶
func LoadKeyring(path string) (openpgp.EntityList, error)
Types ¶
type ArtifactVerifier ¶
type ArtifactVerifier interface {
VerifyHoistArtifact(localCopy *os.File, verificationData VerificationData) error
}
The artifact verifier is responsible for checking that the artifact was created by a trusted entity.
func NopVerifier ¶
func NopVerifier() ArtifactVerifier
type BuildManifestVerifier ¶
type BuildManifestVerifier struct {
// contains filtered or unexported fields
}
BuildManifestVerifier ensures that the given LaunchableStanza's location field is matched with a corresponding manifest certifying the validity of the build. The manifest is a YAML file containing a single key "artifact_sha". That key represents the hex digest of the artifact tar itself. The manifest is signed by the build system and has a corresponding URL for downloading the signature.
The manifest and signature files should match the following convention if the launchable location is a full path to a file:
If the artifact is located here: https://foo.bar.baz/artifacts/myapp_abc123.tar.gz
Then its build manifest is located here: https://foo.bar.baz/artifacts/myapp_abc123.tar.gz.manifest
The contents of the manifest should be a YAML file with one key -
artifact_sha: abc23456
And its signature file is located here: https://foo.bar.baz/artifacts/myapp_abc123.tar.gz.manifest.sig
func (*BuildManifestVerifier) VerifyHoistArtifact ¶
func (b *BuildManifestVerifier) VerifyHoistArtifact(localCopy *os.File, verificationData VerificationData) error
Returns an error if the stanza's artifact is not signed appropriately. Note that this implementation does not use the pod manifest digest location options.
type BuildVerifier ¶
type BuildVerifier struct {
// contains filtered or unexported fields
}
BuildVerifier is a simple variant of the ArtifactVerifier interface that ensures that the tarball has a matching detached signature matching that of the tarball. It is a simpler version of the BuildManifestVerifier.
If the artifact is located here: https://foo.bar.baz/artifacts/myapp_abc123.tar.gz
Then its signature is located here: https://foo.bar.baz/artifacts/myapp_abc123.tar.gz.sig
func NewBuildVerifier ¶
func (*BuildVerifier) VerifyHoistArtifact ¶
func (b *BuildVerifier) VerifyHoistArtifact(localCopy *os.File, verificationData VerificationData) error
Verifies the artifact against a signature. If signatureLocation is nil, it is inferred by adding a ".sig" suffix to the artifactLocation
type CompositeVerifier ¶
type CompositeVerifier struct {
// contains filtered or unexported fields
}
func NewCompositeVerifier ¶
func NewCompositeVerifier(keyringPath string, fetcher uri.Fetcher, logger *logging.Logger) (*CompositeVerifier, error)
The composite verifier executes verification for both the BuildManifestVerifier and the BuildVerifier. Only one of the two need to pas for verification to pass.
func (*CompositeVerifier) VerifyHoistArtifact ¶
func (b *CompositeVerifier) VerifyHoistArtifact(localCopy *os.File, verificationData VerificationData) error
Attempt manifest verification. If it fails, fallback to the build verifier.
type DeployPol ¶
type DeployPol struct { Groups map[DpGroup]map[DpUserEmail]bool // Each group is a *set* of email addrs Apps map[string][]DpGroup // Each app has a list of authorized groups }
A DeployPol lists all app users that apps can run as and the set of users (humans or other apps) that are allowed to deploy to each app user. (This is the deploy policy, but it isn't a `Policy` interface, so the name is shortened.)
This policy is applicable when an app's security policy is centered around the Unix user that the app runs as. Similar to "sudo", authorization grants one user the ability to run commands (apps) as another user.
The policy file should be a YAML-serialized object that conforms to the layout of the `RawDeployPol` type. The data in the "groups" key is a map: each entry's key defines a group's name and its value defines the email addresses in the group. The name of the group is not significant. The data in the "apps" key is also a map: each entry's key is the name of an app user, and its value is a list of groups, each member of which is authorized to deploy apps that will run as the app user.
By separating apps from groups, it allows some flexibility in managing the deployers for an app. Some possible organizations are:
- Have one group that includes all deployers, and each app user references that group
- Create one group for each app user, explicitly listing all deployers for that app
- Create groups for each team, and let each app user be deployed by the team that develops/manages it
Example policy file:
--- groups: teamA: - alice@my.org - bob@my.org admins: - carol@my.org apps: web: - teamA - admins db: - admins
In this example, "alice" is authorized to deploy a pod named "api" that runs as the Unix user "web". Alice cannot however deploy the pod named "mysql" which runs as the "db" user. Note that Alice *is* permitted to deploy "mysql" running as the user "web"--it is beyond the scope of this policy to ensure that only the "db" user is actually capable of serving database traffic.
func LoadDeployPol ¶
Load a new DeployPol from a file.
type Digest ¶
type Digest interface { Signed }
auth.Digest contains all info needed to certify a digest over the files in a launchable.
type DigestFetcher ¶
type DigestFetcher interface { }
type DpUserEmail ¶
type DpUserEmail string
type Error ¶
auth.Error wraps all errors generated by the authorization layer, allowing errors to carry structured data.
type FileKeyringPolicy ¶
type FileKeyringPolicy struct { KeyringFilename string AuthorizedDeployers map[types.PodID][]string // contains filtered or unexported fields }
FileKeyringPolicy has the same authorization policy as FixedKeyringPolicy, but it always pulls its keyring from a file on disk. Whenever the keyring is needed, the file is reloaded if it has changed since the last time it was read (determined by examining mtime).
func (FileKeyringPolicy) Authorize ¶
func (p FileKeyringPolicy) Authorize(email, appUser string) bool
func (FileKeyringPolicy) AuthorizeApp ¶
func (p FileKeyringPolicy) AuthorizeApp(manifest Manifest, logger logging.Logger) error
func (FileKeyringPolicy) CheckDigest ¶
func (p FileKeyringPolicy) CheckDigest(digest Digest) error
func (FileKeyringPolicy) Close ¶
func (p FileKeyringPolicy) Close()
type FixedKeyringPolicy ¶
type FixedKeyringPolicy struct { Keyring openpgp.KeyRing AuthorizedDeployers map[types.PodID][]string }
The FixedKeyring policy holds one keyring. A pod is authorized to be deployed iff:
- The manifest is signed by a key on the keyring, and
- If the pod ID has an authorization list, the signing key is on the list.
Artifacts can optionally sign their contents. If no digest signature is provided, the deployment is authorized. If a signature exists, deployment is authorized iff the signer is on the keyring.
func (FixedKeyringPolicy) Authorize ¶
func (p FixedKeyringPolicy) Authorize(email, appUser string) bool
func (FixedKeyringPolicy) AuthorizeApp ¶
func (p FixedKeyringPolicy) AuthorizeApp(manifest Manifest, logger logging.Logger) error
func (FixedKeyringPolicy) CheckDigest ¶
func (p FixedKeyringPolicy) CheckDigest(digest Digest) error
func (FixedKeyringPolicy) Close ¶
func (p FixedKeyringPolicy) Close()
type Manifest ¶
auth.Manifest mirrors manifest.Manifest, listing only the data accessors that auth logic cares about.
type NullPolicy ¶
type NullPolicy struct{}
The NullPolicy never disallows anything. Everything is safe!
func (NullPolicy) Authorize ¶
func (p NullPolicy) Authorize(email, appUser string) bool
func (NullPolicy) AuthorizeApp ¶
func (p NullPolicy) AuthorizeApp(manifest Manifest, logger logging.Logger) error
func (NullPolicy) CheckDigest ¶
func (p NullPolicy) CheckDigest(digest Digest) error
func (NullPolicy) Close ¶
func (p NullPolicy) Close()
type Policy ¶
type Policy interface { // Check if an App is authorized to be installed and run on this // node. This involves checking that the app's pod manifest has a // valid signature and that the signer is authorized to // install/run the app. If the action is authorized, `nil` will be // returned. AuthorizeApp(manifest Manifest, logger logging.Logger) error Authorize(email, appUser string) bool // Check if a file digest has a valid signature and that the // signer is authorized to certify the digest. The caller must // separately check that the actual files match the digest. If // the action is authorized, `nil` will be returned. CheckDigest(digest Digest) error // Release any resources held by the policy implementation. Close() }
A Policy encapsulates the behavior a p2 node needs to authorize its actions. It is possible for implementations to rely on other services for these behaviors, so these calls may be slow or transiently fail.
func LoadKeyringPolicy ¶
func NewFileKeyringPolicy ¶
type RawDeployPol ¶
type RawDeployPol struct { Groups map[DpGroup][]DpUserEmail Apps map[string][]DpGroup }
type Signed ¶
type Signed interface { // Return plaintext and signature data. If there is no plaintext // or signature, use `nil`. SignatureData() (plaintext, signature []byte) }
A Signed object contains some plaintext encoding and a signature that data.
type UserPolicy ¶
type UserPolicy struct {
// contains filtered or unexported fields
}
UserPolicy is a Policy that authorizes users' actions instead of simply checking for the presence of a key. Users are identified by the email addresses associated with their signing key. An external policy defines every app user and which email addresses are allowed to act as that app user.
The P2 preparer has special authorization check: apps with the preparer's name are checked with a different effective app user. Hooks, being extensions of the preparer itself, are always authorized the same as the preparer.
The deploy policy file should be a YAML file as specified in the comments for the `DeployPol` type. The given keyring file should contain PGP keys with email addresses that match the emails in the deploy policy. The keyring used by this policy *must be validated* to ensure that each key contains correct email addresses.
func (UserPolicy) Authorize ¶
func (p UserPolicy) Authorize(email, appUser string) bool
func (UserPolicy) AuthorizeApp ¶
func (p UserPolicy) AuthorizeApp(manifest Manifest, logger logging.Logger) error
func (UserPolicy) AuthorizePod ¶
func (UserPolicy) CheckDigest ¶
func (p UserPolicy) CheckDigest(digest Digest) error
func (UserPolicy) Close ¶
func (p UserPolicy) Close()
type VerificationData ¶
type VerificationData struct { // Used by BuildManifestVerifier ManifestLocation *url.URL ManifestSignatureLocation *url.URL // Used by BuildVerifier BuildSignatureLocation *url.URL }
Contains URLs to extra files needed to verify the artifact. Not all verification strategies make use of each field.