crypto/grsa/README.md
Package grsa provides useful API for RSA encryption/decryption algorithms within the GoFrame framework.
This package provides two padding schemes for RSA encryption:
Used by Encrypt*, DecryptPKCS1*, DecryptPKCS8* functions.
⚠️ Security Warning: PKCS#1 v1.5 padding is considered less secure and vulnerable to padding oracle attacks. It is provided for backward compatibility with existing systems.
Used by EncryptOAEP*, DecryptOAEP* functions.
✅ Recommended: OAEP (Optimal Asymmetric Encryption Padding) provides better security guarantees and should be used for all new applications.
package main
import (
"fmt"
"github.com/gogf/gf/v2/crypto/grsa"
)
func main() {
// Generate a default RSA key pair (2048 bits)
privateKey, publicKey, err := grsa.GenerateDefaultKeyPair()
if err != nil {
panic(err)
}
// Data to encrypt
plainText := []byte("Hello, World!")
// Encrypt with public key using OAEP (recommended)
cipherText, err := grsa.EncryptOAEP(plainText, publicKey)
if err != nil {
panic(err)
}
// Decrypt with private key using OAEP
decryptedText, err := grsa.DecryptOAEP(cipherText, privateKey)
if err != nil {
panic(err)
}
fmt.Println(string(decryptedText)) // Output: Hello, World!
}
package main
import (
"fmt"
"github.com/gogf/gf/v2/crypto/grsa"
)
func main() {
// Generate a default RSA key pair (2048 bits)
privateKey, publicKey, err := grsa.GenerateDefaultKeyPair()
if err != nil {
panic(err)
}
// Data to encrypt
plainText := []byte("Hello, World!")
// Encrypt with public key (PKCS#1 v1.5 - legacy)
cipherText, err := grsa.Encrypt(plainText, publicKey)
if err != nil {
panic(err)
}
// Decrypt with private key
decryptedText, err := grsa.Decrypt(cipherText, privateKey)
if err != nil {
panic(err)
}
fmt.Println(string(decryptedText)) // Output: Hello, World!
}
package main
import (
"encoding/base64"
"fmt"
"github.com/gogf/gf/v2/crypto/grsa"
)
func main() {
// Generate a key pair
privateKey, publicKey, err := grsa.GenerateDefaultKeyPair()
if err != nil {
panic(err)
}
// Encode keys to Base64
privateKeyBase64 := base64.StdEncoding.EncodeToString(privateKey)
publicKeyBase64 := base64.StdEncoding.EncodeToString(publicKey)
// Data to encrypt
plainText := []byte("Hello, Base64 World!")
// Encrypt with Base64 encoded public key using OAEP (recommended)
cipherTextBase64, err := grsa.EncryptOAEPBase64(plainText, publicKeyBase64)
if err != nil {
panic(err)
}
// Decrypt with Base64 encoded private key using OAEP
decryptedText, err := grsa.DecryptOAEPBase64(cipherTextBase64, privateKeyBase64)
if err != nil {
panic(err)
}
fmt.Println(string(decryptedText)) // Output: Hello, Base64 World!
}
GenerateKeyPair(bits int): Generates a new RSA key pair with the given bits in PKCS#1 formatGenerateKeyPairPKCS8(bits int): Generates a new RSA key pair with the given bits in PKCS#8 formatGenerateDefaultKeyPair(): Generates a new RSA key pair with default bits (2048) in PKCS#1 formatEncryptOAEP(plainText, publicKey []byte): Encrypts data with public key using OAEP padding (SHA-256)DecryptOAEP(cipherText, privateKey []byte): Decrypts data with private key using OAEP padding (SHA-256)EncryptOAEPBase64(plainText []byte, publicKeyBase64 string): Encrypts data with OAEP and returns base64-encoded resultDecryptOAEPBase64(cipherTextBase64, privateKeyBase64 string): Decrypts base64-encoded OAEP dataEncryptOAEPWithHash(plainText, publicKey, label []byte, hash hash.Hash): Encrypts with custom hash functionDecryptOAEPWithHash(cipherText, privateKey, label []byte, hash hash.Hash): Decrypts with custom hash functionEncrypt(plainText, publicKey []byte): Encrypts data with public key (auto-detect format)Decrypt(cipherText, privateKey []byte): Decrypts data with private key (auto-detect format)EncryptBase64(plainText []byte, publicKeyBase64 string): Encrypts data with base64-encoded public key and returns base64-encoded resultDecryptBase64(cipherTextBase64, privateKeyBase64 string): Decrypts base64-encoded data with base64-encoded private keyEncryptPKCS1(plainText, publicKey []byte): Encrypts data with PKCS#1 format public keyDecryptPKCS1(cipherText, privateKey []byte): Decrypts data with PKCS#1 format private keyEncryptPKCS1Base64(plainText []byte, publicKeyBase64 string): Encrypts data with PKCS#1 public key and returns base64-encoded resultDecryptPKCS1Base64(cipherTextBase64, privateKeyBase64 string): Decrypts base64-encoded data with PKCS#1 private keyPKIX (X.509) is the standard format for public keys, used with PKCS#8 private keys.
EncryptPKIX(plainText, publicKey []byte): Encrypts data with PKIX format public keyEncryptPKIXBase64(plainText []byte, publicKeyBase64 string): Encrypts data with PKIX public key and returns base64-encoded resultDecryptPKCS8(cipherText, privateKey []byte): Decrypts data with PKCS#8 format private keyDecryptPKCS8Base64(cipherTextBase64, privateKeyBase64 string): Decrypts base64-encoded data with PKCS#8 private keyThe following functions are deprecated and will be removed in future versions:
EncryptPKCS8(plainText, publicKey []byte): Use EncryptPKIX insteadEncryptPKCS8Base64(plainText []byte, publicKeyBase64 string): Use EncryptPKIXBase64 insteadGetPrivateKeyType(privateKey []byte): Detects the type of private key (PKCS#1 or PKCS#8)GetPrivateKeyTypeBase64(privateKeyBase64 string): Detects the type of base64 encoded private keyExtractPKCS1PublicKey(privateKey []byte): Extracts PKCS#1 public key from PKCS#1 private keyThe package supports two popular RSA key formats:
PKCS#1: Traditional RSA key format
-----BEGIN RSA PRIVATE KEY----------BEGIN RSA PUBLIC KEY-----PKCS#8/PKIX: More modern and flexible key format
-----BEGIN PRIVATE KEY----------BEGIN PUBLIC KEY-----Both formats are supported for encryption and decryption operations, with auto-detection capabilities for general functions.
PKCS#8 is a standard for private keys only, not public keys. Public keys use the PKIX (X.509 SubjectPublicKeyInfo) format.
| Format | Private Key PEM Header | Public Key PEM Header |
|---|---|---|
| PKCS#1 | RSA PRIVATE KEY | RSA PUBLIC KEY |
| PKCS#8/PKIX | PRIVATE KEY | PUBLIC KEY |
When we refer to a "PKCS#8 key pair", it actually means:
This is why the Go standard library provides x509.MarshalPKCS8PrivateKey for private keys but x509.MarshalPKIXPublicKey for public keys — there is no MarshalPKCS8PublicKey function.
The deprecated EncryptPKCS8 function was a misnomer because encryption uses public keys, and public keys are in PKIX format, not PKCS#8. The correct function name is EncryptPKIX.
RSA encryption has a size limit based on key size and padding scheme.
If you need to encrypt larger data, consider using hybrid encryption (RSA + AES).
All functions return descriptive errors that can be handled using the GoFrame error package (gerror). Errors typically include:
Always check for errors in production code to ensure robust handling of edge cases.
Run the package tests with:
go test -v