pbkdf

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 17, 2023 License: MIT Imports: 9 Imported by: 0

README

Go PBKDF1 and PBKDF2 Implementation

Wikipedia

This is a PBKDF1 and PBKDF2 implementation in Go. It relies on the crypto package for the hash functions and random number generation.

The algorithms are implemented following RFC8018.

License

This code is supplied under the MIT license, see the LICENSE file for more details.

Basic Usage

You can call either EncodePassword or EncodePasswordPBKDF1 or EncodePasswordPBKDF2 to encode a password, if you're calling EncodePassword you will need to supply a kdf function with the PBKDF signature, the PBKDF1 and PBKDF2 satisfy this signature and are supplied as part of the library.

If you wish to verify a password you can call either VerifyPassword or VerifyPasswordPBKDF1 or VerifyPasswordPBKDF2, to verify the password you must supply the same hash and kdf that were supplied to the encode method.

Main Functions

The functions for PBKDF1 and PBKDF2 have the PBKDF signature as follows:

PBKDF(hash, P, S, dkLen) -> DK, error

Parameters

The parameters for both functions are the same as follows:

  • hash: The PRF(pseudo-random function) to be used. It must be a hash function compatible with the crypto package. (type crypto.Hash)
  • P: The password we want to derive the key from. (type []byte)
  • S: The salt to be used. (type []byte)
  • c: The number of iterations. (type int64)
  • dkLen: The length of the derived key. (type int64)
Return Values

The return values are the same for both functions as follows:

  • DK: The derived key. (type []byte)
  • error: An error if any. (type error)

Usage

Although it's possbile to use the one the functions(PBKDF1 and PBKDF2) by themselves the library provides helper functions to use the algorithms in a more convenient way.

Encoding

The library defines 3 functions to encode a password:

EncodePassword(hash, password, saltLength, iterationCount, keyLength, kdf) -> string, error

EncodePasswordPBKDF1(hash, password, saltLength, iterationCount, keyLength) -> string, error

EncodePasswordPBKDF2(hash, password, saltLength, iterationCount, keyLength) -> string, error

EncodePassword

This function generates a random salt of of saltLength bytes, converts the password from a string to a []byte slice and calls the supplied kdf function. It then passes the salt, the iteration count and the derived key to the function GeneratePasswordString and returns the result.

EncodePasswordPBKDF1

The same as calling EncondePassword with the kdf parameter set to PBKDF1

EncodePassword

The same as calling EncondePassword with the kdf parameter set to PBKDF2

Verification

The library defines 3 functions to verify a password:

VerifyPassword(hash, password, encodedPassword, kdf) -> bool, error

VerifyPasswordPBKDF1(hash, password, encodedPassword) -> bool, error

VerifyPasswordPBKDF2(hash, password, encodedPassword) -> bool, error

VerifyPassword

This function decodes the supplied encodedPassword using the function GetPasswordParametersFromString. It then calls the supplied kdf function with the parameters from the decoded password and compare the supplied key with the derived key.

VerifyPasswordPBKDF1

The same as calling VerifyPassword with the kdf parameter set to PBKDF1

VerifyPasswordPBKDF2

The same as calling VerifyPassword with the kdf parameter set to PBKDF2

Utility Functions
GeneratePasswordString

This function takes the salt(as a []byte sloce), the iteration count and the derived key(alo as a []byte slice) and returns a string in the format: salt:iterationCount:derivedKey where:

  • salt: The salt encoded in base64
  • iterationCount: The iteration count in decimal format
  • derivedKey: The derived key encoded in base64
GetPasswordParametersFromString

This function takes a string in the format generated by GeneratePasswordString and returns the salt(as a []byte slice), the iteration count and the derived key(as a []byte slice).

GenerateRandomSequence

This function generates a random sequence of bytes of the specified length, it uses cryto/rand to generate the random sequence.

GenerateRandomByte

This function takes a min and max value and returns a random byte(unsigned 8 bit integer) between the two values(inclusive), it uses cryto/rand to generate the random byte.

GenerateRandomInt64

This function takes a min and max value and returns a random int64(signed 64 bit integer) between the two values(inclusive), it uses cryto/rand to generate the random int64.

GenerateRandomPassword

This function takes a min and max value and returns a random password of length between min and max(inclusive), it uses cryto/rand to generate the random password. The password will only contain letters, numbers and the following symbols:!@#$%&*()-_+=[]{}^~?/:;<>.,

GenerateRandomPasswordFromRunes

This function takes a min and max value and a []rune slice. It returns a random password of length between min and max(inclusive) composed of random runes from the supplied slice. It uses cryto/rand to generate the random password.

GetRandomRune

This function takes a []rune slice and returns a random rune from the slice. It uses cryto/rand to generate the random rune.

ConvertUnsignedIntegerToByteSlice

This function converts an uint64 to a []byte slice

ConvertSliceToUnsignedInteger

This function converts a []byte slice to an uint64

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConvertSliceToUnsignedInteger 

func ConvertSliceToUnsignedInteger(slice []byte, bigEndian bool) uint64

ConvertByteSliceToUnsignedInteger converts a byte slice to an unsigned integer The slice parameter is the byte slice to be converted The bigEndian parameter indicates if the byte slice is big endian The integer is returned

func ConvertUnsignedIntegerToByteSlice 

func ConvertUnsignedIntegerToByteSlice(integer uint64, byteLength int, bigEndian bool) []byte

ConvertUnsignedIntegerToByteSlice converts an unsigned integer to a byte slice The integer parameter is the integer to be converted The byteLength parameter is the length of the byte slice The bigEndian parameter indicates if the byte slice should be big endian The byte slice is returned

func EncodePassword 

func EncodePassword(hash crypto.Hash, password string, saltLength, iterationCount, keyLength int64, kdf PBKDF) (string, error)

EncodePassword encodes a password using the given algorithm The encoded password is returned as a string in the format: salt:iterationCount:hashedPassword(salt and hashedPassword are base64 encoded) The hash parameter is the hash function to be used(can be any crypto.Hash) The saltLength parameter is the length of the salt in bytes The iterationCount parameter is the number of iterations The keyLength parameter is the length of the derived key in bytes The kdf parameter is the function used to generate the password key it must have the PBKDF signature

func EncodePasswordPBKDF1 

func EncodePasswordPBKDF1(hash crypto.Hash, password string, saltLength, iterationCount, keyLength int64) (string, error)

EncodePasswordPBKDF1 encodes a password using PBKDF1 algorithm The encoded password is returned in the format: salt:iterationCount:hashedPassword(salt and hashedPassword are base64 encoded) the hash parameter is the hash function to be used(can be any crypto.Hash) The saltLength parameter is the length of the salt in bytes The iterationCount parameter is the number of iterations The keyLength parameter is the length of the derived key in bytes

func EncodePasswordPBKDF2 

func EncodePasswordPBKDF2(hash crypto.Hash, password string, saltLength, iterationCount, keyLength int64) (string, error)

EncodePasswordPBKDF2 encodes a password using PBKDF2 algorithm The encoded password is returned as a string in the format: salt:iterationCount:hashedPassword(salt and hashedPassword are base64 encoded) The hash parameter is the hash function to be used(can be any crypto.Hash) The saltLength parameter is the length of the salt in bytes The iterationCount parameter is the number of iterations The keyLength parameter is the length of the derived key in bytes

func GeneratePasswordString 

func GeneratePasswordString(salt []byte, iterationCount int64, encodedPassword []byte) string

GeneratePasswordString generates a password string from the given parameters The salt parameter is the salt as a byte slice The iterationCount parameter is the iteration count The encodedPassword parameter is the encoded password as a byte slice The password string is returned in the format: salt:iterationCount:encodedPassword(salt and encodedPassword are base64 encoded)

func GenerateRandomByte 

func GenerateRandomByte(min, max byte) (byte, error)

GenerateRandomByte generates a random byte with value between min and max The min parameter is the minimum value of the random byte The max parameter is the maximum value of the random byte The random byte is returned

func GenerateRandomInt64 

func GenerateRandomInt64(min, max int64) (int64, error)

GenerateRandomInt64 generates a random int64 with value between min and max The min parameter is the minimum value of the random int64 The max parameter is the maximum value of the random int64 The random int64 is returned

func GenerateRandomPassword 

func GenerateRandomPassword(minLength, maxLength int) (string, error)

GenerateRandomPassword generates a random password The minLength parameter is the minimum length of the password The maxLength parameter is the maximum length of the password The password is returned as a string this function uses a built-in slice of runes for password generation to generate a password with a custom set of runes, use the GenerateRandomPasswordFromRunes function

func GenerateRandomPasswordFromRunes 

func GenerateRandomPasswordFromRunes(minLength, maxLength int, passwordRunes []rune) (string, error)

GenerateRandomPassword generates a random password The minLength parameter is the minimum length of the password The maxLength parameter is the maximum length of the password The password is returned as a string

func GenerateRandomSequence 

func GenerateRandomSequence(length int) ([]byte, error)

GenerateRandomSequence generates a random sequence of bytes with the given length. The length parameter is the length of the random sequence in bytes this function uses the crypto/rand package

func GetPasswordParametersFromString 

func GetPasswordParametersFromString(encodedPassword string) ([]byte, int64, []byte, error)

GetPasswordParametersFromString gets the password parameters from a password string the encodedPassword parameter is the password string the string must be in the format: salt:iterationCount:encodedPassword(salt and encodedPassword are base64 encoded) the salt, iterationCount and encodedPassword parameters are returned in this order the salt and encodedPassword parameters are byte slices

func GetRandomRune 

func GetRandomRune(validRunes []rune) (rune, error)

GetRandomRune gets a random rune from a slice of runes The validRunes parameter is the slice of runes to get the random rune from The random rune is returned

func PBKDF1 

func PBKDF1(hash crypto.Hash, P []byte, S []byte, c int64, dkLen int64) ([]byte, error)

PBKDF1 is a function that implements the PBKDF1 algorithm It is based on the RFC8018(https://datatracker.ietf.org/doc/html/rfc8018) it implements the PBKDF function type

func PBKDF2 

func PBKDF2(hash crypto.Hash, P []byte, S []byte, c int64, dkLen int64) ([]byte, error)

PBKDF2 is a function that implements the PBKDF2 algorithm It is based on the RFC8018(https://datatracker.ietf.org/doc/html/rfc8018) it implements the PBKDF function type

func VerifyPassword 

func VerifyPassword(hash crypto.Hash, password, encodedPassword string, kdf PBKDF) (bool, error)

VerifyPassword checks if a password matches an encoded password The encoded password must be in the format: salt:iterationCount:hashedPassword(salt and hashedPassword are base64 encoded) The hash parameter is the hash function to be used(can be any crypto.Hash) The password parameter is the password to be checked The encodedPassword parameter is the encoded password The function parameter is the function that has been used to generate the encoded password it must have the PBKDF signature

func VerifyPasswordPBKDF1 

func VerifyPasswordPBKDF1(hash crypto.Hash, password, encodedPassword string) (bool, error)

VerifyPasswordPBKDF1 checks if a password matches an encoded password The encoded password must be in the format: salt:iterationCount:hashedPassword(salt and hashedPassword are base64 encoded) The hash parameter is the hash function to be used(can be any crypto.Hash) The password parameter is the password to be checked The encodedPassword parameter is the encoded password

func VerifyPasswordPBKDF2 

func VerifyPasswordPBKDF2(hash crypto.Hash, password, encodedPassword string) (bool, error)

VerifyPasswordPBKDF2 checks if a password matches an encoded password The encoded password must be in the format: salt:iterationCount:hashedPassword(salt and hashedPassword are base64 encoded) The hash parameter is the hash function to be used(can be any crypto.Hash) The password parameter is the password to be checked The encodedPassword parameter is the encoded password

Types

type PBKDF 

type PBKDF func(hash crypto.Hash, P []byte, S []byte, c int64, dkLen int64) ([]byte, error)

PBKDF is the general signature for a password-based key derivation function. hash: the hash function to be used(can be any crypto.Hash) P: the password(as a byte slice) S: the salt(as a byte slice) c: the iteration count dkLen: the byte length of the derived key returns: DK, the derived key or an error if any the functions PBKDF1 and PBKDF2 of this package implement this function

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.