README
¶
htpasswd for Go
This is a libary to validate user credentials against an HTTPasswd file.
This was forked from https://github.com/jimstudt/http-authentication/tree/master/basic with modifications by @brian-avery to support SSHA, Md5Crypt, and Bcrypt and @jespersoderlund to support Crypt with SHA-256 and SHA-512 support.
Currently, this supports:
- SSHA
- MD5Crypt
- APR1Crypt
- SHA
- Bcrypt
- Plain text
- Crypt with SHA-256 and SHA-512
Documentation
¶
Overview ¶
Package htpasswd groups provides an autorisation mechanism using Apache-style group files.
An Apache group file looks like this: users: user1 user2 user3 admins: user1
Basic usage of this package:
userGroups, groupLoadErr := htgroup.NewGroups("./my-group-file", nil) ok := userGroups.IsUserInGroup(username, "admins")
Package htpasswd provides HTTP Basic Authentication using Apache-style htpasswd files for the user and password data.
It supports most common hashing systems used over the decades and can be easily extended by the programmer to support others. (See the sha.go source file as a guide.)
You will want to use something like...
myauth := htpasswd.New("./my-htpasswd-file", htpasswd.DefaultSystems, nil)
ok := myauth.Match(user, password)
...to use in your handler code. You should read about that nil, as well as Reread() too.
Index ¶
- Constants
- Variables
- type BadLineHandler
- type EncodedPasswd
- func AcceptBcrypt(src string) (EncodedPasswd, error)
- func AcceptCryptSha(src string) (EncodedPasswd, error)
- func AcceptMd5(src string) (EncodedPasswd, error)
- func AcceptPlain(pw string) (EncodedPasswd, error)
- func AcceptSha(src string) (EncodedPasswd, error)
- func AcceptSsha(src string) (EncodedPasswd, error)
- func RejectBcrypt(src string) (EncodedPasswd, error)
- func RejectCryptSha(src string) (EncodedPasswd, error)
- func RejectMd5(src string) (EncodedPasswd, error)
- func RejectPlain(pw string) (EncodedPasswd, error)
- func RejectSha(src string) (EncodedPasswd, error)
- func RejectSsha(src string) (EncodedPasswd, error)
- type File
- type HTGroup
- type PasswdParser
Constants ¶
const PrefixCryptApr1 = "$apr1$"
PrefixCryptApr1 is the Apache Apr1 hash prefix
const PrefixCryptMd5 = "$1$"
PrefixCryptMd5 is the Md5crypt hash prefix
const PrefixCryptSha256 = "$5$"
Prefixes
const PrefixCryptSha512 = "$6$"
const Separator = "$"
Variables ¶
var DefaultSystems = []PasswdParser{AcceptMd5, AcceptSha, AcceptBcrypt, AcceptSsha, AcceptCryptSha, AcceptPlain}
DefaultSystems is an array of PasswdParser including all builtin parsers. Notice that Plain is last, since it accepts anything
Functions ¶
This section is empty.
Types ¶
type BadLineHandler ¶
type BadLineHandler func(err error)
A BadLineHandler is used to notice bad lines in a password file. If not nil, it will be called for each bad line with a descriptive error. Think about what you do with these, they will sometimes contain hashed passwords.
type EncodedPasswd ¶
type EncodedPasswd interface {
// Return true if the string matches the password.
// This may cache the result in the case of expensive comparison functions.
MatchesPassword(pw string) bool
}
An EncodedPasswd is created from the encoded password in a password file by a PasswdParser.
The password files consist of lines like "user:passwd-encoding". The user part is stripped off and the passwd-encoding part is captured in an EncodedPasswd.
func AcceptBcrypt ¶
func AcceptBcrypt(src string) (EncodedPasswd, error)
AcceptBcrypt accepts any valid password encoded using bcrypt.
func AcceptCryptSha ¶ added in v1.1.0
func AcceptCryptSha(src string) (EncodedPasswd, error)
Accepts valid passwords
func AcceptMd5 ¶
func AcceptMd5(src string) (EncodedPasswd, error)
AcceptMd5 accepts valid MD5 encoded passwords
func AcceptPlain ¶
func AcceptPlain(pw string) (EncodedPasswd, error)
AcceptPlain accepts any password in the plain text encoding. Be careful: This matches any line, so it *must* be the last parser in you list.
func AcceptSha ¶
func AcceptSha(src string) (EncodedPasswd, error)
AcceptSha accepts valid SHA encoded passwords.
func AcceptSsha ¶
func AcceptSsha(src string) (EncodedPasswd, error)
AcceptSsha accepts any valid password encoded using bcrypt.
func RejectBcrypt ¶
func RejectBcrypt(src string) (EncodedPasswd, error)
RejectBcrypt rejects any password encoded using bcrypt.
func RejectCryptSha ¶ added in v1.1.0
func RejectCryptSha(src string) (EncodedPasswd, error)
RejectCryptSha known indexes
func RejectMd5 ¶
func RejectMd5(src string) (EncodedPasswd, error)
RejectMd5 rejects any MD5 encoded password
func RejectPlain ¶
func RejectPlain(pw string) (EncodedPasswd, error)
RejectPlain rejects any plain text encoded password. Be careful: This matches any line, so it *must* be the last parser in you list.
func RejectSha ¶
func RejectSha(src string) (EncodedPasswd, error)
RejectSha rejects any password encoded as SHA.
func RejectSsha ¶
func RejectSsha(src string) (EncodedPasswd, error)
RejectSsha rejects any password encoded using SSHA1.
type File ¶
type File struct {
// contains filtered or unexported fields
}
An File encompasses an Apache-style htpasswd file for HTTP Basic authentication
func New ¶
func New(filename string, parsers []PasswdParser, bad BadLineHandler) (*File, error)
New creates an File from an Apache-style htpasswd file for HTTP Basic Authentication.
The realm is presented to the user in the login dialog.
The filename must exist and be accessible to the process, as well as being a valid htpasswd file.
parsers is a list of functions to handle various hashing systems. In practice you will probably just pass htpasswd.DefaultSystems, but you could make your own to explicitly reject some formats or implement your own.
bad is a function, which if not nil will be called for each malformed or rejected entry in the password file.
func NewFromReader ¶
func NewFromReader(r io.Reader, parsers []PasswdParser, bad BadLineHandler) (*File, error)
NewFromReader is like new but reads from r instead of a named file. Calling Reload on the returned File will result in an error; use ReloadFromReader instead.
func (*File) Match ¶
Match checks the username and password combination to see if it represents a valid account from the htpassword file.
func (*File) Reload ¶
func (bf *File) Reload(bad BadLineHandler) error
Reload rereads the htpassword file.. You will need to call this to notice any changes to the password file. This function is thread safe. Someone versed in fsnotify might make it happen automatically. Likewise you might also connect a SIGHUP handler to this function.
func (*File) ReloadFromReader ¶
func (bf *File) ReloadFromReader(r io.Reader, bad BadLineHandler) error
ReloadFromReader is like Reload but reads credentials from r instead of a named file. If File was created by New, it is okay to call Reload and ReloadFromReader as desired.
type HTGroup ¶ added in v1.2.0
type HTGroup struct {
// contains filtered or unexported fields
}
A HTGroup encompasses an Apache-style group file.
func NewGroups ¶ added in v1.2.0
func NewGroups(filename string, bad BadLineHandler) (*HTGroup, error)
NewGroups creates a HTGroup from an Apache-style group file.
The filename must exist and be accessible to the process, as well as being a valid group file.
bad is a function, which if not nil will be called for each malformed or rejected entry in the group file.
func NewGroupsFromReader ¶ added in v1.2.0
func NewGroupsFromReader(r io.Reader, bad BadLineHandler) (*HTGroup, error)
NewGroupsFromReader is like NewGroups but reads from r instead of a named file.
func (*HTGroup) GetUserGroups ¶ added in v1.2.0
GetUserGroups reads all groups of a user. Returns all groups as a string array or an empty array.
func (*HTGroup) IsUserInGroup ¶ added in v1.2.0
IsUserInGroup checks whether the user is in a group. Returns true of user is in that group, otherwise false.
func (*HTGroup) ReloadGroups ¶ added in v1.2.0
func (htGroup *HTGroup) ReloadGroups(bad BadLineHandler) error
ReloadGroups rereads the group file.
func (*HTGroup) ReloadGroupsFromReader ¶ added in v1.2.0
func (htGroup *HTGroup) ReloadGroupsFromReader(r io.Reader, bad BadLineHandler) error
ReloadGroupsFromReader rereads the group file from a Reader.
type PasswdParser ¶
type PasswdParser func(pw string) (EncodedPasswd, error)
PasswdParser examines an encoded password, and if it is formatted correctly and sane, return an EncodedPasswd which will recognize it.
If the format is not understood, then return nil so that another parser may have a chance. If the format is understood but not sane, return an error to prevent other formats from possibly claiming it
You may write and supply one of these functions to support a format (e.g. bcrypt) not already included in this package. Use sha.c as a template, it is simple but not too simple.
Source Files