README
¶
auth/htpasswd 
Authenticate using Apache-style htpasswd files and HTTP Basic Authentication.
htpasswd has supported a number of different password hashing schemes over the
decades. Most common and sane ones are supported directly. For some you will need
to add another package.
| Style | Status |
|---|---|
| plain | yes+ |
| md5 | yes |
| sha | yes |
| crypt | no (conflicts with plain) |
| bcrypt | no (can add with another package) |
The standard set of systems will use Plain, Sha, and MD5 systems while filtering out bcrypt. Because of its complexity, bcrypt will be in another package which you can import and add if you need it. Plain accepts both Apache style plain text and nginx style where the password is preceded by {PLAIN}.
Usage
import (
"github.com/codegangsta/martini"
"github.com/jimstudt/http-authentication/basic"
"log"
)
func main() {
m := martini.Classic()
pw,err := basic.New("My Realm", "./my-htpasswd-file", htpasswd.DefaultSystems, nil)
if ( err != nil) {
log.Fatalf("Unable to read my htpassword file: %s", err.Error())
}
// authenticate every request
m.Use( pw.ServeHTTP)
// You will also want to call pw.Reload(nil) to reprocess the password file when it changes.
// You can use pw.ReloadOn( syscall.SIGHUP, nil ) to make it automatically
// reload on a HUP signal.
// And those 'nil' arguments are where you pass a function to be notified about illegally
// formatted entries, or unsupported hash systems. See the API documents.
// If you only want to authenticate some requests, then it goes like this...
// m.Get("/secure/thing", pw.ServeHTTP, myRealHandler)
// ... if pw.ServeHTTP does the 401 then your handler will not be called
m.Run()
}
API Documentation
The API is documented using godoc and also available at godoc.org
Documentation
¶
Overview ¶
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 Realm", "./my-htpasswd-file", htpasswd.DefaultSystems, nil)
m.Use(myauth.Handler)
...to configure your authentication and then use the myauth.Handler as a middleware handler in your Martini stack. You should read about that nil, as well as Reread() too.
Index ¶
- Variables
- type BadLineHandler
- type EncodedPasswd
- func AcceptMd5(src string) (EncodedPasswd, error)
- func AcceptPlain(pw string) (EncodedPasswd, error)
- func AcceptSha(src string) (EncodedPasswd, error)
- func RejectBcrypt(src string) (EncodedPasswd, error)
- func RejectMd5(src string) (EncodedPasswd, error)
- func RejectPlain(pw string) (EncodedPasswd, error)
- func RejectSha(src string) (EncodedPasswd, error)
- type HtpasswdFile
- type PasswdParser
Constants ¶
This section is empty.
Variables ¶
var DefaultSystems []PasswdParser = []PasswdParser{AcceptMd5, AcceptSha, RejectBcrypt, AcceptPlain}
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 AcceptMd5 ¶
func AcceptMd5(src string) (EncodedPasswd, error)
Accept valid MD5 encoded passwords
func AcceptPlain ¶
func AcceptPlain(pw string) (EncodedPasswd, error)
Accept 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)
Accept valid SHA encoded passwords.
func RejectBcrypt ¶
func RejectBcrypt(src string) (EncodedPasswd, error)
Reject any password encoded using bcrypt.
func RejectPlain ¶
func RejectPlain(pw string) (EncodedPasswd, error)
Reject any plain text encoded passoword. Be careful: This matches any line, so it *must* be the last parser in you list.
func RejectSha ¶
func RejectSha(src string) (EncodedPasswd, error)
Reject any password encoded as SHA.
type HtpasswdFile ¶
type HtpasswdFile struct {
// contains filtered or unexported fields
}
An HtpasswdFile encompasses an Apache-style htpasswd file for HTTP Basic authentication
func New ¶
func New(realm string, filename string, parsers []PasswdParser, bad BadLineHandler) (*HtpasswdFile, error)
New creates an HtpasswdFile 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 (*HtpasswdFile) Reload ¶
func (bf *HtpasswdFile) Reload(bad BadLineHandler) error
Reread the password file for this HtpasswdFile. 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 (*HtpasswdFile) ReloadOn ¶
func (bf *HtpasswdFile) ReloadOn(when os.Signal, onbad BadLineHandler)
Reload the htpasswd file on a signal. If there is an error, the old data will be kept instead. Typically you would use syscall.SIGHUP for the value of "when"
func (*HtpasswdFile) ServeHTTP ¶
func (bf *HtpasswdFile) ServeHTTP(res http.ResponseWriter, req *http.Request)
A Martini middleware handler to enforce HTTP Basic Auth using the policy read from the htpasswd file.
type PasswdParser ¶
type PasswdParser func(pw string) (EncodedPasswd, error)
Examine 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