secutil

package module
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 19 Imported by: 0

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

Examples

Constants

View Source 
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")
)

Variables

View Source 
var Encryption = struct {
	AES_256_GCM       IEncryption
	CHACHA20_POLY1305 IEncryption
}{
	AES_256_GCM:       EncryptionAES256GCM{},
	CHACHA20_POLY1305: EncryptionChaCha20Poly1305{},
}

Encryption provides access to a standard interface for cryptographic encryption and decrption tasks

View Source 
var Hashing = struct {
	SHA_256    IHashing
	SHA_512    IHashing
	BLAKE2_256 IHashing
	BLAKE2_384 IHashing
	BLAKE2_512 IHashing
}{
	SHA_256:    HashingSHA{256},
	SHA_512:    HashingSHA{512},
	BLAKE2_256: HashingBLAKE2{256},
	BLAKE2_384: HashingBLAKE2{384},
	BLAKE2_512: HashingBLAKE2{512},
}

Hashing provides access to a standard interface for cryptographic hashing

Functions

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 int64, max int64) int64

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

func RandomString deprecated 

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.

Deprecated: Recommended to use RandomStringHex - keep in mind that the length variable to that function does not work as with this function.

func RandomStringFrom added in v1.0.2 

func RandomStringFrom(strLength uint16, alphabet string) string

RandomStringFrom returns a random string using each of the runes in alphabet. It will panic if strLength is 0 or if alphabet is empty.

func RandomStringHex added in v1.0.2 

func RandomStringHex(strLength uint16) string

RandomStringHex returns a random string in hex characters that is exactly the length provided. Returned values are always lower case.

Types

type EncryptionAES256GCM 

type EncryptionAES256GCM struct{}

EncryptionAES256GCM is an implementation of the IEncryption interface for AES-256-GCM cryptography

func (EncryptionAES256GCM) Decrypt 

func (t EncryptionAES256GCM) 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"

	"git.ecn.io/ian/secutil"
)

func main() {
	encryptedBytes, _ := hex.DecodeString("4cf3c191dc75cdbd37bca050c99028ef8b43cbb85b36a890ea5ad074eaa1a250e62dad0a3da0cd090a08cfd1")
	passphrase := "password"

	decryptedBytes, err := secutil.Encryption.AES_256_GCM.Decrypt(encryptedBytes, passphrase)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%s\n", decryptedBytes)
}

Output:
some secret data

func (EncryptionAES256GCM) DecryptKey 

func (t EncryptionAES256GCM) 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 (EncryptionAES256GCM) Encrypt 

func (t EncryptionAES256GCM) 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"

	"git.ecn.io/ian/secutil"
)

func main() {
	passphrase := "password"
	data := []byte("some secret data")

	encryptedBytes, err := secutil.Encryption.AES_256_GCM.Encrypt(data, passphrase)
	if err != nil {
		panic(err)
	}

	// Encrypted bytes are binary so you may wish to encode them as hex bytes
	hexBytes := hex.EncodeToString(encryptedBytes)

	fmt.Printf("Encrypted bytes: %s\n", hexBytes)
}

func (EncryptionAES256GCM) EncryptKey 

func (t EncryptionAES256GCM) 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 (EncryptionAES256GCM) PassphraseToKey 

func (t EncryptionAES256GCM) PassphraseToKey(passphrase string) []byte

PassphraseToKey generates a 32-byte key from the given passphrase

type EncryptionChaCha20Poly1305 

type EncryptionChaCha20Poly1305 struct{}

EncryptionChaCha20Poly1305 is an implementation of the IEncryption interface for ChaCha20-Poly1305 cryptography

func (EncryptionChaCha20Poly1305) Decrypt 

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

Decrypt will decrypt the given encrypted data using ChaCha20-Poly1305 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"

	"git.ecn.io/ian/secutil"
)

func main() {
	encryptedBytes, _ := hex.DecodeString("c2b602e819dbac10ac1cf9f3b9408c783b1769a703bc2169131046af4715fd70005228fb00c894d3a6d0877ab637261d593b28888600bf5d")
	passphrase := "password"

	decryptedBytes, err := secutil.Encryption.CHACHA20_POLY1305.Decrypt(encryptedBytes, passphrase)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%s\n", decryptedBytes)
}

Output:
some secret data

func (EncryptionChaCha20Poly1305) DecryptKey 

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

DecryptKey will decrypt the given encrypted data using ChaCha20-Poly1305 with the given 32-byte key.

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

func (EncryptionChaCha20Poly1305) Encrypt 

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

Encrypt will encrypt the given data using ChaCha20-Poly1305 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"

	"git.ecn.io/ian/secutil"
)

func main() {
	passphrase := "password"
	data := []byte("some secret data")

	encryptedBytes, err := secutil.Encryption.CHACHA20_POLY1305.Encrypt(data, passphrase)
	if err != nil {
		panic(err)
	}

	// Encrypted bytes are binary so you may wish to encode them as hex bytes
	hexBytes := hex.EncodeToString(encryptedBytes)

	fmt.Printf("Encrypted bytes: %s\n", hexBytes)
}

func (EncryptionChaCha20Poly1305) EncryptKey 

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

EncryptKey will encrypt the given data using ChaCha20-Poly1305 with the given 32-byte key.

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

func (EncryptionChaCha20Poly1305) PassphraseToKey 

func (t EncryptionChaCha20Poly1305) PassphraseToKey(passphrase string) []byte

PassphraseToKey generates a 32-byte key from the given passphrase

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"

	"git.ecn.io/ian/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 MustHashPassword added in v1.0.2 

func MustHashPassword(password []byte) HashedPassword

MustHashPassword calls HashPassword but panics if an error is returned.

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"

	"git.ecn.io/ian/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

type HashingBLAKE2 

type HashingBLAKE2 struct {
	Len int
}

HashingBLAKE2 is an implementation of the IHashing interface for BLAKE2b hashing

func (HashingBLAKE2) Hash 

func (t HashingBLAKE2) Hash(in []byte) []byte

Hash will hash the given data with BLAKE2b and return hash bytes

func (HashingBLAKE2) HashString 

func (t HashingBLAKE2) HashString(in string) string

HashString will hash the given string with BLAKE2b and return a hex string

Example 
package main

import (
	"fmt"

	"git.ecn.io/ian/secutil"
)

func main() {
	input := "some secret data"
	result := secutil.Hashing.BLAKE2_256.HashString(input)
	fmt.Printf("%s\n", result)
}

Output:
d354690b768614c9bb4bf2ae367dc1b86cd3d6c1bd0ac6c281fe0c278bd8f2ae

type HashingSHA 

type HashingSHA struct {
	Len int
}

HashingSHA is an implementation of the IHashing interface for SHA hashing

func (HashingSHA) Hash 

func (t HashingSHA) Hash(in []byte) []byte

Hash will hash the given data with SHA and return hash bytes

func (HashingSHA) HashString 

func (t HashingSHA) HashString(in string) string

HashString will hash the given string with SHA and return a hex string

Example 
package main

import (
	"fmt"

	"git.ecn.io/ian/secutil"
)

func main() {
	input := "some secret data"
	result := secutil.Hashing.SHA_256.HashString(input)
	fmt.Printf("%s\n", result)
}

Output:
d61b9f52be1d066db55f392faf119d6a13302fdb7da80f62a9e5e9aa332f534b

type IEncryption 

type IEncryption interface {
	Encrypt(data []byte, passphrase string) ([]byte, error)
	EncryptKey(data []byte, key []byte) ([]byte, error)
	Decrypt(data []byte, passphrase string) ([]byte, error)
	DecryptKey(data []byte, key []byte) ([]byte, error)
	PassphraseToKey(passphrase string) []byte
}

IEncryption describes the interface for an encryption implementation

type IHashing 

type IHashing interface {
	Hash(in []byte) []byte
	HashString(in string) string
}

Source Files

  • encryption.go
  • encryption_aes256gcm.go
  • encryption_chacha20poly1305.go
  • hashing.go
  • hashing_blake2.go
  • hashing_sha.go
  • password.go
  • random.go
  • secutil.go

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.