dongle

README

English | 简体中文 | 日本語

Introduction

Dongle is a simple, semantic and developer-friendly golang crypto package with 100% unit test coverage，has been included by awesome-go

Repository

github.com/dromara/dongle

gitee.com/dromara/dongle

gitcode.com/dromara/dongle

Quick Start

Installation

go version >= 1.23

// Via github 
go get -u github.com/dromara/dongle
import "github.com/dromara/dongle"

// Via gitee
go get -u gitee.com/dromara/dongle
import "gitee.com/dromara/dongle"

// Via gitcode 
go get -u gitcode.com/dromara/dongle
import "gitcode.com/dromara/dongle"

Dongle was donated to the dromara organization, the repository URL has changed. If the previous repository used was golang-module/dongle, please replace the original repository with the new repository in go.mod, or execute the following command:

go mod edit -replace github.com/golang-module/dongle = github.com/dromara/dongle

Example Usage

Encode&Decode(using Base64 as an example)

import "github.com/dromara/dongle"

dongle.Encode.FromString("hello world").ByBase64().ToString()      // aGVsbG8gd29ybGQ=
dongle.Decode.FromString("aGVsbG8gd29ybGQ=").ByBase64().ToString() // hello world

Hash Algorithm(using Md5 as an example)

import "github.com/dromara/dongle"

dongle.Hash.FromString("hello world").ByMd5().ToHexString()    // 5eb63bbbe01eeed093cb22bb8f5acdc3
dongle.Hash.FromString("hello world").ByMd5().ToBase64String() // XrY7u+Ae7tCTyyK7j1rNww==

Hmac Algorithm(using Md5 as an example)

import "github.com/dromara/dongle"

dongle.Hash.FromString("hello world").WithKey([]byte("dongle")).ByMd5().ToHexString()    // 4790626a275f776956386e5a3ea7b726
dongle.Hash.FromString("hello world").WithKey([]byte("dongle")).ByMd5().ToBase64String() // R5Biaidfd2lWOG5aPqe3Jg==

Symmetric Encryption&Decryption(using AES as an example)

import (
	"github.com/dromara/dongle"
	"github.com/dromara/dongle/crypto/cipher"
)

// Create cipher
c := cipher.NewAesCipher(cipher.CBC)
// Set key (16 bytes)
c.SetKey([]byte("dongle1234567890")) 
// Set initialization vector (16 bytes)
c.SetIV([]byte("1234567890123456"))
// Set padding mode (optional, default is PKCS7)
c.SetPadding(cipher.PKCS7)

// Encrypt string plaintext, return hex-encoded string ciphertext
dongle.Encrypt.FromString("hello world").ByAes(c).ToHexString() // 48c6bc076e1da2946e1c0e59e9c91ae9
// Encrypt string plaintext, return base64-encoded string ciphertext
dongle.Encrypt.FromString("hello world").ByAes(c).ToBase64String() // SMa8B24dopRuHA5Z6cka6Q==

// Decrypt hex-encoded string ciphertext, return string plaintext
dongle.Decrypt.FromHexString("48c6bc076e1da2946e1c0e59e9c91ae9").ByAes(c).ToString() // hello world
// Decrypt base64-encoded string ciphertext, return string plaintext
dongle.Decrypt.FromBase64String("SMa8B24dopRuHA5Z6cka6Q==").ByAes(c).ToString() // hello world

Asymmetric Encryption&Decryption(using RSA as an example)

import (
	"crypto"
	"github.com/dromara/dongle"
	"github.com/dromara/dongle/crypto/keypair"
)

// Create key pair
kp := keypair.NewRsaKeyPair()
// Set key format (optional, default is PKCS8)
kp.SetFormat(keypair.PKCS8)
// Set hash algorithm (optional, default is SHA256)
kp.SetHash(crypto.SHA256)   

// Set public key
kp.SetPublicKey([]byte("MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqzZNa9VrcewyU6wDoV7Y9kAHqX1VK0B3Rb6GNmQe4zLEfce7cVTaLrc4VGTKl35tADG1cRHqtaG4S/WttpiGZBhxJy4MpOXb6eIPiVLsn2lL+rJo5XdbSr3gyjxEOQQ97ihtw4lDd5wMo4bIOuw1LtMezHC1outlM6x+/BB0BSQIDAQAB"))
// Encrypt string plaintext by public key, return hex-encoded string ciphertext
dongle.Encrypt.FromString("hello world").ByRsa(kp).ToHexString() // 7fae94fd1a8b880d8d5454dd8df30c40...
// Encrypt string plaintext by public key, return base64-encoded string ciphertext
dongle.Encrypt.FromString("hello world").ByRsa(kp).ToBase64String() // f66U/RqLiA2NVFTdjfMMQA==...

// Set private key
kp.SetPrivateKey([]byte("MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAKrNk1r1Wtx7DJTrAOhXtj2QAepfVUrQHdFvoY2ZB7jMsR9x7txVNoutzhUZMqXfm0AMbVxEeq1obhL9a22mIZkGHEnLgyk5dvp4g+JUuyfaUv6smjld1tKveDKPEQ5BD3uKG3DiUN3nAyjhsg67DUu0x7McLWi62UzrH78EHQFJAgMBAAECgYAeo3nHWzPNURVUsUMcan96U5bEYA2AugxfQVMNf2HvOGidZ2adh3udWrQY/MglERNcTd5gKriG2rDEH0liBecIrNKsBL4lV+qHEGRUcnDDdtUBdGInEU8lve5keDgmX+/huXSRJ+3tYA5u9j+32RquVczvIdtb5XnBLUl61k0osQJBAON5+eJjtw6xpn+pveU92BSHvaJYVyrLHwUjR07aNKb7GlGVM3MGf1FCa8WQUo9uUzYxGLtg5Qf3sqwOrwPd5UsCQQDAOF/zWqGuY3HfV/1wgiXiWp8rc+S8tanMj5M37QQbYW5YLjUmJImoklVahv3qlgLZdEN5ZSueM5jfoSFtNts7AkBKoRDvSiGbi4MBbTHkzLZgfewkH/FxE7S4nctePk553fXTgCyh9ya8BRuQdHnxnpNkOxVPHEnnpEcVFbgrf5gjAkB7KmRI4VTiEfRgINhTJAG0VU7SH/N7+4cufPzfA+7ywG5c8Fa79wOB0SoB1KeUjcSLo5Ssj2fwea1F9dAeU90LAkBJQFofveaDa3YlN4EQZOcCvJKmg7xwWuGxFVTZDVVEws7UCQbEOEEXZrNd9x0IF5kpPLR+rxuaRPgUNaDGIh5o"))
// Decrypt hex-encoded string ciphertext by private key, return string plaintext
dongle.Decrypt.FromHexString("7fae94fd1a8b880d8d5454dd8df30c40...").ByRsa(kp).ToString() // hello world
// Decrypt base64-encoded string ciphertext by private key, return string plaintext
dongle.Decrypt.FromBase64String("f66U/RqLiA2NVFTdjfMMQA==...").ByRsa(kp).ToString() // hello world

Digital Signature&Verification(using RSA as an example)

import (
	"crypto"
	"github.com/dromara/dongle"
	"github.com/dromara/dongle/crypto/keypair"
)

// Create key pair
kp := keypair.NewRsaKeyPair()
// Set key format (optional, default is PKCS8)
kp.SetFormat(keypair.PKCS8)
// Set hash algorithm (optional, default is SHA256)
kp.SetHash(crypto.SHA256)   

// Set private key
kp.SetPrivateKey([]byte("MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAKrNk1r1Wtx7DJTrAOhXtj2QAepfVUrQHdFvoY2ZB7jMsR9x7txVNoutzhUZMqXfm0AMbVxEeq1obhL9a22mIZkGHEnLgyk5dvp4g+JUuyfaUv6smjld1tKveDKPEQ5BD3uKG3DiUN3nAyjhsg67DUu0x7McLWi62UzrH78EHQFJAgMBAAECgYAeo3nHWzPNURVUsUMcan96U5bEYA2AugxfQVMNf2HvOGidZ2adh3udWrQY/MglERNcTd5gKriG2rDEH0liBecIrNKsBL4lV+qHEGRUcnDDdtUBdGInEU8lve5keDgmX+/huXSRJ+3tYA5u9j+32RquVczvIdtb5XnBLUl61k0osQJBAON5+eJjtw6xpn+pveU92BSHvaJYVyrLHwUjR07aNKb7GlGVM3MGf1FCa8WQUo9uUzYxGLtg5Qf3sqwOrwPd5UsCQQDAOF/zWqGuY3HfV/1wgiXiWp8rc+S8tanMj5M37QQbYW5YLjUmJImoklVahv3qlgLZdEN5ZSueM5jfoSFtNts7AkBKoRDvSiGbi4MBbTHkzLZgfewkH/FxE7S4nctePk553fXTgCyh9ya8BRuQdHnxnpNkOxVPHEnnpEcVFbgrf5gjAkB7KmRI4VTiEfRgINhTJAG0VU7SH/N7+4cufPzfA+7ywG5c8Fa79wOB0SoB1KeUjcSLo5Ssj2fwea1F9dAeU90LAkBJQFofveaDa3YlN4EQZOcCvJKmg7xwWuGxFVTZDVVEws7UCQbEOEEXZrNd9x0IF5kpPLR+rxuaRPgUNaDGIh5o"))
// Sign string data using private key, return hex-encoded signature
hexBytes := dongle.Sign.FromString("hello world").ByRsa(kp).ToHexBytes() // 7fae94fd1a8b880d8d5454dd8df30c40...
// Sign string data using private key, return base64-encoded signature
base64Bytes :=dongle.Sign.FromString("hello world").ByRsa(kp).ToBase64Bytes() // f66U/RqLiA2NVFTdjfMMQA==...

// Set public key
kp.SetPublicKey([]byte("MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqzZNa9VrcewyU6wDoV7Y9kAHqX1VK0B3Rb6GNmQe4zLEfce7cVTaLrc4VGTKl35tADG1cRHqtaG4S/WttpiGZBhxJy4MpOXb6eIPiVLsn2lL+rJo5XdbSr3gyjxEOQQ97ihtw4lDd5wMo4bIOuw1LtMezHC1outlM6x+/BB0BSQIDAQAB"))
// Verify hex-encoded signature using public key
dongle.Verify.FromString("hello world").WithHexSign(hexBytes).ByRsa(kp).ToBool()
// Verify base64-encoded signature using public key
dongle.Verify.FromString("hello world").WithBase64Sign(base64Bytes).ByRsa(kp).ToBool()

For more usage examples, please refer to official document.

Contributors

Thanks to all the following who contributed to dongle:

Sponsors

Dongle is a non-commercial open source project. If you want to support dongle, you can buy a cup of coffee for developer.

Thanks

Dongle had been being developed with GoLand under the free JetBrains Open Source license, I would like to express my thanks here.

License

Dongle is licensed under the MIT License, see the LICENSE file for details.

Documentation

Overview

Package dongle is a simple, semantic and developer-friendly golang crypto package.

Index

• Constants
• Variables

Constants

const Version = "1.1.2"

Variables

var (
	// Encode defines an Encoder instance.
	Encode = coding.NewEncoder()
	// Decode defines a Decoder instance.
	Decode = coding.NewDecoder()

	// Hash defines a Hasher instance.
	Hash = hash.NewHasher()

	// Encrypt defines an Encrypter instance.
	Encrypt = crypto.NewEncrypter()
	// Decrypt defines a Decrypter instance.
	Decrypt = crypto.NewDecrypter()

	// Sign defines a Signer instance.
	Sign = crypto.NewSigner()
	// Verify defines a Verifier instance.
	Verify = crypto.NewVerifier()
)