password

Documentation

Overview

Package password : The password package provides implementation of Password services: Encryption, salting, reset, time expiration and throttling.

The password package handles the following:

• Generating a new (salted) password,
• Checking if a given password matches a given user's password
• Updating a user's password
• Resetting a password to a password that can only be used once within a predifined window of time

Passwords have the following properties:

• The current password
• The password's expiration time
• Old passwords that should be avoided. If there is an attempt to reused an old the user is flagged.
• Error counter: counts the number of consecutive unsuccessful authentication attempts
• Is it a 'temporary password' (after password reset)

Note that users are also flagged if they attempt to use a one-time-passwords more than once

Index

• Constants
• func CheckPasswordStrength(pass string) error
• func GenerateNewValidPassword() []byte
• func GetHashedPwd(pwd []byte) []byte
• type Serializer
  • func (s Serializer) AddToStorage(prefix string, data interface{}, storage *ss.SecureStorage) error
  • func (s Serializer) IsEqualProperties(da1 interface{}, da2 interface{}) bool
  • func (s Serializer) PrintProperties(data interface{}) string
  • func (s Serializer) ReadFromStorage(key string, storage *ss.SecureStorage) (interface{}, error)
• type UserPwd
  • func NewUserPwd(pwd []byte, saltData []byte, checkPwdStrength bool) (*UserPwd, error)
  • func (u UserPwd) IsNewPwdValid(pwd []byte, checkPwdStrength bool) error
  • func (u *UserPwd) IsPasswordMatch(pwd []byte) error
  • func (u *UserPwd) ResetPasword() ([]byte, error)
  • func (u *UserPwd) SetTemporaryPwd(flag bool)
  • func (u UserPwd) String() string
  • func (u *UserPwd) UpdatePassword(currentPwd []byte, pwd []byte, checkPwdStrength bool) ([]byte, error)
  • func (u *UserPwd) UpdatePasswordAfterReset(currentPwd []byte, pwd []byte, expiration time.Time) ([]byte, error)

Examples

• UserPwd
• UserPwd.ResetPasword

Constants

const (
	MinPasswordLength = 8
	MaxPasswordLength = 256
)

Note: Secure storage and the strength of the password are not handled by this package

Functions

func CheckPasswordStrength

func CheckPasswordStrength(pass string) error

CheckPasswordStrength : VErify that the given password strength is good enougth

func GenerateNewValidPassword

func GenerateNewValidPassword() []byte

GenerateNewValidPassword : Generate a valid password that includes defaultPasswordLen characters with 2 Upper case characters, 2 numbers and 2 characters from "!@#$&-+;" The other method of select random byte array and verify if it fits the rules may take a lot of iterations to fit the rules The entropy is not perfect but its good enougth for temporary reset password

func GetHashedPwd

func GetHashedPwd(pwd []byte) []byte

GetHashedPwd : The password should be handled and stored as hashed and not in clear text This function implementation may later be updated to crypto.cbytes

Types

type Serializer

type Serializer struct{}

Serializer : virtual set of functions that must be implemented by each module

func (Serializer) AddToStorage

func (s Serializer) AddToStorage(prefix string, data interface{}, storage *ss.SecureStorage) error

AddToStorage : Add the Password property information to the secure_storage

func (Serializer) IsEqualProperties

func (s Serializer) IsEqualProperties(da1 interface{}, da2 interface{}) bool

IsEqualProperties : Compare 2 Password properties

func (Serializer) PrintProperties

func (s Serializer) PrintProperties(data interface{}) string

PrintProperties : Print the Password property data

func (Serializer) ReadFromStorage

func (s Serializer) ReadFromStorage(key string, storage *ss.SecureStorage) (interface{}, error)

ReadFromStorage : Return the entity Password data read from the secure storage (in JSON format)

type UserPwd

type UserPwd struct {
	Password      []byte
	Salt          []byte
	Expiration    time.Time
	ErrorsCounter int
	TemporaryPwd  bool // must be replaced after the first use
	OldPasswords  [defaultNumberOfOldPasswords][]byte
}

UserPwd : structure that holds all the parameters relevant to handle password such as the passward, salt, expiration time, counters etc.

Example

Example of how to use the password.

1. Create a new password.
2. Verify that the initial password is set correctly
3. Change the user's password
4. Verify that the old password is not valid anymore
5. Verify that the new password is valid
6. Verify that the old password can't be used any more (at least not as long as it remains in the old passwords list)

package main

import (
	"fmt"

	"github.com/ibm-security-innovation/libsecurity-go/password"
	"github.com/ibm-security-innovation/libsecurity-go/salt"
)

var (
	minPasswordLength = 1
	maxPasswordLength = 255
)

func main() {
	id := "User-1"
	pwd := []byte("a1B2c3d^@")
	saltStr, _ := salt.GetRandomSalt(8)

	userPwd, _ := password.NewUserPwd(pwd, saltStr, true)
	tPwd, _ := salt.GenerateSaltedPassword(pwd, minPasswordLength, maxPasswordLength, saltStr, -1)
	newPwd := password.GetHashedPwd(tPwd)
	err := userPwd.IsPasswordMatch(newPwd)
	if err != nil {
		fmt.Println("Ravid: error", err)
	}
	userNewPwd := []byte(string(pwd) + "a")
	newPwd, err = userPwd.UpdatePassword(userPwd.Password, userNewPwd, true)
	if err != nil {
		fmt.Printf("Password update for user %v to new password '%v' (%v) failed, error: %v\n", id, newPwd, string(userNewPwd), err)
	} else {
		fmt.Printf("User: '%v', updated password to '%v' (%v)\n", id, newPwd, string(userNewPwd))
	}
	err = userPwd.IsPasswordMatch(newPwd)
	if err != nil {
		fmt.Printf("Check of the new password: '%v' (%v) for user: %v failed, error: %v\n", newPwd, string(userNewPwd), id, err)
	} else {
		fmt.Printf("User: '%v', new password '%v' (%v) verified successfuly\n", id, newPwd, string(userNewPwd))
	}
	err = userPwd.IsPasswordMatch(pwd)
	if err == nil {
		fmt.Printf("Error: Old password: '%v' (%v) for user: %v accepted\n", pwd, string(pwd), id)
	} else {
		fmt.Printf("User: '%v', Note that the old password '%v' (%v) can't be used anymore\n", id, pwd, string(pwd))
	}
	newPwd, err = userPwd.UpdatePassword(userPwd.Password, pwd, true)
	if err == nil {
		fmt.Printf("Error: Password '%v' (typed password %v) for user %v was alredy used\n", newPwd, string(pwd), id)
	} else {
		fmt.Printf("Entity: '%v', Note that the old password (entered password) %v as it was already used\n", id, string(pwd))
	}
}

func NewUserPwd

func NewUserPwd(pwd []byte, saltData []byte, checkPwdStrength bool) (*UserPwd, error)

NewUserPwd : Generate a new UserPwd for a given password The generated password is with a default expiration time

func (UserPwd) IsNewPwdValid

func (u UserPwd) IsNewPwdValid(pwd []byte, checkPwdStrength bool) error

IsNewPwdValid : Verify that the password is legal: its length is OK and it wasn't recently used

func (*UserPwd) IsPasswordMatch

func (u *UserPwd) IsPasswordMatch(pwd []byte) error

IsPasswordMatch : Verify that the given password is the expected one and that it is not expired

func (*UserPwd) ResetPasword

func (u *UserPwd) ResetPasword() ([]byte, error)

ResetPasword : Reset the password of a given user to a random password and make it a One-time-password with a short window time in which it should be used and replaced by the user

Example

Example of how to use the reset password function: This function resets the current password, selects a new password with short expiration time and lets the user use it exactly once

package main

import (
	"fmt"

	"github.com/ibm-security-innovation/libsecurity-go/password"
	"github.com/ibm-security-innovation/libsecurity-go/salt"
)

func main() {
	id := "User1"
	pwd := []byte("a1b2C@3d4")

	saltStr, _ := salt.GetRandomSalt(10)
	userPwd, _ := password.NewUserPwd(pwd, saltStr, false)
	tmpPwd, _ := userPwd.ResetPasword()
	tPwd, _ := salt.GenerateSaltedPassword(tmpPwd, 1, 100, saltStr, -1)
	newPwd := password.GetHashedPwd(tPwd)
	err := userPwd.IsPasswordMatch(newPwd)
	if err != nil {
		fmt.Printf("Check of newly generated password: '%v' for user: %v failed, error: %v\n", newPwd, id, err)
	} else {
		fmt.Printf("Entity %v, after reseting password '%v' verified successfuly\n", id, newPwd)
	}
	err = userPwd.IsPasswordMatch(newPwd)
	if err == nil {
		fmt.Printf("Error: Newly generated password: '%v' could be used only once\n", newPwd)
	} else {
		fmt.Printf("Newly generated password: '%v', for entity: %v, can only be used once\n", newPwd, id)
	}
}

func (*UserPwd) SetTemporaryPwd

func (u *UserPwd) SetTemporaryPwd(flag bool)

SetTemporaryPwd : sets the temporary password status to the given value

func (UserPwd) String

func (u UserPwd) String() string

func (*UserPwd) UpdatePassword

func (u *UserPwd) UpdatePassword(currentPwd []byte, pwd []byte, checkPwdStrength bool) ([]byte, error)

UpdatePassword : Update password and expiration time

func (*UserPwd) UpdatePasswordAfterReset

func (u *UserPwd) UpdatePasswordAfterReset(currentPwd []byte, pwd []byte, expiration time.Time) ([]byte, error)

UpdatePasswordAfterReset : Update the password, it's expioration time and it's state (is it a one-time-password or a regular one)