passlist

README

PassList

Purpose

Sometimes there is a need to password-protect your web-server, either in whole or just some parts of it. That's were this little package comes in. It offers to simply integrate the popular BasicAuth mechanism into your own web-server.

Installation

You can use Go to install this package for you:

go get -u github.com/mwat56/go-passlist

Usage

PassList provides an easy way to handle HTTP Basic Authentication by simply calling the package's Wrap() function and implementing the TAuthDecider interface which only requires the single function or method

NeedAuthentication(aRequest *http.Request) bool

That function may decide on whatever means whether to grant access (returning true)) or deny it (returning false). For your ease there are two TAuthDecider implementations provided: TAuthSkipper (which generally returns false) and TAuthSkipper (which generally returns true). Just instanciate one of those – or, of course, your own implementation – and pass it to the Wrap() function.

func Wrap(aHandler http.Handler, aRealm, aPasswdFile string, aAuthDecider TAuthDecider) http.Handler

The arguments mean:

• aHandler: the HTTP handler you implemented for your web-server; you will use the return value of Wrap() after you called this function.

• aRealm: the name of the host/domain to protect (this can be any string you like); it will be shown by most browsers when the username/password is requested.

• aPasswdFile: the name of the password file that holds all the username/password pairs to use when authentication is actually required.

• aAuthDecider: the deciding function we talked about above.

So, in short: implement the TAuthDecider interface and call passlist.Wrap(…), and you're done.

However, the package provides a TPassList class with lots of methods to works with a username/password list. It's fairly well documented, so it shouldn't be too hard to use it on your own if you don't like the automatic handling provided by Wrap(). You can create a new instance by either calling passlist.LoadPasswords(aFilename string) (which, as it's name says, tries to load the given password file at once), or you call passlist.NewList(aFilename string) (which leaves it to you when to actually read the password file by calling the TPassList object's Load() method).

There's an additional convenience function called passlist.Deny() which sends an "Unauthorised" notice to the remote host in case the remote user couldn't be authenticated; this function is called internally whenever your TAuthDecider required authentication and wasn't given valid credentials from the remote user.

Please refer to the source code documentation for further details ot the TPassList class.

In the package's _demo folder you'll find the pwaccess.go program which implements the maintainance of password files with the following options:

-add string
    <username> name of the user to add to the file (prompting for the password)
-chk string
    <username> name of the user whose pass to check (prompting for the password)
-del string
    <username> name of the user to remove from the file
-file string
    <filename> name of the passwordfile to use (default "pwaccess.db")
-lst
    list all current usernames from the list
-q    whether to be quiet or not (suppress non-essential messages)
-upd string
    <username> name of the user to update in the file (prompting for the password)

Note: To be on the safe side your web-server schould use HTTPS instead of plain old HTTP to avoid the chance of someone eavesdropping on the username/password exchange.

Licence

Copyright © 2019  M.Watermann, 10247 Berlin, Germany
                All rights reserved
            EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the GNU General Public License for details.

Documentation

Overview

Package passlist provides BasicAuth for Go web-servers.

Copyright © 2019 M.Watermann, 10247 Berlin, Germany
                All rights reserved
            EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the [GNU General Public License](http://www.gnu.org/licenses/gpl.html) for details.

Index

• func Deny(aRealm string, aWriter http.ResponseWriter)
• func Wrap(aHandler http.Handler, aRealm, aPasswdFile string, aAuthDecider TAuthDecider) http.Handler
• type TAuthDecider
• type TAuthNeeder
  • func (ad TAuthNeeder) NeedAuthentication(aRequest *http.Request) bool
• type TAuthSkipper
  • func (ad TAuthSkipper) NeedAuthentication(aRequest *http.Request) bool
• type TPassList
  • func LoadPasswords(aFilename string) (*TPassList, error)
  • func NewList(aFilename string) (rList *TPassList)
  • func (ul *TPassList) Add(aUser, aPassword string) error
  • func (ul *TPassList) Clear() *TPassList
  • func (ul *TPassList) Exists(aUser string) (rOK bool)
  • func (ul *TPassList) Find(aUser string) (rHash string, rOK bool)
  • func (ul *TPassList) IsAuthenticated(aRequest *http.Request) bool
  • func (ul *TPassList) Len() int
  • func (ul *TPassList) List() (rList []string)
  • func (ul *TPassList) Load() error
  • func (ul *TPassList) Matches(aUser, aPassword string) (rOK bool)
  • func (ul *TPassList) Remove(aUser string) *TPassList
  • func (ul *TPassList) Store() (int, error)
  • func (ul *TPassList) String() string

Functions

func Deny

func Deny(aRealm string, aWriter http.ResponseWriter)

Deny sends an "Unauthorised" notice to the remote host.

`aRealm` is the symbolic name of the host/domain to protect.

`aWriter` is used by an HTTP handler to construct an HTTP response.

func Wrap

func Wrap(aHandler http.Handler, aRealm, aPasswdFile string, aAuthDecider TAuthDecider) http.Handler

Wrap returns a handler function that includes authentication, wrapping the given `aHandler` and calling it internally.

`aHandler` responds to the actual HTTP request; this is the handler to be called after successful authentication.

`aRealm` is the symbolic name of the domain/host to protect.

`aPasswdFile` is the name of the password file to use.

Types

type TAuthDecider

type TAuthDecider interface {
	// NeedAuthentication returns `true` if authentication is needed,
	// or `false` otherwise.
	//
	// `aRequest` holds the URL to check.
	NeedAuthentication(aRequest *http.Request) bool
}

TAuthDecider is an interface deciding whether a given URL needs authentication or not.

type TAuthNeeder

type TAuthNeeder bool

TAuthNeeder provides a `TAuthDecider` implementation always returning `true`.

func (TAuthNeeder) NeedAuthentication

func (ad TAuthNeeder) NeedAuthentication(aRequest *http.Request) bool

NeedAuthentication returns `true` thus requiring authentication for any URL.

type TAuthSkipper

type TAuthSkipper bool

TAuthSkipper provides a `TAuthDecider` implementation always returning `false`.

func (TAuthSkipper) NeedAuthentication

func (ad TAuthSkipper) NeedAuthentication(aRequest *http.Request) bool

NeedAuthentication returns `false` thus skipping any authentication.

type TPassList

type TPassList tPassList

TPassList holds the list of username/password values.

func LoadPasswords

func LoadPasswords(aFilename string) (*TPassList, error)

LoadPasswords reads the given `aFilename` returning a `TUserList` instance filled with data read from the password file and a possible error condition.

This function reads one line at a time of the password file skipping both empty lines and comments (identified by `#` or `;` at line start).

`aFilename` is the name of the password file to read.

func NewList

func NewList(aFilename string) (rList *TPassList)

NewList returns a new `TUserList` instance.

`aFilename` is the name of the password file to use for `Load()` and `Store()`

func (*TPassList) Add

func (ul *TPassList) Add(aUser, aPassword string) error

Add inserts `aUser` with `aPassword` into the list.

Before storing `aPassword` it gets hashed.

`aUser` is the username to use.

`aPassword` is the user's password to store.

func (*TPassList) Clear

func (ul *TPassList) Clear() *TPassList

Clear empties the internal data structure.

func (*TPassList) Exists

func (ul *TPassList) Exists(aUser string) (rOK bool)

Exists returns `true` if `aUser` exists in the list, or `false` if not found.

`aUser` is the username to lookup.

func (*TPassList) Find

func (ul *TPassList) Find(aUser string) (rHash string, rOK bool)

Find returns the hashed password of `aUser` and `true`, or an empty string and `false` if not found.

`aUser` is the username to lookup.

func (*TPassList) IsAuthenticated

func (ul *TPassList) IsAuthenticated(aRequest *http.Request) bool

IsAuthenticated checks `aRequest` for authentication data, returning `true` for successful authentication, or `false` otherwise.

On success the username/password are stored in the `aRequest.URL.User` structure to allow for other handlers checking its existence and act accordingly.

`aRequest` is an HTTP request received by a server.

func (*TPassList) Len

func (ul *TPassList) Len() int

Len returns the actual length of the userlist.

func (*TPassList) List

func (ul *TPassList) List() (rList []string)

List returns a list of all usernames in the list.

func (*TPassList) Load

func (ul *TPassList) Load() error

Load reads the password file named in `LoadPasswords()` or `NewList()` replacing any older list's contents with the file's.

func (*TPassList) Matches

func (ul *TPassList) Matches(aUser, aPassword string) (rOK bool)

Matches checks whether `aPassword` of `aUser` matches the stored password.

`aUser` the username to lookup.

`aPassword` the (unhashed) password to check.

func (*TPassList) Remove

func (ul *TPassList) Remove(aUser string) *TPassList

Remove deletes `aUser` from the list.

`aUser` is the username to remove.

func (*TPassList) Store

func (ul *TPassList) Store() (int, error)

Store writes the list to `aFilename`, truncating the file if it already exists.

The method returns the number of bytes written and an error, if any.

func (*TPassList) String

func (ul *TPassList) String() string

String returns the list as a single string.