crypto

README

go-crypto-suite

A quick, easy-to-use, and convenient Go language cryptography toolkit that provides a unified interface for key generation, key import/export, encryption/decryption, signing/verification, password hashing, and other functionality.

Features

Based on Go's generics feature, it supports []byte and string.

Unified output format:

• Ciphertext format: {algorithm identifier}.{ciphertext}, {algorithm identifier}.{ciphertext}.{signature}.
• Ciphertext + signature format: {algorithm identifier}.{ciphertext}.{signature}
• Signature format: {algorithm identifier}.{message digest}.{signature}
• Hash format: {algorithm identifier}.{hash value}

Supported Algorithms

Hasher	Encryption & Decryption	Signing & Verification	Hashing & Verification
AES_CBC_128	✔
AES_CBC_192	✔
AES_CBC_256	✔
AES_GCM_128	✔
AES_GCM_192	✔
AES_GCM_256	✔
Chacha20	✔
XChacha20	✔
RSA_1024	✔	✔
RSA_2048	✔	✔
RSA_4096	✔	✔
ECDSA_P256		✔
ECDSA_P384		✔
ECDSA_P521		✔
HMAC_SHA256		✔
HMAC_SHA512		✔
ARGON2I			✔
ARGON2ID			✔
PBKDF2_SHA256			✔
PBKDF2_SHA512			✔

Installation

go get github.com/yakumioto/go-crypto-suite

Usage Examples

Encryption: Using AES_GCM_256 to encrypt and decrypt strings

package main

import (
  "fmt"

  "github.com/yakumioto/go-crypto-suite"
  "github.com/yakumioto/go-crypto-suite/types"
)

func main() {
  key, err := crypto.KeyImport[string](types.AesGcm256, "123456")
  if err != nil {
    panic(err)
  }

  ciphertext, err := key.Encrypt("hello world")
  if err != nil {
    panic(err)
  }
  fmt.Println(ciphertext)
  // aes_gcm_256.RYrO4e+d2xslDQgZiZWQgClwVr/jZygLb3VMP5COwvxOBg6OSpHf

  plaintext, err := key.Decrypt(ciphertext)
  if err != nil {
    panic(err)
  }

  fmt.Println(plaintext)
  // hello world
}

Signing: Using ECDSA_P256 to sign and verify strings

package main

import (
    "fmt"

    "github.com/yakumioto/go-crypto-suite"
    "github.com/yakumioto/go-crypto-suite/types"
)

func main() {
    privKey, err := crypto.KeyGenerate[string](types.EcdsaP256)
    if err != nil {
       panic(err)
    }

    signature, err := privKey.Sign("hello world")
    if err != nil {
       panic(err)
    }
    fmt.Println(signature)
    // ecdsa_p256.uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek.MEQCIBFl8IcfPldpN5eTOW+rKmrTyLTx7zZsdFv56suUGy2VAiA9ZIBt7i9WmQwazwtpki5M+8oZlFBqovITQzykZDfQBA
    
    pubKey, err := privKey.PublicKey()
    if err != nil {
       panic(err)
    }

    verified, err := pubKey.Verify("hello world", signature)
    if err != nil {
       panic(err)
    }

    fmt.Println(verified)
    // true
}

Password Hashing: Using ARGON2ID to hash passwords

package main

import (
    "fmt"

    "github.com/yakumioto/go-crypto-suite"
    "github.com/yakumioto/go-crypto-suite/argon2"
    "github.com/yakumioto/go-crypto-suite/types"
)

func main() {
    key, err := crypto.KeyGenerate[string](types.Argon2,
       argon2.WithMemory[string](65536),
       argon2.WithTime[string](4),
       argon2.WithThreads[string](4),
    )
    if err != nil {
       panic(err)
    }

    signature, err := key.Sign("hello world")
    if err != nil {
       panic(err)
    }
    fmt.Println(signature)
    // argon2.argon2id$v=19$m=65536,t=4,p=4$BYzGXsTNx3Vy86vpqWU7+Q$AgOiaQEMnPudblmI4rTHSmFgZcNAgND4aQM+KwtdK40

    verified, err := key.Verify("hello world", signature)
    if err != nil {
       panic(err)
    }

    fmt.Println(verified)
    // true
}

Community

Telegram：https://t.me/gocryptosuite

Acknowledgments

This project was inspired by the following projects:

• Hyperledger Fabric: https://github.com/hyperledger/fabric
• Bitwarden: https://bitwarden.com/help/bitwarden-security-white-paper

Contribution

Contributions are welcome! Please feel free to submit pull requests or open issues.

License

This project is licensed under the MIT License.

Documentation

Overview

Package crypto provides a set of cryptographic utilities in Go.

It includes interfaces and functions for handling cryptographic keys, such as Key, KeyGenerator, and KeyImporter. These interfaces provide methods for key generation, import, signing, verifying, encrypting, and decrypting.

The package supports a variety of cryptographic algorithms, including HMAC SHA, AES CBC, AES GCM, ECDSA, and RSA.

Example usage:

key, err := KeyImport[string]("123456", AesCbc128)
if err != nil {
    panic(err)
}

ciphertext, err := key.Encrypt("hello world")
if err != nil {
    panic(err)
}

plaintext, err := key.Decrypt(ciphertext)
if err != nil {
    panic(err)
}

This will encrypt the string "hello world" using the AES CBC 128 algorithm and then decrypt it back to the original string.

Index

• func KeyGenerate[T types.DataType](alg types.Algorithm, opts ...key.Option[T]) (key.Key[T], error)
• func KeyImport[T types.DataType](alg types.Algorithm, raw interface{}, opts ...key.Option[T]) (key.Key[T], error)

Examples

• KeyImport

Functions

func KeyGenerate

func KeyGenerate[T types.DataType](alg types.Algorithm, opts ...key.Option[T]) (key.Key[T], error)

KeyGenerate is a function that generates a cryptographic key based on a given algorithm. It supports ECDSA and RSA algorithms. If the algorithm is not supported, it returns an error.

func KeyImport

func KeyImport[T types.DataType](alg types.Algorithm, raw interface{}, opts ...key.Option[T]) (key.Key[T], error)

KeyImport is a function that imports a cryptographic key based on a given raw data and algorithm. It supports HMAC SHA, AES CBC, AES GCM, ECDSA, and RSA algorithms. If the algorithm is not supported, it returns an error.

Example

utils.RandomSize = func(len int) ([]byte, error) {
	b := make([]byte, len)
	for i := 0; i < len; i++ {
		b[i] = 'a'
	}
	return b, nil
}

key, err := KeyImport[string](types.AesCbc128, "123456")
if err != nil {
	panic(err)
}

ciphertext, err := key.Encrypt("hello world")
if err != nil {
	panic(err)
}
fmt.Println(ciphertext)

plaintext, err := key.Decrypt(ciphertext)
if err != nil {
	panic(err)
}
fmt.Println(plaintext)

Output:

aes_cbc_128.YWFhYWFhYWFhYWFhYWFhYWv1wt6aTe92jzFCoVBvNYU
hello world