secutil

README

Security Utilities (secutil)

Security utilities provides simple bindings for security related tasks in golang. This includes encrypting & decrypting data, password & other data hashing, and random value generation.

Usage & Examples

Examples can be found on the documentation for the library

Documentation

Overview

Package secutil provides simple bindings for security related tasks in golang. This includes encrypting & decrypting data, password & other data hashing, and random value generation.

Index

• Constants
• func Decrypt(data []byte, passphrase string) ([]byte, error)
• func DecryptKey(data []byte, key []byte) ([]byte, error)
• func Encrypt(data []byte, passphrase string) ([]byte, error)
• func EncryptKey(data []byte, key []byte) ([]byte, error)
• func HashSHA256(raw []byte) []byte
• func HashSHA256String(raw string) string
• func HashSHA512(raw []byte) []byte
• func HashSHA512String(raw string) string
• func PassphraseToEncryptionKey(raw string) []byte
• func RandomBytes(length uint16) []byte
• func RandomNumber(min int, max int) int
• func RandomString(randomLength uint16) string
• type HashedPassword
  • func HashPassword(password []byte) (*HashedPassword, error)
  • func HashPasswordAlgorithm(password []byte, alg HashingAlgorithm) (*HashedPassword, error)
  • func (p HashedPassword) Algorithm() HashingAlgorithm
  • func (p HashedPassword) Compare(password []byte) bool
  • func (p HashedPassword) Upgrade(password []byte) *HashedPassword
• type HashingAlgorithm

Examples

• Decrypt
• Encrypt
• HashPassword
• HashSHA256
• HashSHA256String
• HashSHA512
• HashSHA512String
• HashedPassword.Compare

Constants

const (
	// HashingAlgorithmBCrypt constant value representing the BCrypt hashing algorithm
	HashingAlgorithmBCrypt = HashingAlgorithm("1")
	// HashingAlgorithmArgon2id constant value representing the Argon2id hashing algorithm
	HashingAlgorithmArgon2id = HashingAlgorithm("2")
	// HashingAlgorithmPBKDF2 constant value representing the PBKDF2 hashing algorithm
	HashingAlgorithmPBKDF2 = HashingAlgorithm("3")
)

Functions

func Decrypt

func Decrypt(data []byte, passphrase string) ([]byte, error)

Decrypt will decrypt the given encrypted data using AES-256-GCM with the given passphrase. The passphrase can be a user provided value, and is hashed using scrypt before being used.

Will return error if an empty passphrase or data is provided.

Example

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/ecnepsnai/secutil"
)

func main() {
	encryptedBytes, _ := hex.DecodeString("c2a2ae6cb914c62b8c60b2697202649e66b02fac34b686ded43a4148de6537e1f3135ec351eedcf2")
	passphrase := "hunter1"

	decryptedBytes, err := secutil.Decrypt(encryptedBytes, passphrase)
	if err != nil {
		// Decryption failed, password was incorrect?
		panic(err)
	}

	// Do something with the decrypted bytes
	fmt.Printf("Decrypted bytes: '%s'\n", decryptedBytes)

}

Output:

Decrypted bytes: 'Hello world!'

func DecryptKey

func DecryptKey(data []byte, key []byte) ([]byte, error)

DecryptKey will decrypt the given encrypted data using AES-256-GCM with the given 32-byte key.

Will return error if an invaid key or data is provided.

func Encrypt

func Encrypt(data []byte, passphrase string) ([]byte, error)

Encrypt will encrypt the given data using AES-256-GCM with the given passphrase. The passphrase can be a user provided value, and is hashed using scrypt before being used.

Will return error if an empty passphrase or data is provided.

Example

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/ecnepsnai/secutil"
)

func main() {
	data := []byte("Hello world!")
	passphrase := "hunter1"
	encryptedBytes, err := secutil.Encrypt(data, passphrase)
	if err != nil {
		// Encryption failed for some reason
		panic(err)
	}

	// Encrypted bytes are not ASCII, you should convert it to
	// hex if you plan to store it as a string
	fmt.Printf("Encrypted bytes: '%s'\n", hex.EncodeToString(encryptedBytes))
}

func EncryptKey

func EncryptKey(data []byte, key []byte) ([]byte, error)

EncryptKey will encrypt the given data using AES-256-GCM with the given 32-byte key.

Will return error if an invaid key or data is provided.

func HashSHA256

func HashSHA256(raw []byte) []byte

HashSHA256 return the SHA-256 hash of the provided data. Do not use for secret data from users, such as passwords.

Example

package main

import (
	"fmt"

	"github.com/ecnepsnai/secutil"
)

func main() {
	hash := secutil.HashSHA256([]byte("hunter2"))
	fmt.Printf("%x\n", hash)

}

Output:

f52fbd32b2b3b86ff88ef6c490628285f482af15ddcb29541f94bcf526a3f6c7

func HashSHA256String

func HashSHA256String(raw string) string

HashSHA256String return a hexadecimal string representing the SHA-256 hash of the provided string. Do not use for secret data from users, such as passwords.

Example

package main

import (
	"fmt"

	"github.com/ecnepsnai/secutil"
)

func main() {
	hash := secutil.HashSHA256String("hunter2")
	fmt.Printf("%s\n", hash)

}

Output:

f52fbd32b2b3b86ff88ef6c490628285f482af15ddcb29541f94bcf526a3f6c7

func HashSHA512

func HashSHA512(raw []byte) []byte

HashSHA512 return the SHA-512 hash of the provided data. Do not use for secret data from users, such as passwords.

Example

package main

import (
	"fmt"

	"github.com/ecnepsnai/secutil"
)

func main() {
	hash := secutil.HashSHA512([]byte("hunter2"))
	fmt.Printf("%x\n", hash)

}

Output:

6b97ed68d14eb3f1aa959ce5d49c7dc612e1eb1dafd73b1e705847483fd6a6c809f2ceb4e8df6ff9984c6298ff0285cace6614bf8daa9f0070101b6c89899e22

func HashSHA512String

func HashSHA512String(raw string) string

HashSHA512String return a hexadecimal string representing the SHA-512 hash of the provided string. Do not use for secret data from users, such as passwords.

Example

package main

import (
	"fmt"

	"github.com/ecnepsnai/secutil"
)

func main() {
	hash := secutil.HashSHA512String("hunter2")
	fmt.Printf("%s\n", hash)

}

Output:

6b97ed68d14eb3f1aa959ce5d49c7dc612e1eb1dafd73b1e705847483fd6a6c809f2ceb4e8df6ff9984c6298ff0285cace6614bf8daa9f0070101b6c89899e22

func PassphraseToEncryptionKey

func PassphraseToEncryptionKey(raw string) []byte

PassphraseToEncryptionKey hash a string suitable for a AES-256 key (32 bytes) using scrypt

func RandomBytes

func RandomBytes(length uint16) []byte

RandomBytes generate random bytes of specified length. Suitable for cryptographical use. This may panic if too much data was requested.

func RandomNumber

func RandomNumber(min int, max int) int

RandomNumber generate a random number within the specified range. Not suitable for cryptographically use.

func RandomString

func RandomString(randomLength uint16) string

RandomString generate a random string (hex characters) with the length of random entropy. Returned string will be exactly 2* longer than `randomLength`. For example, if you want a string that's 32 characters long, specify 16 for the random length. Suitable for cryptographical use. This may panic if too much data was requested.

Types

type HashedPassword

type HashedPassword []byte

HashedPassword describes a hashed password

func HashPassword

func HashPassword(password []byte) (*HashedPassword, error)

HashPassword returns a hashed representation of the provided password that is suitable for storage. Current algorithm used is Argon2ID with time=1, memory=62*1024, threads=<number of logical CPUs of your system>.

Example

package main

import (
	"fmt"

	"github.com/ecnepsnai/secutil"
)

func main() {
	password := []byte("hunter2")
	hashedPassword, err := secutil.HashPassword(password)
	if err != nil {
		panic(err)
	}

	// hashedPassword contains the algorithm used, the salt, and the hash data. It is safe for storage.
	fmt.Printf("%s\n", *hashedPassword)
}

func HashPasswordAlgorithm

func HashPasswordAlgorithm(password []byte, alg HashingAlgorithm) (*HashedPassword, error)

HashPasswordAlgorithm returns a hashed representation of the provided password that is suitable for storage using the given hashing algorithm.

func (HashedPassword) Algorithm

func (p HashedPassword) Algorithm() HashingAlgorithm

Algorithm get the algorithm used for this hashed password.

func (HashedPassword) Compare

func (p HashedPassword) Compare(password []byte) bool

Compare does password match the hashed password. Returns true if matched.

Example

package main

import (
	"fmt"

	"github.com/ecnepsnai/secutil"
)

func main() {
	password := []byte("hunter2")
	hashedPassword, err := secutil.HashPassword(password)
	if err != nil {
		panic(err)
	}

	test1 := hashedPassword.Compare([]byte("hunter1"))
	test2 := hashedPassword.Compare([]byte("hunter2"))
	test3 := hashedPassword.Compare([]byte("hunter3"))

	fmt.Printf("Password is 'hunter1': %v, Password is 'hunter2': %v, Password is 'hunter3': %v\n", test1, test2, test3)

}

Output:

Password is 'hunter1': false, Password is 'hunter2': true, Password is 'hunter3': false

func (HashedPassword) Upgrade

func (p HashedPassword) Upgrade(password []byte) *HashedPassword

Upgrade generate a new password object if the current hashing algorithm could be replaced with a better option. Returns a new hashed password object, or nil if no upgrade is needed.

type HashingAlgorithm

type HashingAlgorithm string

HashingAlgorithm describes an enum type for a hashing algorithm