Documentation
¶
Overview ¶
Package authz provides network-based and principal-based access control utilities.
Index ¶
- Variables
- func IsPrincipalAuthorised(user string, allowList []string, denyList []string, allowByDefault bool) bool
- type Authoriser
- type DeniedError
- type GatingListener
- type Listener
- type NetworkACL
- func (a *NetworkACL) Allow(n *net.IPNet)
- func (a *NetworkACL) AllowFromString(n string) error
- func (a *NetworkACL) Authorise(addr *net.TCPAddr) error
- func (a *NetworkACL) AuthoriseConn(c net.Conn) error
- func (a *NetworkACL) AuthoriseFromString(addr string) error
- func (a *NetworkACL) Deny(n *net.IPNet)
- func (a *NetworkACL) DenyFromString(n string) error
- type NetworkACLConfig
- type PrincipalACLConfig
Constants ¶
This section is empty.
Variables ¶
var ErrDenied = errors.New("denied by network ACL")
ErrDenied is the sentinel a *DeniedError always unwraps to via errors.Is, so callers can distinguish a deliberate ACL denial from an operational failure (e.g. an unparsable address) without inspecting error text.
Functions ¶
func IsPrincipalAuthorised ¶ added in v0.40.0
func IsPrincipalAuthorised(user string, allowList []string, denyList []string, allowByDefault bool) bool
IsPrincipalAuthorised checks if a user is authorised based on allow and deny lists.
allowByDefault controls the outcome when allowList is empty (no allow rule configured): true authorises the user (subject to denyList), false denies by default. This mirrors NetworkACL.AllowByDefault -- callers should not assume an empty allowList means "allow everyone" without setting this explicitly.
Types ¶
type Authoriser ¶ added in v0.61.0
type Authoriser interface {
Authorise(addr *net.TCPAddr) error
AuthoriseFromString(addr string) error
AuthoriseConn(c net.Conn) error
}
Authoriser checks whether a network address is permitted to connect. A nil return means permitted; a non-nil return describes why not, and matches errors.Is(err, ErrDenied) when the implementation deliberately denied the address (as opposed to failing to evaluate it, e.g. a malformed address).
type DeniedError ¶ added in v0.69.0
type DeniedError struct {
// MatchedNetwork is the specific CIDR that caused the denial - an
// explicit deny-list entry, including one that overrode an allow-list
// match (deny wins). Empty when the address matched neither list and
// the result came from falling through to AllowByDefault=false.
MatchedNetwork string
// AllowByDefault is the ACL's configured fallback, included so a log
// line built from this error doesn't need the *NetworkACL in scope to
// explain a no-match denial.
AllowByDefault bool
}
DeniedError describes why a NetworkACL denied an address. Retrieve it with errors.As to log the specific network/default that decided the outcome.
func (*DeniedError) Error ¶ added in v0.69.0
func (e *DeniedError) Error() string
func (*DeniedError) Is ¶ added in v0.69.0
func (e *DeniedError) Is(target error) bool
Is reports whether target is ErrDenied, so errors.Is(err, ErrDenied) works without callers needing to know about the concrete *DeniedError type.
type GatingListener ¶ added in v0.61.0
GatingListener wraps a net.Listener and applies a gate predicate to each accepted connection. Connections rejected by the gate are closed and the loop retries; only connections that pass the gate are returned.
gate receives the accepted conn and returns true to allow it. A false return closes the connection and retries; gate errors are the gate's responsibility to handle before returning.
func NewGatingListener ¶ added in v0.61.0
NewGatingListener creates a GatingListener that applies gate to every accepted connection. gate must be safe for concurrent use if Accept is called concurrently (in practice net.Listener.Accept is typically called from a single goroutine).
type Listener ¶
Listener is a network listener that enforces an Authoriser on all incoming connections.
func NewListener ¶ added in v0.61.0
NewListener creates a Listener that gates incoming connections via the given Authoriser.
func (*Listener) Accept ¶
Accept waits for and returns the next connection that passes the Authoriser. Rejected connections are closed; the loop retries until an authorised connection arrives.
type NetworkACL ¶
type NetworkACL struct {
AllowByDefault bool
// contains filtered or unexported fields
}
NetworkACL describes network-based access control rules.
func NewNetworkACL ¶
func NewNetworkACL(cfg NetworkACLConfig) (*NetworkACL, error)
NewNetworkACL creates a new NetworkACL from the provided configuration.
func (*NetworkACL) Allow ¶
func (a *NetworkACL) Allow(n *net.IPNet)
Allow adds a network to the allow list.
func (*NetworkACL) AllowFromString ¶
func (a *NetworkACL) AllowFromString(n string) error
AllowFromString parses a network string and adds it to the allow list.
func (*NetworkACL) Authorise ¶
func (a *NetworkACL) Authorise(addr *net.TCPAddr) error
Authorise checks if the provided TCP address is authorised. It returns nil when addr is allowed, or a *DeniedError (retrievable with errors.As, and matching errors.Is(err, ErrDenied)) describing which rule, or default, denied it.
If both allow and deny lists are present, allow is checked first. If an IP is in the allow list but also matches a deny rule, authorisation is denied. This allows denying subsets of allowed CIDR ranges.
func (*NetworkACL) AuthoriseConn ¶
func (a *NetworkACL) AuthoriseConn(c net.Conn) error
AuthoriseConn checks if the provided connection is authorised. It returns nil when authorised, or an error describing why not - see Authorise.
func (*NetworkACL) AuthoriseFromString ¶
func (a *NetworkACL) AuthoriseFromString(addr string) error
AuthoriseFromString checks if the provided address string is authorised. It returns nil when authorised, or an error describing why not - see Authorise. A malformed addr is returned unwrapped, so errors.Is(err, ErrDenied) is false for it, distinguishing "couldn't evaluate" from "ACL said no".
func (*NetworkACL) Deny ¶
func (a *NetworkACL) Deny(n *net.IPNet)
Deny adds a network to the deny list.
func (*NetworkACL) DenyFromString ¶
func (a *NetworkACL) DenyFromString(n string) error
DenyFromString parses a network string and adds it to the deny list.
type NetworkACLConfig ¶
type NetworkACLConfig struct {
AllowedNets []string `json:"allow,omitzero" mapstructure:"allow"`
DeniedNets []string `json:"deny,omitzero" mapstructure:"deny"`
AllowByDefault bool `json:"allow_by_default" mapstructure:"allow-by-default"`
}
NetworkACLConfig describes the configuration for network-based access control.
type PrincipalACLConfig ¶
type PrincipalACLConfig struct {
AllowList []string `mapstructure:"allow-list"`
DenyList []string `mapstructure:"deny-list"`
// AllowByDefault controls the outcome when AllowList is empty (no allow
// rule configured). Mirrors NetworkACLConfig.AllowByDefault; defaults to
// false (deny) so an unconfigured ACL fails closed.
AllowByDefault bool `mapstructure:"allow-by-default"`
}
PrincipalACLConfig describes the configuration for principal-based access control.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package prefixlist provides utilities for fetching and managing IP prefix lists from various cloud providers.
|
Package prefixlist provides utilities for fetching and managing IP prefix lists from various cloud providers. |