secutil

package module
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Jun 20, 2021 License: MIT Imports: 20 Imported by: 2

README

Security Utilities (secutil)

Go Report Card Godoc Releases LICENSE

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 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.

**This method is deprecated in favor of `secutil.Cryptograpy.AES_256_GCM.Decrypt` and will be removed in a future release of secutil**

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.

**This method is deprecated in favor of `secutil.Cryptograpy.AES_256_GCM.DecryptKey` and will be removed in a future release of secutil**

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.

**This method is deprecated in favor of `secutil.Cryptograpy.AES_256_GCM.Encrypt` and will be removed in a future release of secutil**

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.

**This method is deprecated in favor of `secutil.Cryptograpy.AES_256_GCM.EncryptKey` and will be removed in a future release of secutil**

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.

**This method is deprecated in favor of `secutil.Hashing.SHA_256.Hash` and will be removed in a future version of secutil.**

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.

**This method is deprecated in favor of `secutil.Hashing.SHA_256.HashString` and will be removed in a future version of secutil.**

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.

**This method is deprecated in favor of `secutil.Hashing.SHA_512.Hash` and will be removed in a future version of secutil.**

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.

**This method is deprecated in favor of `secutil.Hashing.SHA_512.HashString` and will be removed in a future version of secutil.**

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.

**This method is deprecated in favor of `secutil.Cryptograpy.AES_256_GCM.PassphraseToKey` and will be removed in a future release of secutil**

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 EncryptionAES256GCM added in v1.0.2 

type EncryptionAES256GCM struct{}

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

func (EncryptionAES256GCM) Decrypt added in v1.0.2 

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"

	"github.com/ecnepsnai/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 added in v1.0.2 

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 added in v1.0.2 

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"

	"github.com/ecnepsnai/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 added in v1.0.2 

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 added in v1.0.2 

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

PassphraseToKey generates a 32-byte key from the given passphrase

type EncryptionChaCha20Poly1305 added in v1.0.2 

type EncryptionChaCha20Poly1305 struct{}

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

func (EncryptionChaCha20Poly1305) Decrypt added in v1.0.2 

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"

	"github.com/ecnepsnai/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 added in v1.0.2 

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 added in v1.0.2 

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"

	"github.com/ecnepsnai/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 added in v1.0.2 

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 added in v1.0.2 

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"

	"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

type HashingBLAKE2 added in v1.0.2 

type HashingBLAKE2 struct {
	Len int
}

HashingBLAKE2 is an implementation of the IHashing interface for BLAKE2b hashing

func (HashingBLAKE2) Hash added in v1.0.2 

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

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

func (HashingBLAKE2) HashString added in v1.0.2 

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"

	"github.com/ecnepsnai/secutil"
)

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

Output:
d354690b768614c9bb4bf2ae367dc1b86cd3d6c1bd0ac6c281fe0c278bd8f2ae

type HashingSHA added in v1.0.2 

type HashingSHA struct {
	Len int
}

HashingSHA is an implementation of the IHashing interface for SHA hashing

func (HashingSHA) Hash added in v1.0.2 

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

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

func (HashingSHA) HashString added in v1.0.2 

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"

	"github.com/ecnepsnai/secutil"
)

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

Output:
d61b9f52be1d066db55f392faf119d6a13302fdb7da80f62a9e5e9aa332f534b

type IEncryption added in v1.0.2 

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 added in v1.0.2 

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

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.