Documentation ¶
Overview ¶
Package permissions provides a way to keep track of users, login states and permissions.
Index ¶
- Constants
- Variables
- func PermissionDenied(w http.ResponseWriter, req *http.Request)
- func ValidUsernamePassword(username, password string) error
- type Permissions
- func (perm *Permissions) AddAdminPath(prefix string)
- func (perm *Permissions) AddPublicPath(prefix string)
- func (perm *Permissions) AddUserPath(prefix string)
- func (perm *Permissions) Clear()
- func (perm *Permissions) DenyFunction() http.HandlerFunc
- func (perm *Permissions) Middleware(next http.Handler) http.Handler
- func (perm *Permissions) Rejected(w http.ResponseWriter, req *http.Request) bool
- func (perm *Permissions) ServeHTTP(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
- func (perm *Permissions) SetAdminPath(pathPrefixes []string)
- func (perm *Permissions) SetDenyFunction(f http.HandlerFunc)
- func (perm *Permissions) SetPublicPath(pathPrefixes []string)
- func (perm *Permissions) SetUserPath(pathPrefixes []string)
- func (perm *Permissions) UserState() pinterface.IUserState
- type UserState
- func NewUserState(dbindex int, randomseed bool, redisHostPort string) *UserState
- func NewUserState2(dbindex int, randomseed bool, redisHostPort string) (*UserState, error)
- func NewUserStateSimple() *UserState
- func NewUserStateSimple2() (*UserState, error)
- func NewUserStateWithPassword(hostname, password string) *UserState
- func NewUserStateWithPassword2(hostname, password string) (*UserState, error)
- func (state *UserState) AddUnconfirmed(username, confirmationCode string)
- func (state *UserState) AddUser(username, password, email string)
- func (state *UserState) AdminRights(req *http.Request) bool
- func (state *UserState) AllUnconfirmedUsernames() ([]string, error)
- func (state *UserState) AllUsernames() ([]string, error)
- func (state *UserState) AlreadyHasConfirmationCode(confirmationCode string) bool
- func (state *UserState) BooleanField(username, fieldname string) bool
- func (state *UserState) ClearCookie(w http.ResponseWriter)
- func (state *UserState) Close()
- func (state *UserState) Confirm(username string)
- func (state *UserState) ConfirmUserByConfirmationCode(confirmationCode string) error
- func (state *UserState) ConfirmationCode(username string) (string, error)
- func (state *UserState) CookieSecret() string
- func (state *UserState) CookieTimeout(username string) int64
- func (state *UserState) CorrectPassword(username, password string) bool
- func (state *UserState) Creator() pinterface.ICreator
- func (state *UserState) DatabaseIndex() int
- func (state *UserState) Email(username string) (string, error)
- func (state *UserState) FindUserByConfirmationCode(confirmationCode string) (string, error)
- func (state *UserState) GenerateUniqueConfirmationCode() (string, error)
- func (state *UserState) GetToken(username string) (string, error)
- func (state *UserState) HasEmail(email string) (string, error)
- func (state *UserState) HasUser(username string) bool
- func (state *UserState) HasUser2(username string) (bool, error)
- func (state *UserState) HashPassword(username, password string) string
- func (state *UserState) Host() pinterface.IHost
- func (state *UserState) IsAdmin(username string) bool
- func (state *UserState) IsConfirmed(username string) bool
- func (state *UserState) IsLoggedIn(username string) bool
- func (state *UserState) Login(w http.ResponseWriter, username string) error
- func (state *UserState) Logout(username string)
- func (state *UserState) MarkConfirmed(username string)
- func (state *UserState) PasswordAlgo() string
- func (state *UserState) PasswordHash(username string) (string, error)
- func (state *UserState) Pool() *simpleredis.ConnectionPool
- func (state *UserState) Properties(username string) []string
- func (state *UserState) RemoveAdminStatus(username string)
- func (state *UserState) RemoveToken(username string)
- func (state *UserState) RemoveUnconfirmed(username string)
- func (state *UserState) RemoveUser(username string)
- func (state *UserState) SetAdminStatus(username string)
- func (state *UserState) SetBooleanField(username, fieldname string, val bool)
- func (state *UserState) SetCookieSecret(cookieSecret string)
- func (state *UserState) SetCookieTimeout(cookieTime int64)
- func (state *UserState) SetLoggedIn(username string)
- func (state *UserState) SetLoggedOut(username string)
- func (state *UserState) SetMinimumConfirmationCodeLength(length int)
- func (state *UserState) SetPassword(username, password string)
- func (state *UserState) SetPasswordAlgo(algorithm string) error
- func (state *UserState) SetToken(username, token string, expire time.Duration)
- func (state *UserState) SetUsernameCookie(w http.ResponseWriter, username string) error
- func (state *UserState) SetUsernameCookieOnlyHTTPS(w http.ResponseWriter, username string) error
- func (state *UserState) UserRights(req *http.Request) bool
- func (state *UserState) Username(req *http.Request) string
- func (state *UserState) UsernameCookie(req *http.Request) (string, error)
- func (state *UserState) Users() pinterface.IHashMap
Constants ¶
const (
// Version number. Stable API within major version numbers.
Version = 2.6
)
Variables ¶
var ( // ErrNotFound is returned if something is not found ErrNotFound = errors.New("not found") // ErrNoCookieUsername is returned if a username could not be retrieved from a cookie ErrNoCookieUsername = errors.New("could not retrieve the username from browser cookie") // ErrNoCookieEmptyUsername is returned if the cookie could not be set because the username was empty ErrNoCookieEmptyUsername = errors.New("can't set cookie for empty username") // ErrNoCookieMissingUser is returned if the user does not exist when about to store a cookie ErrNoCookieMissingUser = errors.New("can't store cookie for non-existing user") // ErrRedisConnectionFailure is returned if the Redis server is unreachable ErrRedisConnectionFailure = errors.New("unable to connect to Redis server on port 6379") // ErrRedisLostConnection is returned if the connection to the Redis server is lost ErrRedisLostConnection = errors.New("lost connection to Redis") // ErrUsersAlreadyConfirmed is returned if all users are confirmed and no confirmation can be done ErrUsersAlreadyConfirmed = errors.New("all existing users are already confirmed") // ErrConfirmationNoLongerValid is returned if the given confirmation code is invalid ErrConfirmationNoLongerValid = errors.New("the confirmation code is no longer valid") // ErrConfirmationUserMissing is returned if the confirmation fails because the user does not exist // on the list of users that are unconfirmed. ErrConfirmationUserMissing = errors.New("the user that is to be confirmed no longer exists") // ErrConfirmationNotUnique is returned if there are issues generating confirmation codes. This should normally not happen. ErrConfirmationNotUnique = errors.New("too many generated confirmation codes are not unique") // ErrInvalidUsername is returned if the given username contains characters that the default validator does not accept ErrInvalidUsername = errors.New("only numbers, underscore and some letters are allowed in usernames") // ErrSameUsernameAndPassword is returned if the username and password are equal ErrSameUsernameAndPassword = errors.New("username and password must be different, try another password") )
Functions ¶
func PermissionDenied ¶
func PermissionDenied(w http.ResponseWriter, req *http.Request)
PermissionDenied is the default "permission denied" http handler.
func ValidUsernamePassword ¶
ValidUsernamePassword checks that the given username and password are different. Also check if the chosen username only contains letters, numbers and/or underscore. Use the "CorrectPassword" function for checking if the password is correct. Don't use this function if you wish to use e-mail addresses as usernames.
Types ¶
type Permissions ¶
type Permissions struct {
// contains filtered or unexported fields
}
Permissions is a structure that keeps track of the permissions for various path prefixes
func New ¶
func New() *Permissions
New will initialize a Permissions struct with all the default settings. This will also connect to the redis host at localhost:6379.
func New2 ¶
func New2() (*Permissions, error)
New2 will initialize a Permissions struct with all the default settings. This will also connect to the redis host at localhost:6379.
func NewPermissions ¶
func NewPermissions(state *UserState) *Permissions
NewPermissions will initialize a Permissions struct with the given UserState and a few default paths for admin/user/public path prefixes.
func NewWithRedisConf ¶
func NewWithRedisConf(dbindex int, hostPort string) *Permissions
NewWithRedisConf will initialize a Permissions struct with Redis DB index and host:port. Calls log.Fatal if something goes wrong.
func NewWithRedisConf2 ¶
func NewWithRedisConf2(dbindex int, hostPort string) (*Permissions, error)
NewWithRedisConf2 will initialize a Permissions struct with Redis DB index and host:port. Returns an error if something goes wrong.
func (*Permissions) AddAdminPath ¶
func (perm *Permissions) AddAdminPath(prefix string)
AddAdminPath registers a path prefix for URLs that shall only be reached by logged in administrators
func (*Permissions) AddPublicPath ¶
func (perm *Permissions) AddPublicPath(prefix string)
AddPublicPath registers a path prefix for URLs that can be reached by anyone
func (*Permissions) AddUserPath ¶
func (perm *Permissions) AddUserPath(prefix string)
AddUserPath registers a path prefix for URLs that shall only be reached by logged in users
func (*Permissions) Clear ¶
func (perm *Permissions) Clear()
Clear sets every URL path prefix permission to "public"
func (*Permissions) DenyFunction ¶
func (perm *Permissions) DenyFunction() http.HandlerFunc
DenyFunction returns the current http.HandlerFunc, for when permissions are denied.
func (*Permissions) Middleware ¶
func (perm *Permissions) Middleware(next http.Handler) http.Handler
Middleware handler (compatible with Chi)
func (*Permissions) Rejected ¶
func (perm *Permissions) Rejected(w http.ResponseWriter, req *http.Request) bool
Rejected checks if a given request should be rejected.
func (*Permissions) ServeHTTP ¶
func (perm *Permissions) ServeHTTP(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
Middleware handler (compatible with Negroni)
func (*Permissions) SetAdminPath ¶
func (perm *Permissions) SetAdminPath(pathPrefixes []string)
SetAdminPath can be used for setting all URL path prefixes that are for the logged in administrator pages.
func (*Permissions) SetDenyFunction ¶
func (perm *Permissions) SetDenyFunction(f http.HandlerFunc)
SetDenyFunction can be used for specifying a http.HandlerFunc that will be used when the permissions are denied.
func (*Permissions) SetPublicPath ¶
func (perm *Permissions) SetPublicPath(pathPrefixes []string)
SetPublicPath can be used for setting all URL path prefixes that are for the public pages.
func (*Permissions) SetUserPath ¶
func (perm *Permissions) SetUserPath(pathPrefixes []string)
SetUserPath can be used for setting all URL path prefixes that are for the logged in user pages.
func (*Permissions) UserState ¶
func (perm *Permissions) UserState() pinterface.IUserState
UserState retrieves the UserState struct
type UserState ¶
type UserState struct {
// contains filtered or unexported fields
}
UserState is a struct for dealing with the user state, users and passwords. Can also be used for retrieving the underlying Redis connection pool. The default password hashing algorithm is "bcrypt+", which is the same as "bcrypt", but with backwards compatibility for checking sha256 hashes.
func NewUserState ¶
NewUserState will create a new *UserState that can be used for managing users. dbindex is the Redis database index (0 is a good default value). If randomseed is true, the random number generator will be seeded after generating the cookie secret (true is a good default value). redisHostPort is host:port for the desired Redis server (can be blank for localhost). Also creates a new ConnectionPool. Calls log.Fatal if things go wrong.
func NewUserState2 ¶
NewUserState2 will create a new *UserState that can be used for managing users. dbindex is the Redis database index (0 is a good default value). If randomseed is true, the random number generator will be seeded after generating the cookie secret (true is a good default value). redisHostPort is host:port for the desired Redis server (can be blank for localhost) Also creates a new ConnectionPool. Returns an error if things go wrong.
func NewUserStateSimple ¶
func NewUserStateSimple() *UserState
NewUserStateSimple will create a new *UserState that can be used for managing users. The random number generator will be seeded after generating the cookie secret. A connection pool for the local Redis server (dbindex 0) will be created. Calls log.Fatal if things go wrong.
func NewUserStateSimple2 ¶
NewUserStateSimple2 will create a new *UserState that can be used for managing users. The random number generator will be seeded after generating the cookie secret. A connection pool for the local Redis server (dbindex 0) will be created. Returns an error if things go wrong.
func NewUserStateWithPassword ¶
NewUserStateWithPassword is the same as NewUserStateSimple, but also takes a Redis hostname and a Redis password. Use NewUserState for control over the database index and port number. Calls log.Fatal if things go wrong.
func NewUserStateWithPassword2 ¶
NewUserStateWithPassword2 is the same as NewUserStateSimple2, but takes a hostname and a password. Use NewUserState2 for control over the database index and port number. Returns an error if things go wrong.
func (*UserState) AddUnconfirmed ¶
AddUnconfirmed adds a user that is registered but not confirmed.
func (*UserState) AddUser ¶
AddUser creates a user and hashes the password, does not check for rights. The given data must be valid.
func (*UserState) AdminRights ¶
AdminRights checks if the current user is logged in and has administrator rights.
func (*UserState) AllUnconfirmedUsernames ¶
AllUnconfirmedUsernames returns a list of all registered users that are not yet confirmed.
func (*UserState) AllUsernames ¶
AllUsernames retrieves a list of all usernames.
func (*UserState) AlreadyHasConfirmationCode ¶
AlreadyHasConfirmationCode runs through all confirmation codes of all unconfirmed users and checks if this confirmationCode is already in use.
func (*UserState) BooleanField ¶
BooleanField returns the boolean value for a given username and field name. If the user or field is missing, false will be returned. Useful for states where it makes sense that the returned value is not true unless everything is in order.
func (*UserState) ClearCookie ¶
func (state *UserState) ClearCookie(w http.ResponseWriter)
ClearCookie will try to clear the user cookie by setting it to expired. Some browsers *may* be configured to keep cookies even after this, but that is highly unusual.
func (*UserState) Confirm ¶
Confirm removes the username from the list of unconfirmed users and mark the user as confirmed.
func (*UserState) ConfirmUserByConfirmationCode ¶
ConfirmUserByConfirmationCode takes a confirmation code and mark the corresponding unconfirmed user as confirmed.
func (*UserState) ConfirmationCode ¶
ConfirmationCode gets the confirmation code for a specific user.
func (*UserState) CookieSecret ¶
CookieSecret returns the current cookie secret.
func (*UserState) CookieTimeout ¶
CookieTimeout gets how long a login cookie should last, in seconds.
func (*UserState) CorrectPassword ¶
CorrectPassword checks if a password is correct. username is needed because it is part of the hash.
func (*UserState) Creator ¶
func (state *UserState) Creator() pinterface.ICreator
Creator returns a struct for creating data structures with
func (*UserState) DatabaseIndex ¶
DatabaseIndex gets the Redis database index.
func (*UserState) FindUserByConfirmationCode ¶
FindUserByConfirmationCode can find the corresponding username in the list of unconfirmed users, given a unique confirmation code.
func (*UserState) GenerateUniqueConfirmationCode ¶
GenerateUniqueConfirmationCode will generate a unique confirmation code that can be used for confirming users after users have registered.
func (*UserState) HasEmail ¶
HasEmail finds the user that has a given e-mail address. Returns the username and nil if found or a blank string and ErrNotFound if not.
func (*UserState) HashPassword ¶
HashPassword will hash the password (takes a username as well, it can be used for salting when using sha256).
func (*UserState) Host ¶
func (state *UserState) Host() pinterface.IHost
Host gets the Host (for qualifying for the IUserState interface)
func (*UserState) IsConfirmed ¶
IsConfirmed checks if the given username is confirmed.
func (*UserState) IsLoggedIn ¶
IsLoggedIn checks if the given username is logged in.
func (*UserState) Login ¶
func (state *UserState) Login(w http.ResponseWriter, username string) error
Login is a convenience function for logging a user in and storing the username in a cookie. Returns an error if the cookie could not be set.
func (*UserState) Logout ¶
Logout is a convenience function for logging a user out. This is the same as SetLoggedOut.
func (*UserState) MarkConfirmed ¶
MarkConfirmed can mark a user as confirmed.
func (*UserState) PasswordAlgo ¶
PasswordAlgo gets the current password hashing algorithm.
func (*UserState) PasswordHash ¶
PasswordHash returns the password hash for the given username.
func (*UserState) Pool ¶
func (state *UserState) Pool() *simpleredis.ConnectionPool
Pool gets the Redis connection pool.
func (*UserState) Properties ¶
Properties returns a list of user properties. Returns an empty list if the user has no properties, or if there are errors.
func (*UserState) RemoveAdminStatus ¶
RemoveAdminStatus can remove administrator status from a user.
func (*UserState) RemoveToken ¶
RemoveToken takes a username and removes the associated token.
func (*UserState) RemoveUnconfirmed ¶
RemoveUnconfirmed removes a user that is registered but not confirmed.
func (*UserState) RemoveUser ¶
RemoveUser removes user and login status.
func (*UserState) SetAdminStatus ¶
SetAdminStatus can make a user an administrator.
func (*UserState) SetBooleanField ¶
SetBooleanField can store a boolean value for the given username and custom fieldname.
func (*UserState) SetCookieSecret ¶
SetCookieSecret will set the secret that is used when generating secure cookies.
func (*UserState) SetCookieTimeout ¶
SetCookieTimeout will set how long a login cookie should last, in seconds.
func (*UserState) SetLoggedIn ¶
SetLoggedIn will mark the user as logged in. Use the Login function instead, unless cookies are not involved.
func (*UserState) SetLoggedOut ¶
SetLoggedOut will mark the user as logged out.
func (*UserState) SetMinimumConfirmationCodeLength ¶
SetMinimumConfirmationCodeLength will set the minimum length of the user confirmation code. The default is 20.
func (*UserState) SetPassword ¶
SetPassword sets the password for a user. The given password string will be hashed. No validation or check of the given password is performed.
func (*UserState) SetPasswordAlgo ¶
SetPasswordAlgo can set the password hashing algorithm that should be used. The default is "bcrypt+". Possible values are:
bcrypt -> Store and check passwords with the bcrypt hash. sha256 -> Store and check passwords with the sha256 hash. bcrypt+ -> Store passwords with bcrypt, but check with both bcrypt and sha256, for backwards compatibility with old passwords that has been stored as sha256.
func (*UserState) SetUsernameCookie ¶
func (state *UserState) SetUsernameCookie(w http.ResponseWriter, username string) error
SetUsernameCookie tries to store the given username in a cookie in the browser.
* * The user must exist. Returns an error if the username is empty or does not exist. * Returns nil if the cookie has been attempted to be set. * To check if the cookie has actually been set, one must try to read it.
func (*UserState) SetUsernameCookieOnlyHTTPS ¶
func (state *UserState) SetUsernameCookieOnlyHTTPS(w http.ResponseWriter, username string) error
SetUsernameCookieOnlyHTTPS tries to store the given username in a cookie in the browser.
- This function will not set the cookie if over plain HTTP. *
- The user must exist. Returns an error if the username is empty or does not exist.
- Returns nil if the cookie has been attempted to be set.
- To check if the cookie has actually been set, one must try to read it.
func (*UserState) UserRights ¶
UserRights checks if the current user is logged in and has user rights.
func (*UserState) Username ¶
Username is a convenience function that will return a username (from the browser cookie) or an empty string.
func (*UserState) UsernameCookie ¶
UsernameCookie retrieves the username that is stored in a cookie in the browser, if available.
func (*UserState) Users ¶
func (state *UserState) Users() pinterface.IHashMap
Users gets the users HashMap.