dongle

repository·master·Indexed 22 days ago

A semantic, developer-friendly Go cryptography package providing high-level APIs for encoding, hashing, symmetric (AES) and asymmetric (RSA) encryption, and digital signatures. It features global instances for common operations and supports 100% unit test coverage. Requires Go version >= 1.23.

Tokens: 4.8K
Snippets: 15
Records: 16
Agent score: 73%

What's inside dongle

Install Dongle
master
Dongle requires go version >= 1.23. You can install it using any of the following providers:
GitHub:
```
go get -u github.com/dromara/dongle
```
Gitee:
```
go get -u gitee.com/dromara/dongle
```
GitCode:
```
go get -u gitcode.com/dromara/dongle
```
Note on Repository Migration: Dongle was donated to the dromara open-source organization. If your project uses the old path github.com/golang-module/dongle, you should update your go.mod or run the following command to replace it with the new path:
```
go mod edit -replace github.com/golang-module/dongle = github.com/dromara/dongle
```
```
go get -u github.com/dromara/dongle
```
https://github.com/dromara/dongle/blob/master/README.ja.md
Use the dongle package entrypoint for crypto and coding operations
master
The dongle package provides a high-level, developer-friendly entrypoint for common cryptographic and data encoding tasks. Instead of managing individual sub-packages, you can use the exported global instances to perform encoding, hashing, encryption, and signing.
Available global instances:
- coding.Encode / coding.Decode: For data encoding and decoding.
- hash.Hash: For generating cryptographic hashes.
- crypto.Encrypt / crypto.Decrypt: For symmetric or asymmetric encryption/decryption.
- crypto.Sign / crypto.Verify: For digital signatures and verification.
```
package main

import "github.com/dromara/dongle"

func main() {
    // Example of using the global instances
    // Note: Actual method calls depend on the sub-package implementations
    _ = dongle.Encode
    _ = dongle.Hash
    _ = dongle.Encrypt
    _ = dongle.Sign
}
```
https://github.com/dromara/dongle/blob/master/dongle.go
Migrate from golang-module/dongle to dromara/dongle
master
Dongle has been donated to the dromara open-source organization. If your project previously used github.com/golang-module/dongle, you must update your go.mod file or use the go mod edit command to replace the old path with the new one.
```
go mod edit -replace github.com/golang-module/dongle = github.com/dromara/dongle
```
https://github.com/dromara/dongle/blob/master/README.cn.md

Symmetric Encryption and Decryption (AES)

master

For symmetric encryption, use cipher.NewAesCipher to create a cipher instance, configure the key, IV, and padding, and then use dongle.Encrypt or dongle.Decrypt.

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

// 1. Create the cipher (e.g., AES-CBC)
c := cipher.NewAesCipher(cipher.CBC)

// 2. Configure Key (16 bytes) and IV (16 bytes)
c.SetKey([]byte("dongle1234567890")) 
c.SetIV([]byte("1234567890123456"))

// 3. Set Padding (Required for CBC/ECB modes)
c.SetPadding(cipher.PKCS7)

// --- Encryption ---
// Encrypt to Hex
dongle.Encrypt.FromString("hello world").ByAes(c).ToHexString() // 48c6bc076e1da2946e1c0e59e9c91ae9
// Encrypt to Base64
dongle.Encrypt.FromString("hello world").ByAes(c).ToBase64String() // SMa8B24dopRuHA5Z6cka6Q==

// --- Decryption ---
// Decrypt from Hex
dongle.Decrypt.FromHexString("48c6bc076e1da2946e1c0e59e9c91ae9").ByAes(c).ToString() // hello world
// Decrypt from Base64
dongle.Decrypt.FromBase64String("SMa8B24dopRuHA5Z6cka6Q==").ByAes(c).ToString() // hello world

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

c := cipher.NewAesCipher(cipher.CBC)
c.SetKey([]byte("dongle1234567890")) 
c.SetIV([]byte("1234567890123456"))
c.SetPadding(cipher.PKCS7)

dongle.Encrypt.FromString("hello world").ByAes(c).ToHexString()
dongle.Decrypt.FromHexString("48c6bc076e1da2946e1c0e59e9c91ae9").ByAes(c).ToString()

Encode and Decode data (Base64)

master

Use dongle.Encode and dongle.Decode for simple encoding/decoding tasks. For example, to perform Base64 encoding and decoding:

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

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

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

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

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

Asymmetric Encryption and Decryption (RSA)

master

Use keypair.NewRsaKeyPair to manage RSA keys. You can configure the key format (e.g., PKCS8), padding (e.g., OAEP or PKCS1v15), and the hash algorithm.

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

// 1. Setup KeyPair
kp := keypair.NewRsaKeyPair()
kp.SetFormat(keypair.PKCS8)
kp.SetPadding(keypair.OAEP) 
kp.SetHash(crypto.SHA256)

// 2. Encryption with Public Key
kp.SetPublicKey([]byte("MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqzZNa9VrcewyU6wDoV7Y9kAHqX1VK0B3Rb6GNmQe4zLEfce7cVTaLrc4VGTKl35tADG1cRHqtaG4S/WttpiGZBhxJy4MpOXb6eIPiVLsn2lL+rJo5XdbSr3gyjxEOQQ97ihtw4lDd5wMo4bIOuw1LtMezHC1outlM6x+/BB0BSQIDAQAB"))
dongle.Encrypt.FromString("hello world").ByRsa(kp).ToHexString()

// 3. Decryption with Private Key
kp.SetPrivateKey([]byte("MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAKrNk1r1Wtx7DJTrAOhXtj2QAepfVUrQHdFvoY2ZB7jMsR9x7txVNoutzhUZMqXfm0AMbVxEeq1obhL9a22mIZkGHEnLgyk5dvp4g+JUuyfaUv6smjld1tKveDKPEQ5BD3uKG3DiUN3nAyjhsg67DUu0x7McLWi62UzrH78EHQFJAgMBAAECgYAeo3nHWzPNURVUsUMcan96U5bEYA2AugxfQVMNf2HvOGidZ2adh3udWrQY/MglERNcTd5gKriG2rDEH0liBecIrNKsBL4lV+qHEGRUcnDDdtUBdGInEU8lve5keDgmX+/huXSRJ+3tYA5u9j+32RquVczvIdtb5XnBLUl61k0osQJBAON5+eJjtw6xpn+pveU92BSHvaJYVyrLHwUjR07aNKb7GlGVM3MGf1FCa8WQUo9uUzYxGLtg5Qf3sqwOrwPd5UsCQQDAOF/zWqGuY3HfV/1wgiXiWp8rc+S8tanMj5M37QQbYW5YLjUmJImoklVahv3qlgLZdEN5ZSueM5jfoSFtNts7AkBKoRDvSiGbi4MBbTHkzLZgfewkH/FxE7S4nctePk553fXTgCyh9ya8BRuQdHnxnpNkOxVPHEnnpEcVFbgrf5gjAkB7KmRI4VTiEfRgINhTJAG0VU7SH/N7+4cufPzfA+7ywG5c8Fa79wOB0SoB1KeUjcSLo5Ssj2fwea1F9dAeU90LAkBJQFofveaDa3YlN4EQZOcCvJKmg7xwWuGxFVTZDVVEws7UCQbEOEEXZrNd9x0IF5kpPLR+rxuaRPgUNaDGIh5o"))
dongle.Decrypt.FromHexString("7fae94fd1a8b880d8d5454dd8df30c40...").ByRsa(kp).ToString()

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

kp := keypair.NewRsaKeyPair()
kp.SetFormat(keypair.PKCS8)
kp.SetPadding(keypair.OAEP) 
kp.SetHash(crypto.SHA256)

kp.SetPublicKey([]byte("..."))
dongle.Encrypt.FromString("hello world").ByRsa(kp).ToHexString()

kp.SetPrivateKey([]byte("..."))
dongle.Decrypt.FromHexString("...").ByRsa(kp).ToString()

Digital Signatures and Verification (RSA)

master

Use dongle.Sign to create a signature and dongle.Verify to validate it using an RSA key pair.

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

// 1. Setup KeyPair for Signing
kp := keypair.NewRsaKeyPair()
kp.SetFormat(keypair.PKCS8)
kp.SetPadding(keypair.PSS) // Use PSS for signatures
kp.SetHash(crypto.SHA256)

// 2. Sign with Private Key
kp.SetPrivateKey([]byte("..."))
hexSign := dongle.Sign.FromString("hello world").ByRsa(kp).ToHexBytes()
base64Sign := dongle.Sign.FromString("hello world").ByRsa(kp).ToBase64Bytes()

// 3. Verify with Public Key
kp.SetPublicKey([]byte("..."))
// Verify Hex signature
isValidHex := dongle.Verify.FromString("hello world").WithHexSign(hexSign).ByRsa(kp).ToBool()
// Verify Base64 signature
isValidBase64 := dongle.Verify.FromString("hello world").WithBase64Sign(base64Sign).ByRsa(kp).ToBool()

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

kp := keypair.NewRsaKeyPair()
kp.SetFormat(keypair.PKCS8)
kp.SetPadding(keypair.PSS) 
kp.SetHash(crypto.SHA256)

kp.SetPrivateKey([]byte("..."))
hexBytes := dongle.Sign.FromString("hello world").ByRsa(kp).ToHexBytes()

kp.SetPublicKey([]byte("..."))
dongle.Verify.FromString("hello world").WithHexSign(hexBytes).ByRsa(kp).ToBool()

Asymmetric Encryption (RSA)

master

Use keypair.NewRsaKeyPair to manage RSA keys and dongle.Encrypt/Decrypt for operations. You can configure the key format (e.g., PKCS8), padding (e.g., OAEP or PSS), and hash algorithm.

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

// 1. Setup KeyPair
kp := keypair.NewRsaKeyPair()
kp.SetFormat(keypair.PKCS8)
kp.SetPadding(keypair.OAEP)
kp.SetHash(crypto.SHA256)

// 2. Set Public Key for Encryption
kp.SetPublicKey([]byte("MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqzZNa9VrcewyU6wDoV7Y9kAHqX1VK0B3Rb6GNmQe4zLEfce7cVTaLrc4VGTKl35tADG1cRHqtaG4S/WttpiGZBhxJy4MpOXb6eIPiVLsn2lL+rJo5XdbSr3gyjxEOQQ97ihtw4lDd5wMo4bIOuw1LtMezHC1outlM6x+/BB0BSQIDAQAB"))
dongle.Encrypt.FromString("hello world").ByRsa(kp).ToHexString()

// 3. Set Private Key for Decryption
kp.SetPrivateKey([]byte("MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAKrNk1r1Wtx7DJTrAOhXtj2QAepfVUrQHdFvoY2ZB7jMsR9x7txVNoutzhUZMqXfm0AMbVxEeq1obhL9a22mIZkGHEnLgyk5dvp4g+JUuyfaUv6smjld1tKveDKPEQ5BD3uKG3DiUN3nAyjhsg67DUu0x7McLWi62UzrH78EHQFJAgMBAAECgYAeo3nHWzPNURVUsUMcan96U5bEYA2AugxfQVMNf2HvOGidZ2adh3udWrQY/MglERNcTd5gKriG2rDEH0liBecIrNKsBL4lV+qHEGRUcnDDdtUBdGInEU8lve5keDgmX+/huXSRJ+3tYA5u9j+32RquVczvIdtb5XnBLUl61k0osQJBAON5+eJjtw6xpn+pveU92BSHvaJYVyrLHwUjR07aNKb7GlGVM3MGf1FCa8WQUo9uUzYxGLtg5Qf3sqwOrwPd5UsCQQDAOF/zWqGuY3HfV/1wgiXiWp8rc+S8tanMj5M37QQbYW5YLjUmJImoklVahv3qlgLZdEN5ZSueM5jfoSFtNts7AkBKoRDvSiGbi4MBbTHkzLZgfewkH/FxE7S4nctePk553fXTgCyh9ya8BRuQdHnxnpNkOxVPHEnnpEcVFbgrf5gjAkB7KmRI4VTiEfRgINhTJAG0VU7SH/N7+4cufPzfA+7ywG5c8Fa79wOB0SoB1KeUjcSLo5Ssj2fwea1F9dAeU90LAkBJQFofveaDa3YlN4EQZOcCvJKmg7xwWuGxFVTZDVVEws7UCQbEOEEXZrNd9x0IF5kpPLR+rxuaRPgUNaDGIh5o"))
dongle.Decrypt.FromHexString("7fae94fd1a8b880d8d5454dd8df30c40...").ByRsa(kp).ToString()

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

kp := keypair.NewRsaKeyPair()
kp.SetFormat(keypair.PKCS8)
kp.SetPadding(keypair.OAEP)
kp.SetHash(crypto.SHA256)

kp.SetPublicKey([]byte("MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqzZNa9VrcewyU6wDoV7Y9kAHqX1VK0B3Rb6GNmQe4zLEfce7cVTaLrc4VGTKl35tADG1cRHqtaG4S/WttpiGZBhxJy4MpOXb6eIPiVLsn2lL+rJo5XdbSr3gyjxEOQQ97ihtw4lDd5wMo4bIOuw1LtMezHC1outlM6x+/BB0BSQIDAQAB"))
dongle.Encrypt.FromString("hello world").ByRsa(kp).ToHexString()

kp.SetPrivateKey([]byte("MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAKrNk1r1Wtx7DJTrAOhXtj2QAepfVUrQHdFvoY2ZB7jMsR9x7txVNoutzhUZMqXfm0AMbVxEeq1obhL9a22mIZkGHEnLgyk5dvp4g+JUuyfaUv6smjld1tKveDKPEQ5BD3uKG3DiUN3nAyjhsg67DUu0x7McLWi62UzrH78EHQFJAgMBAAECgYAeo3nHWzPNURVUsUMcan96U5bEYA2AugxfQVMNf2HvOGidZ2adh3udWrQY/MglERNcTd5gKriG2rDEH0liBecIrNKsBL4lV+qHEGRUcnDDdtUBdGInEU8lve5keDgmX+/huXSRJ+3tYA5u9j+32RquVczvIdtb5XnBLUl61k0osQJBAON5+eJjtw6xpn+pveU92BSHvaJYVyrLHwUjR07aNKb7GlGVM3MGf1FCa8WQUo9uUzYxGLtg5Qf3sqwOrwPd5UsCQQDAOF/zWqGuY3HfV/1wgiXiWp8rc+S8tanMj5M37QQbYW5YLjUmJImoklVahv3qlgLZdEN5ZSueM5jfoSFtNts7AkBKoRDvSiGbi4MBbTHkzLZgfewkH/FxE7S4nctePk553fXTgCyh9ya8BRuQdHnxnpNkOxVPHEnnpEcVFbgrf5gjAkB7KmRI4VTiEfRgINhTJAG0VU7SH/N7+4cufPzfA+7ywG5c8Fa79wOB0SoB1KeUjcSLo5Ssj2fwea1F9dAeU90LAkBJQFofveaDa3YlN4EQZOcCvJKmg7xwWuGxFVTZDVVEws7UCQbEOEEXZrNd9x0IF5kpPLR+rxuaRPgUNaDGIh5o"))
dongle.Decrypt.FromHexString("7fae94fd1a8b880d8d5454dd8df30c40...").ByRsa(kp).ToString()

Encode and Decode strings (e.g., Base64)

master

Use dongle.Encode and dongle.Decode for semantic encoding and decoding operations. For example, to perform Base64 encoding/decoding:

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

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

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

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

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

Hash and HMAC algorithms

master

Generate hashes or HMACs using dongle.Hash. You can specify the algorithm (e.g., ByMd5()) and the output format (ToHexString() or ToBase64String()). For HMAC, use WithKey() to provide the secret key.

Hashing Example (MD5):

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

HMAC Example (MD5):

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

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

dongle.Hash.FromString("hello world").ByMd5().ToHexString()    // 5eb63bbbe01eeed093cb22bb8f5acdc3
dongle.Hash.FromString("hello world").WithKey([]byte("dongle")).ByMd5().ToHexString()    // 4790626a275f776956386e5a3ea7b726

Generate Hashes (MD5)

master

Use dongle.Hash to generate message digests. You can output the result as a Hex string or a Base64 string.

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

// MD5 Hash to Hex
dongle.Hash.FromString("hello world").ByMd5().ToHexString()    // 5eb63bbbe01eeed093cb22bb8f5acdc3

// MD5 Hash to Base64
dongle.Hash.FromString("hello world").ByMd5().ToBase64String() // XrY7u+Ae7tCTyyK7j1rNww==

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

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

Encode and Decode data

master

Use dongle.Encode and dongle.Decode for semantic encoding/decoding operations. For example, using Base64:

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

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

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

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

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