auth

Documentation

Overview

Package auth provides common types and functions for aiding in authentication within Juju. Currently this package provides our password logic for hashing and encapsulating plain text passwords.

When a component in Juju receives a plain text password from a user it should be immediately wrapped in a Password type with NewPassword("mypassword").

To hash a new password for Juju to persist the first step is to generate a new password salt with NewSalt(). This newly created salt value must follow the users password for the life of the password.

Passwords can be hashed with HashPassword(password, salt). The resultant hash is now safe for storing in Juju along with the created salt.

Index

• Constants
• func HashPassword(p Password, salt []byte) (string, error)
• func NewSalt() ([]byte, error)
• type Password
  • func NewPassword(p string) Password
  • func (p Password) Destroy()
  • func (p Password) Format(f fmt.State, verb rune)
  • func (p Password) GoString() string
  • func (p Password) IsDestroyed() bool
  • func (p Password) String() string
  • func (p Password) Validate() error

Examples

• HashPassword

Constants

const (
	// ErrPasswordDestroyed is used when a password has been destroyed and the
	// operation cannot be performed.
	ErrPasswordDestroyed = errors.ConstError("password destroyed")

	// ErrPasswordNotValid is used when a password has failed validation.
	ErrPasswordNotValid = errors.ConstError("password not valid")
)

Functions

func HashPassword

func HashPassword(p Password, salt []byte) (string, error)

HashPassword takes a password and corresponding salt to produce a hash of the password. The resultant hash is safe for persistence and comparison. If the salt provided to password hash is empty then a error satisfying errors.NotValid is returned. If the password does not pass validation a error satisfying ErrPasswordNotValid will be returned. If the password has been destroyed a error satisfying ErrPasswordDestroyed will be returned.

HashPassword under all circumstances will Destroy() the password provided to the function rendering it unusable.

Example

userExposedPassword := "topsecret"

password := NewPassword(userExposedPassword)
salt, err := NewSalt()
if err != nil {
	log.Fatalf("generating password salt: %v", salt)
}

hash, err := HashPassword(password, salt)
if err != nil {
	log.Fatalf("generating password hash with salt: %v", err)
}

fmt.Println(hash)

func NewSalt

func NewSalt() ([]byte, error)

NewSalt generates a new random password salt for use with password hashing.

Types

type Password

type Password struct {
	// contains filtered or unexported fields
}

Password hides and protects a plain text passwords in Juju from accidentally being consumed or printed to a log.

func NewPassword

func NewPassword(p string) Password

NewPassword returns a Password struct wrapping the plain text password.

func (Password) Destroy

func (p Password) Destroy()

Destroy will invalidate the memory being used to store the password. Destroy() can be called multiple times safely.

func (Password) Format

func (p Password) Format(f fmt.State, verb rune)

Format implements the Formatter interface from fmt making sure not to output the encapsulated password.

func (Password) GoString

func (p Password) GoString() string

GoString implements the GoStringer interface from fmt making sure not to output the encapsulated password.

func (Password) IsDestroyed

func (p Password) IsDestroyed() bool

IsDestroyed reports if the password has been destroyed or not.

func (Password) String

func (p Password) String() string

String implements the stringer interface always returning an empty string and never the encapsulated password.

func (Password) Validate

func (p Password) Validate() error

Validate will check the wrapped password to make sure that it meets our validation requirements. Passwords must not be empty and less than 1KB in size. All validation errors will satisfy ErrPasswordNotValid. If the password has been destroyed a error of type ErrPasswordDestroyed will be returned.