Documentation ¶
Overview ¶
Package auth contains one-time password authentication functionality for implementing authentication in a system design. An Authenticator contains authentication information, presumably for a user; the authentication token or password submitted by the user can be validated using the Validate function.
This package currently supports password authentication (using bcrypt hashes), YubiKey OTPs, Google Authenticator standard TOTPs, and a basic session implementation.
Index ¶
- Constants
- Variables
- func NewGoogleTOTP(label string) (*Authenticator, *UserTOTP, error)
- func Validate(auth *Authenticator, password string) (needsUpdate bool, err error)
- func ValidatePassword(auth *Authenticator, password string) (bool, error)
- func ValidateSession(auth *Authenticator, otp string) (bool, error)
- func ValidateTOTP(auth *Authenticator, otp string) (bool, error)
- func ValidateYubiKey(auth *Authenticator, otp string) (bool, error)
- type Authenticator
- type Session
- type TOTPConfig
- type UserTOTP
- type YubiKeyConfig
Constants ¶
const TypePassword = "password"
TypePassword is a bcrypted password hash.
const TypeSession = "session"
TypeSession is a new session.
const TypeTOTP = "TOTP"
TypeTOTP is a TOTP token.
const TypeYubiKey = "yubikey"
TypeYubiKey is a YubiOTP token.
Variables ¶
var ( // ErrInvalidAuthenticator indicates that the authenticator // passed to Validate is not a valid authenticator. Ensure // that it is a type supported by the server, and that it is // an actual value. ErrInvalidAuthenticator = errors.New("auth: invalid authenticator") // ErrInvalidOTP indicates that an OTP is invalid for the // Authenticator. ErrValidationFail = errors.New("auth: authentication failed") )
var ( // ErrUnsupportedHash is returned when the user tries to use a // hash algorithm that isn't supported by the authentication scheme. ErrUnsupportedHash = errors.New("auth: unsupported hash algorithm") )
var TOTPProvider string
TOTPProvider contains the value that should be used to fill in the Provider field of the TOTPConfig.
var Validators = map[string]func(*Authenticator, string) (bool, error){ TypeYubiKey: ValidateYubiKey, TypeTOTP: ValidateTOTP, TypeSession: ValidateSession, TypePassword: ValidatePassword, }
Validators contains a mapping of authenticator types to validation functions.
Functions ¶
func NewGoogleTOTP ¶
func NewGoogleTOTP(label string) (*Authenticator, *UserTOTP, error)
NewGoogleTOTP generates a new Google-authenticator standard TOTP token.
func Validate ¶
func Validate(auth *Authenticator, password string) (needsUpdate bool, err error)
Validate takes an Authenticator and an OTP, and checks whether the OTP is valid. It returns a boolean value indicating whether the Authenticator needs to be validated (i.e., if it contains a counter, and therefore the counter value needs to be stored).
func ValidatePassword ¶
func ValidatePassword(auth *Authenticator, password string) (bool, error)
ValidatePassword takes an Authenticator that is presumed to be a bcrypted password hash and a password, and ensures that it matches.
func ValidateSession ¶
func ValidateSession(auth *Authenticator, otp string) (bool, error)
ValidateSession ensures that the OTP provided contains the next value and the appropriate HMAC for the session.
func ValidateTOTP ¶
func ValidateTOTP(auth *Authenticator, otp string) (bool, error)
ValidateTOTP takes an Authenticator that is presumed to be a TOTP authenticator and attempts to validate the given OTP using it. The TOTP authenticator will always need to be updated when successful to account for an updated last OTP.
func ValidateYubiKey ¶
func ValidateYubiKey(auth *Authenticator, otp string) (bool, error)
ValidateYubiKey takes an Authenticator that is presumed to be a YubiKey authenticator and attempts to validate the given OTP using it. The YubiKey authenticator will always need to be updated when successful to account for changes in the counter, and to update the last OTP.
Types ¶
type Authenticator ¶
type Authenticator struct { Type string `json:"type"` Label string `json:"label"` Last string `json:"last"` Secret []byte `json:"secret"` }
An Authenticator stores a one-time password key for a user. The type is used to select the appropriate verification algorithm.
func ImportGoogleTOTP ¶
func ImportGoogleTOTP(key []byte) (*Authenticator, error)
ImportGoogleTOTP creates a new Google-authenticator standard TOTP from an existing key.
func NewPasswordAuth ¶
func NewPasswordAuth(password string, cost int) (*Authenticator, error)
NewPasswordAuth creates a bcrypt hash authenticator for the password using the given cost, which must be between 8 and 31. If the cost is an invalid value, a default cost will be used.
func NewSession ¶
func NewSession(pub []byte) (*Authenticator, []byte, error)
NewSession sets up a new session. The Last field should be sent to the client. The returned public key should be sent to the user for generating a shared MAC key. The authenticator should ensure some mechanism for expiring sessions exists.
func NewYubiKey ¶
func NewYubiKey(key []byte, initialOTP string) (*Authenticator, error)
NewYubiKey takes the key and initial OTP and returns an authenticator.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
A Session is meant to be used by an authenticatee for computing the checksums.
func KeySession ¶
KeySession sets up a new session from the user's private key and the server's ephemeral public key.
type TOTPConfig ¶
type TOTPConfig struct { // Key is used as the HMAC key for generating OTPs. This should // be the same length as the hash algorithm's output size, but // not everyone does that. Key []byte // Start is the start time for the TOTP. Google defaults this to // the start of the epoch. Start uint64 // Step is the time step between OTPs. Users will not be able // to authenticate inside this time period after the first // successful authentication to prevent replay attacks. Google // defaults to 30 seconds for this. Step uint64 // Size is the number of digits to generate. Google defaults // to six. Size int // Algo contains the hash algorithm used in the HMAC. Google // defaults to SHA1. Algo crypto.Hash // Provider is an optional string that identifies the // authentication provider. This is used in generating QR codes. Provider string }
TOTPConfig contains the details required to use a TOTP token.
func ParseTOTPConfig ¶
func ParseTOTPConfig(in []byte) (*TOTPConfig, error)
ParseTOTPConfig parses a serialised TOTP configuration.
func (*TOTPConfig) Bytes ¶
func (config *TOTPConfig) Bytes() ([]byte, error)
Bytes exports the TOTP configuration as a byte slice.
func (*TOTPConfig) ExportKey ¶
func (config *TOTPConfig) ExportKey() string
ExportKey returns the base32-encoded key for the TOTP to hand off to the user.
type UserTOTP ¶
type UserTOTP struct { Secret string // The TOTP secret, base32-encoded. QR []byte // A QR code that may be used to import the token. }
UserTOTP contains the data a user needs to import the TOTP token in their TOTP app of choice.
func ExportUserTOTP ¶
func ExportUserTOTP(auth *Authenticator, label string) (*UserTOTP, error)
ExportUserTOTP returns a UserTOTP value suitable for handing off to a user. If a label is provided, a QR code will be returned.
type YubiKeyConfig ¶
YubiKeyConfig contains the token and key information for a YubiKey.
func ParseYubiKeyConfig ¶
func ParseYubiKeyConfig(in []byte) (*YubiKeyConfig, error)
ParseYubiKeyConfig attempts to parse a YubiKeyConfig from a byte slice.
func (*YubiKeyConfig) Bytes ¶
func (config *YubiKeyConfig) Bytes() []byte
Bytes returns a byte slice representation of the YubiKeyConfig.