Documentation
¶
Index ¶
- Constants
- Variables
- func EscapedSplit(s string, sep rune) []string
- func ReadWithSudoScript(h *HomePolicyLoader, username string) ([]byte, error)
- type DenyList
- type EmptySource
- type Enforcer
- type FileSource
- type HomePolicyLoader
- type Loader
- type MultiPolicyLoader
- type OptionalLoader
- type OsUserLookup
- type Policy
- type PolicyLoader
- type PolicyValidator
- type ProviderLoader
- type ProviderPolicy
- type ProvidersFileLoader
- type ProvidersRow
- type Source
- type SystemPolicyLoader
- type User
- type UserLookup
- type ValidationRowResult
- type ValidationStatus
- type ValidationSummary
Constants ¶
const ( OIDC_CLAIMS = "oidc:" OIDC_WILDCARD_EMAIL = "oidc-match-end:email:" )
Variables ¶
var SystemDefaultPolicyPath = filepath.FromSlash("/etc/opk/auth_id")
SystemDefaultPolicyPath is the default filepath where opkssh policy is defined
var SystemDefaultProvidersPath = filepath.FromSlash("/etc/opk/providers")
SystemDefaultProvidersPath is the default filepath where opkssh provider definitions are configured
Functions ¶
func EscapedSplit ¶ added in v0.11.0
EscapedSplit splits a string by a separator while ignoring the separator in quoted sections. This is useful for strings that may contain the separator character as part of the string and not as a delimiter.
func ReadWithSudoScript ¶
func ReadWithSudoScript(h *HomePolicyLoader, username string) ([]byte, error)
ReadWithSudoScript specifies additional way of loading the policy in the user's home directory (`~/.opk/auth_id`). This is needed when the AuthorizedKeysCommand user does not have privileges to transverse the user's home directory. Instead we call run a command which uses special sudoers permissions to read the policy file.
Doing this is more secure than simply giving opkssh sudoer access because if there was an RCE in opkssh could be triggered an SSH request via AuthorizedKeysCommand, the new opkssh process we use to perform the read would not be compromised. Thus, the compromised opkssh process could not assume full root privileges.
Types ¶
type EmptySource ¶
type EmptySource struct{}
EmptySource implements policy.Source and returns an empty string as the source
func (EmptySource) Source ¶
func (EmptySource) Source() string
type Enforcer ¶
type Enforcer struct {
PolicyLoader Loader
}
Enforcer evaluates opkssh policy to determine if the desired principal is permitted
func (*Enforcer) CheckPolicy ¶
func (p *Enforcer) CheckPolicy(principalDesired string, pkt *pktoken.PKToken, userInfoJson string, sshCert string, keyType string, denyList DenyList, extraArgs []string) error
CheckPolicy loads opkssh policy and checks to see if there is a policy permitting access to principalDesired for the user identified by the PKT's email claim. Returns nil if access is granted. Otherwise, an error is returned.
It is security critical to verify the pkt first before calling this function. This is because if this function is called first, a timing channel exists which allows an attacker check what identities and principals are allowed by the policy.F
type FileSource ¶
type FileSource string
FileSource implements policy.Source by returning a string that is expected to be a filepath
func (FileSource) Source ¶
func (s FileSource) Source() string
type HomePolicyLoader ¶
type HomePolicyLoader struct {
*PolicyLoader
}
HomePolicyLoader contains methods to read/write the opkssh policy file stored in `~/.opk/ssh` from/to a filesystem. All methods that read policy from the filesystem fail and return an error immediately if the permission bits are invalid.
func NewHomePolicyLoader ¶
func NewHomePolicyLoader() *HomePolicyLoader
NewHomePolicyLoader returns an opkssh policy loader that uses the os library to read/write policy from/to the user's home directory, e.g. `~/.opk/auth_id`,
func (*HomePolicyLoader) LoadHomePolicy ¶
func (h *HomePolicyLoader) LoadHomePolicy(username string, skipInvalidEntries bool, optLoader ...OptionalLoader) (*Policy, string, error)
LoadHomePolicy reads the user's opkssh policy at ~/.opk/auth_id (where ~ maps to username's home directory) and returns the filepath read. An error is returned if the file cannot be read, if the permission bits are not correct, or if there is no user with username or has no home directory.
If skipInvalidEntries is true, then invalid user entries are skipped and not included in the returned policy. A user policy's entry is considered valid if it gives username access. The returned policy is stripped of invalid entries. To specify an alternative Loader that will be used if we don't have sufficient permissions to read the policy file in the user's home directory, pass the alternative loader as the last argument.
func (*HomePolicyLoader) UserPolicyPath ¶
func (h *HomePolicyLoader) UserPolicyPath(username string) (string, error)
UserPolicyPath returns the path to the user's opkssh policy file at ~/.opk/auth_id.
type Loader ¶
type Loader interface {
// Load fetches an opkssh policy and returns information describing its
// source. If an error occurs, all return values are nil except the error
// value
Load() (*Policy, Source, error)
}
Loader declares the minimal interface to retrieve an opkssh policy from an arbitrary source
type MultiPolicyLoader ¶
type MultiPolicyLoader struct {
HomePolicyLoader *HomePolicyLoader
SystemPolicyLoader *SystemPolicyLoader
LoaderScript OptionalLoader
Username string
}
MultiPolicyLoader implements policy.Loader by reading both the system default policy (root policy) and user policy (~/.opk/auth_id where ~ maps to Username's home directory)
func NewMultiPolicyLoader ¶ added in v0.7.0
func NewMultiPolicyLoader(username string, loader OptionalLoader) *MultiPolicyLoader
type OptionalLoader ¶
type OptionalLoader func(h *HomePolicyLoader, username string) ([]byte, error)
type OsUserLookup ¶
type OsUserLookup struct{}
OsUserLookup implements the UserLookup interface by invoking the os/user library
type Policy ¶
type Policy struct {
// Users is a list of all user entries in the policy
Users []User
}
Policy represents an opkssh policy
func FromTable ¶
func FromTable(input []byte, path string) (*Policy, []files.ConfigProblem)
FromTable decodes whitespace delimited input into policy.Policy. Any problems encountered during parsing are returned. When verifying, these problems should be ignored so that a error on one line does not prevent all users from logging in.
func (*Policy) AddAllowedPrincipal ¶
AddAllowedPrincipal adds a new allowed principal to the user whose email is equal to userEmail. If no user can be found with the email userEmail, then a new user entry is added with an initial allowed principals list containing principal. No changes are made if the principal is already allowed for this user.
type PolicyLoader ¶
type PolicyLoader struct {
FileLoader files.FileLoader
UserLookup UserLookup
}
PolicyLoader contains methods to read/write the opkssh policy file from/to an arbitrary filesystem. All methods that read policy from the filesystem fail and return an error immediately if the permission bits are invalid.
func (PolicyLoader) CreateIfDoesNotExist ¶
func (l PolicyLoader) CreateIfDoesNotExist(path string) error
func (*PolicyLoader) Dump ¶
func (l *PolicyLoader) Dump(policy *Policy, path string) error
Dump encodes the policy into file and writes the contents to the filepath path
func (*PolicyLoader) LoadPolicyAtPath ¶
func (l *PolicyLoader) LoadPolicyAtPath(path string) (*Policy, error)
LoadPolicyAtPath validates that the policy file at path exists, can be read by the current process, and has the correct permission bits set. Parses the contents and returns a policy.Policy if file permissions are valid and reading is successful; otherwise returns an error.
type PolicyValidator ¶ added in v0.12.0
type PolicyValidator struct {
// contains filtered or unexported fields
}
PolicyValidator validates policy file entries against provider definitions
func NewPolicyValidator ¶ added in v0.12.0
func NewPolicyValidator(providerPolicy *ProviderPolicy) *PolicyValidator
NewPolicyValidator creates a new PolicyValidator from a ProviderPolicy
func (*PolicyValidator) ValidateEntry ¶ added in v0.12.0
func (v *PolicyValidator) ValidateEntry(principal, identityAttr, issuer string, lineNumber int) ValidationRowResult
ValidateEntry validates a single policy entry against the provider definitions
type ProviderLoader ¶ added in v0.12.0
type ProviderLoader interface {
LoadProviderPolicy(path string) (*ProviderPolicy, error)
}
ProviderLoader defines the interface for loading provider policies
type ProviderPolicy ¶
type ProviderPolicy struct {
// contains filtered or unexported fields
}
func (*ProviderPolicy) AddRow ¶
func (p *ProviderPolicy) AddRow(row ProvidersRow)
func (*ProviderPolicy) CreateVerifier ¶
func (p *ProviderPolicy) CreateVerifier() (*verifier.Verifier, error)
func (*ProviderPolicy) GetRows ¶ added in v0.12.0
func (p *ProviderPolicy) GetRows() []ProvidersRow
func (ProviderPolicy) ToString ¶
func (p ProviderPolicy) ToString() string
type ProvidersFileLoader ¶
type ProvidersFileLoader struct {
files.FileLoader
Path string
}
func NewProviderFileLoader ¶
func NewProviderFileLoader() *ProvidersFileLoader
func (*ProvidersFileLoader) FromTable ¶
func (o *ProvidersFileLoader) FromTable(input []byte, path string) *ProviderPolicy
FromTable decodes whitespace delimited input into policy.Policy Path is passed only for logging purposes
func (*ProvidersFileLoader) LoadProviderPolicy ¶
func (o *ProvidersFileLoader) LoadProviderPolicy(path string) (*ProviderPolicy, error)
func (ProvidersFileLoader) ToTable ¶
func (o ProvidersFileLoader) ToTable(opPolicies ProviderPolicy) files.Table
FromTable decodes whitespace delimited input into policy.Policy
type ProvidersRow ¶
func (ProvidersRow) GetExpirationPolicy ¶
func (p ProvidersRow) GetExpirationPolicy() (verifier.ExpirationPolicy, error)
func (ProvidersRow) ToString ¶
func (p ProvidersRow) ToString() string
type Source ¶
type Source interface {
// Source returns a string describing the source of an opkssh policy. The
// returned value is empty if there is no information about its source
Source() string
}
Source declares the minimal interface to describe the source of a fetched opkssh policy (i.e. where the policy is retrieved from)
type SystemPolicyLoader ¶
type SystemPolicyLoader struct {
*PolicyLoader
}
SystemPolicyLoader contains methods to read/write the system wide opkssh policy file from/to a filesystem. All methods that read policy from the filesystem fail and return an error immediately if the permission bits are invalid.
func NewSystemPolicyLoader ¶
func NewSystemPolicyLoader() *SystemPolicyLoader
NewSystemPolicyLoader returns an opkssh policy loader that uses the os library to read/write system policy from/to the filesystem.
func (*SystemPolicyLoader) LoadSystemPolicy ¶
func (s *SystemPolicyLoader) LoadSystemPolicy() (*Policy, Source, error)
LoadSystemPolicy reads the opkssh policy at SystemDefaultPolicyPath. An error is returned if the file cannot be read or if the permissions bits are not correct.
type User ¶
type User struct {
// IdentityAttribute is a string that is either structured or unstructured.
// Structured: <IdentityProtocolMatching>:<Attribute>:<Value>
// E.g. `oidc:groups:ssh-users`
// Using the structured identifier allows the capability of constructing
// complex user matchers.
//
// Unstructured:
// This is older version that only works with OIDC Identity Tokens, with
// the claim being `email` or `sub`. The expected value is to be the user's
// email or the user's subscriber ID. The expected value used when comparing
// against an id_token's email claim Subscriber ID is a unique identifier
// for the user at the OpenID Provider
IdentityAttribute string
// Principals is a list of allowed principals
Principals []string
// Sub string
Issuer string
}
User is an opkssh policy user entry
type UserLookup ¶
UserLookup defines the minimal interface to lookup users on the current system
func NewOsUserLookup ¶
func NewOsUserLookup() UserLookup
type ValidationRowResult ¶ added in v0.12.0
type ValidationRowResult struct {
Status ValidationStatus `json:"status"`
Hints []string `json:"hints"`
Principal string `json:"principal"`
IdentityAttr string `json:"identity_attr"`
Issuer string `json:"issuer"`
Reason string `json:"reason"`
LineNumber int `json:"line_number"` // Line number in the policy file (1-indexed)
}
ValidationRowResult represents the result of validating a single policy entry
type ValidationStatus ¶ added in v0.12.0
type ValidationStatus string
ValidationStatus represents the validation result status
const ( StatusSuccess ValidationStatus = "SUCCESS" StatusWarning ValidationStatus = "WARNING" StatusError ValidationStatus = "ERROR" )
type ValidationSummary ¶ added in v0.12.0
Summary holds aggregated statistics about validation results
func CalculateSummary ¶ added in v0.12.0
func CalculateSummary(results []ValidationRowResult) ValidationSummary
CalculateSummary calculates summary statistics from a list of validation results
func (*ValidationSummary) GetExitCode ¶ added in v0.12.0
func (s *ValidationSummary) GetExitCode() int
GetExitCode returns the appropriate exit code (0 for success, 1 for errors/warnings)
func (*ValidationSummary) HasErrors ¶ added in v0.12.0
func (s *ValidationSummary) HasErrors() bool
HasErrors returns true if there are any errors or warnings
Source Files
Directories