README
¶
Security
Security 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 security provides simple bindings for security related tasks in golang. This includes encrypting & decrypting data, password & other data hashing, and random value generation.
Index ¶
- Constants
- Variables
- 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
- type Hasher
- type HashingAlgorithm
Examples ¶
Constants ¶
const ( // HashingAlgorithmBCrypt constant value representing the BCrypt hashing algorithm HashingAlgorithmBCrypt = HashingAlgorithm("1") // HashingAlgorithmArgon2id constant value representing the Argon2id hashing algorithm HashingAlgorithmArgon2id = HashingAlgorithm("2") )
Variables ¶
var FailDelay = 3 * time.Second
FailDelay how long to sleep when an incorrect password was detected. Defaults to 3 seconds.
Functions ¶
func Decrypt ¶
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/security"
)
func main() {
encryptedBytes, _ := hex.DecodeString("c2a2ae6cb914c62b8c60b2697202649e66b02fac34b686ded43a4148de6537e1f3135ec351eedcf2")
passphrase := "hunter1"
decryptedBytes, err := security.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 ¶ added in v1.2.0
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 ¶
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/security"
)
func main() {
data := []byte("Hello world!")
passphrase := "hunter1"
encryptedBytes, err := security.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))
}
Output:
func EncryptKey ¶ added in v1.2.0
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 ¶ added in v1.1.0
HashSHA256 return the SHA-256 hash of the provided data. Do not use for passwords.
Example ¶
package main
import (
"fmt"
"github.com/ecnepsnai/security"
)
func main() {
hash := security.HashSHA256([]byte("hunter2"))
fmt.Printf("%x\n", hash)
}
Output: f52fbd32b2b3b86ff88ef6c490628285f482af15ddcb29541f94bcf526a3f6c7
func HashSHA256String ¶ added in v1.1.0
HashSHA256String return a hexadecimal string representing the SHA-256 hash of the provided string. Do not use for passwords.
Example ¶
package main
import (
"fmt"
"github.com/ecnepsnai/security"
)
func main() {
hash := security.HashSHA256String("hunter2")
fmt.Printf("%s\n", hash)
}
Output: f52fbd32b2b3b86ff88ef6c490628285f482af15ddcb29541f94bcf526a3f6c7
func HashSHA512 ¶ added in v1.1.0
HashSHA512 return the SHA-512 hash of the provided data. Do not use for passwords.
Example ¶
package main
import (
"fmt"
"github.com/ecnepsnai/security"
)
func main() {
hash := security.HashSHA512([]byte("hunter2"))
fmt.Printf("%x\n", hash)
}
Output: 6b97ed68d14eb3f1aa959ce5d49c7dc612e1eb1dafd73b1e705847483fd6a6c809f2ceb4e8df6ff9984c6298ff0285cace6614bf8daa9f0070101b6c89899e22
func HashSHA512String ¶ added in v1.1.0
HashSHA512String return a hexadecimal string representing the SHA-512 hash of the provided string. Do not use for passwords.
Example ¶
package main
import (
"fmt"
"github.com/ecnepsnai/security"
)
func main() {
hash := security.HashSHA512String("hunter2")
fmt.Printf("%s\n", hash)
}
Output: 6b97ed68d14eb3f1aa959ce5d49c7dc612e1eb1dafd73b1e705847483fd6a6c809f2ceb4e8df6ff9984c6298ff0285cace6614bf8daa9f0070101b6c89899e22
func PassphraseToEncryptionKey ¶ added in v1.1.0
PassphraseToEncryptionKey hash a string suitable for a AES-256 key (32 bytes) using scrypt
func RandomBytes ¶ added in v1.1.0
RandomBytes generate random bytes of specified length. suitable for cryptographical use.
func RandomNumber ¶
RandomNumber generate a random number within the specified range. Not suitable for cryptographically use.
func RandomString ¶
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.
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.
Example ¶
package main
import (
"fmt"
"github.com/ecnepsnai/security"
)
func main() {
password := []byte("hunter2")
hashedPassword, err := security.HashPassword(password)
if err != nil {
panic(err)
}
// hashedPassword contains the algorithm used, the salt (if applicable), and the hash data
// it is safe for storage.
fmt.Printf("%s\n", *hashedPassword)
}
Output:
func HashPasswordAlgorithm ¶ added in v1.1.0
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 ¶ added in v1.1.0
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. If false, will sleep for the duration specified by FailDelay.
Example ¶
package main
import (
"fmt"
"github.com/ecnepsnai/security"
)
func main() {
password := []byte("hunter2")
hashedPassword, err := security.HashPassword(password)
if err != nil {
panic(err)
}
test1 := hashedPassword.Compare([]byte("hunter1"))
test2 := hashedPassword.Compare([]byte("hunter2"))
test3 := hashedPassword.Compare([]byte("hunter3"))
fmt.Printf("Test 1: %v, Test 2: %v, Test 3: %v\n", test1, test2, test3)
}
Output: Test 1: false, Test 2: true, Test 3: false
func (HashedPassword) Upgrade ¶ added in v1.1.0
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 nil if no upgraded needed.
type Hasher ¶ added in v1.1.0
type Hasher struct {
// contains filtered or unexported fields
}
Hasher describes an object that can hash data
type HashingAlgorithm ¶ added in v1.1.0
type HashingAlgorithm string
HashingAlgorithm describes an enum type for a hashing algorithm
Source Files