keypair

package
v1.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 8, 2025 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package keypair provides cryptographic key pair management for multiple algorithms.

It supports key generation, parsing, formatting, and manipulation for:

  • RSA: Supports PKCS1 and PKCS8 key formats, with configurable padding schemes
  • SM2: Supports PKCS8/PKIX formats with configurable ciphertext order
  • Ed25519: Supports PKCS8 format

Each key pair type provides methods for:

  • Generating new key pairs
  • Parsing keys from PEM format
  • Formatting keys to PEM format
  • Setting algorithm-specific parameters

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Ed25519KeyPair added in v1.1.1 

type Ed25519KeyPair struct {
	// PublicKey contains the PEM-encoded public key
	PublicKey []byte

	// PrivateKey contains the PEM-encoded private key
	PrivateKey []byte

	// Signature contains the signature bytes for verification
	Signature []byte
}

Ed25519KeyPair represents an ED25519 key pair with public and private keys. It supports PKCS8 format and provides methods for key generation, formatting, and parsing.

func NewEd25519KeyPair added in v1.1.1 

func NewEd25519KeyPair() *Ed25519KeyPair

NewEd25519KeyPair returns a new Ed25519KeyPair instance.

func (*Ed25519KeyPair) CompressPrivateKey added in v1.2.0 

func (k *Ed25519KeyPair) CompressPrivateKey(privateKey []byte) []byte

CompressPrivateKey removes the PEM headers and footers from the private key. It supports PKCS8 format and removes all whitespace characters. The resulting byte slice contains only the base64-encoded key data.

func (*Ed25519KeyPair) CompressPublicKey added in v1.2.0 

func (k *Ed25519KeyPair) CompressPublicKey(publicKey []byte) []byte

CompressPublicKey removes the PEM headers and footers from the public key. It supports PKCS8 format and removes all whitespace characters. The resulting byte slice contains only the base64-encoded key data.

func (*Ed25519KeyPair) FormatPrivateKey added in v1.2.0 

func (k *Ed25519KeyPair) FormatPrivateKey(privateKey []byte) ([]byte, error)

FormatPrivateKey formats base64-encoded der private key into the specified PEM format.

func (*Ed25519KeyPair) FormatPublicKey added in v1.2.0 

func (k *Ed25519KeyPair) FormatPublicKey(publicKey []byte) ([]byte, error)

FormatPublicKey formats base64-encoded der public key into the specified PEM format.

func (*Ed25519KeyPair) GenKeyPair added in v1.1.1 

func (k *Ed25519KeyPair) GenKeyPair() error

GenKeyPair generates a new Ed25519KeyPair instance. The generated keys are formatted in PEM format using PKCS8 format.

Note: The generated keys are automatically formatted in PEM format using PKCS8 format.

func (*Ed25519KeyPair) ParsePrivateKey added in v1.1.1 

func (k *Ed25519KeyPair) ParsePrivateKey() (ed25519.PrivateKey, error)

ParsePrivateKey parses the private key from PEM format and returns a Go crypto/ed25519.PrivateKey. It supports PKCS8 format.

Note: This method automatically detects the key format from the PEM headers.

func (*Ed25519KeyPair) ParsePublicKey added in v1.1.1 

func (k *Ed25519KeyPair) ParsePublicKey() (ed25519.PublicKey, error)

ParsePublicKey parses the public key from PEM format and returns a Go crypto/ed25519.PublicKey. It supports PKCS8 format.

Note: This method automatically detects the key format from the PEM headers.

func (*Ed25519KeyPair) SetPrivateKey added in v1.1.1 

func (k *Ed25519KeyPair) SetPrivateKey(privateKey []byte) error

SetPrivateKey sets the private key and formats it in PKCS8 format. The input key is expected to be in PEM format and will be reformatted if necessary.

func (*Ed25519KeyPair) SetPublicKey added in v1.1.1 

func (k *Ed25519KeyPair) SetPublicKey(publicKey []byte) error

SetPublicKey sets the public key and formats it in PKCS8 format. The input key is expected to be in PEM format and will be reformatted if necessary.

type EmptyFormatError added in v1.2.2 

type EmptyFormatError struct {
}

func (EmptyFormatError) Error added in v1.2.2 

func (e EmptyFormatError) Error() string

type EmptyPaddingError added in v1.2.2 

type EmptyPaddingError struct {
}

func (EmptyPaddingError) Error added in v1.2.2 

func (e EmptyPaddingError) Error() string

type EmptyPrivateKeyError added in v1.2.0 

type EmptyPrivateKeyError struct {
}

func (EmptyPrivateKeyError) Error added in v1.2.0 

func (e EmptyPrivateKeyError) Error() string

type EmptyPublicKeyError added in v1.2.0 

type EmptyPublicKeyError struct {
}

func (EmptyPublicKeyError) Error added in v1.2.0 

func (e EmptyPublicKeyError) Error() string

type EmptySignatureError added in v1.2.2 

type EmptySignatureError struct {
}

func (EmptySignatureError) Error added in v1.2.2 

func (e EmptySignatureError) Error() string

type InvalidPrivateKeyError 

type InvalidPrivateKeyError struct {
	Err error
}

func (InvalidPrivateKeyError) Error 

func (e InvalidPrivateKeyError) Error() string

type InvalidPublicKeyError 

type InvalidPublicKeyError struct {
	Err error
}

func (InvalidPublicKeyError) Error 

func (e InvalidPublicKeyError) Error() string

type RsaKeyFormat added in v1.2.2 

type RsaKeyFormat string

RsaKeyFormat represents the PEM encoding format for RSA keys. This ONLY affects key generation (GenKeyPair) and determines the PEM header.

IMPORTANT: RsaKeyFormat does NOT affect encryption/decryption/signing operations. For cryptographic operations, use RsaPaddingScheme instead.

Key parsing (ParsePublicKey/ParsePrivateKey) automatically detects the format from PEM headers, so this field is not used during parsing. 

const (
	// PKCS1 generates keys with RSA-specific PEM headers.
	// - Private key: "-----BEGIN RSA PRIVATE KEY-----"
	// - Public key: "-----BEGIN RSA PUBLIC KEY-----"
	// - Usage: Legacy compatibility, OpenSSL traditional format
	PKCS1 RsaKeyFormat = "pkcs1"

	// PKCS8 generates keys with generic PEM headers (recommended).
	// - Private key: "-----BEGIN PRIVATE KEY-----"
	// - Public key: "-----BEGIN PUBLIC KEY-----"
	// - Usage: Modern standard, works with multiple key algorithms
	PKCS8 RsaKeyFormat = "pkcs8"
)

Key format constants for RSA key pairs.

type RsaKeyPair 

type RsaKeyPair struct {
	// PublicKey contains the PEM-encoded public key
	PublicKey []byte

	// PrivateKey contains the PEM-encoded private key
	PrivateKey []byte

	// Signature contains the signature bytes for verification
	Signature []byte

	// Format specifies the key format for PEM encoding.
	// This field affects:
	//   - GenKeyPair(): PEM header format when generating keys
	//   - FormatPublicKey(): PEM header format when formatting public keys
	//   - FormatPrivateKey(): PEM header format when formatting private keys
	// It does NOT affect cryptographic operations.
	Format RsaKeyFormat

	// Padding specifies the padding scheme for RSA cryptographic operations.
	// This field affects encryption, decryption, signing, and verification algorithms.
	//
	// Available padding schemes:
	// - PKCS1v15: Can be used for both encryption and signing operations
	// - OAEP: ONLY for encryption/decryption (error if used for signing/verification)
	// - PSS: ONLY for signing/verification (error if used for encryption/decryption)
	//
	// Note: Padding is independent from Format. You can use any padding with any key format.
	Padding RsaPaddingScheme

	// Hash specifies the hash function used for RSA cryptographic operations.
	// Usage depends on the Padding scheme:
	// - PKCS1v15: Used for hashing message data before signing
	// - OAEP: Used for mask generation in encryption/decryption
	// - PSS: Used for mask generation in signing/verification
	Hash crypto.Hash
}

RsaKeyPair represents an RSA key pair with public and private keys. It supports both PKCS1 and PKCS8 key formats and provides methods for key generation, formatting, and parsing.

func NewRsaKeyPair 

func NewRsaKeyPair() *RsaKeyPair

NewRsaKeyPair returns a new RsaKeyPair instance with default settings. For explicit security requirements:

  • For encryption: kp.SetPadding(keypair.OAEP)
  • For signing: kp.SetPadding(keypair.PSS)
  • For both: kp.SetPadding(keypair.PKCS1v15)

func (*RsaKeyPair) CompressPrivateKey added in v1.2.0 

func (k *RsaKeyPair) CompressPrivateKey(privateKey []byte) []byte

CompressPrivateKey removes the PEM headers and footers from the private key. It supports both PKCS1 and PKCS8 formats and removes all whitespace characters. The resulting byte slice contains only the base64-encoded key data.

func (*RsaKeyPair) CompressPublicKey added in v1.2.0 

func (k *RsaKeyPair) CompressPublicKey(publicKey []byte) []byte

CompressPublicKey removes the PEM headers and footers from the public key. It supports both PKCS1 and PKCS8 formats and removes all whitespace characters. The resulting byte slice contains only the base64-encoded key data.

func (*RsaKeyPair) FormatPrivateKey added in v1.2.0 

func (k *RsaKeyPair) FormatPrivateKey(privateKey []byte) ([]byte, error)

FormatPrivateKey formats base64-encoded der private key into the specified PEM format.

func (*RsaKeyPair) FormatPublicKey added in v1.2.0 

func (k *RsaKeyPair) FormatPublicKey(publicKey []byte) ([]byte, error)

FormatPublicKey formats base64-encoded der public key into the specified PEM format.

func (*RsaKeyPair) GenKeyPair 

func (k *RsaKeyPair) GenKeyPair(size int) error

GenKeyPair generates a new RsaKeyPair with the specified key size. The generated keys are formatted according to the current Format setting.

Note: The generated keys are automatically formatted in PEM format according to the current Format setting (PKCS1 or PKCS8).

func (*RsaKeyPair) ParsePrivateKey 

func (k *RsaKeyPair) ParsePrivateKey() (*rsa.PrivateKey, error)

ParsePrivateKey parses the private key from PEM format. It supports both PKCS1 and PKCS8 formats automatically.

Note: This method automatically detects the key format from the PEM headers.

func (*RsaKeyPair) ParsePublicKey 

func (k *RsaKeyPair) ParsePublicKey() (*rsa.PublicKey, error)

ParsePublicKey parses the public key from PEM format. It supports both PKCS1 and PKCS8 formats automatically.

Note: This method automatically detects the key format from the PEM headers.

func (*RsaKeyPair) SetFormat 

func (k *RsaKeyPair) SetFormat(format RsaKeyFormat)

SetFormat sets the key format for the RSA key pair. This affects:

  • GenKeyPair(): Determines the PEM header format when generating keys
  • FormatPublicKey(): Determines the PEM header format when formatting public keys
  • FormatPrivateKey(): Determines the PEM header format when formatting private keys

func (*RsaKeyPair) SetHash 

func (k *RsaKeyPair) SetHash(hash crypto.Hash)

SetHash sets the hash function used for OAEP padding in RSA operations.

func (*RsaKeyPair) SetPadding added in v1.2.2 

func (k *RsaKeyPair) SetPadding(padding RsaPaddingScheme)

SetPadding sets the padding scheme for RSA cryptographic operations.

Padding schemes:

  • PKCS1v15: Can be used for both encryption and signing
  • OAEP: ONLY for encryption (returns error if used for signing)
  • PSS: ONLY for signing (returns error if used for encryption)

func (*RsaKeyPair) SetPrivateKey 

func (k *RsaKeyPair) SetPrivateKey(privateKey []byte) error

SetPrivateKey sets the private key and formats it according to the current format. The input key is expected to be in PEM format and will be reformatted if necessary.

func (*RsaKeyPair) SetPublicKey 

func (k *RsaKeyPair) SetPublicKey(publicKey []byte) error

SetPublicKey sets the public key and formats it according to the current format. The input key is expected to be in PEM format and will be reformatted if necessary.

type RsaPaddingScheme added in v1.2.2 

type RsaPaddingScheme string

RsaPaddingScheme represents the padding scheme for RSA cryptographic operations.

Different padding schemes are used for different operations: - PKCS1v15: Can be used for both encryption and signing - OAEP: Only for encryption (more secure than PKCS1v15) - PSS: Only for signing (more secure than PKCS1v15) 

const (
	// PKCS1v15 uses PKCS#1 v1.5 padding for RSA operations.
	// - For encryption/decryption: rsa.EncryptPKCS1v15 / rsa.DecryptPKCS1v15
	// - For signing/verification: rsa.SignPKCS1v15 / rsa.VerifyPKCS1v15
	// - Compatibility: Works with JSEncrypt, PHP openssl_* defaults
	// - Security: Adequate for most applications, widely supported
	// - Usage: Can be used for both encryption and signing operations
	PKCS1v15 RsaPaddingScheme = "pkcs1v15"

	// OAEP uses Optimal Asymmetric Encryption Padding (more secure).
	// - For encryption/decryption: rsa.EncryptOAEP / rsa.DecryptOAEP
	// - Compatibility: Modern standard, may not work with older libraries
	// - Security: Recommended for encryption in new applications
	// - Usage: ONLY for encryption/decryption operations
	//
	// Note: Attempting to use OAEP for signing/verification will return an error.
	// For signing, use PKCS1v15 or PSS instead.
	OAEP RsaPaddingScheme = "oaep"

	// PSS uses Probabilistic Signature Scheme (more secure for signing).
	// - For signing/verification: rsa.SignPSS / rsa.VerifyPSS
	// - Compatibility: Modern standard, may not work with older libraries
	// - Security: Recommended for signing in new applications
	// - Usage: ONLY for signing/verification operations
	//
	// Note: Attempting to use PSS for encryption/decryption will return an error.
	// For encryption, use PKCS1v15 or OAEP instead.
	PSS RsaPaddingScheme = "pss"
)

type Sm2CipherOrder added in v1.2.2 

type Sm2CipherOrder string

Sm2CipherOrder specifies the concatenation order of SM2 ciphertext components. It controls how the library assembles (encrypt) and interprets (decrypt) the C1, C2, C3 parts.

C1: EC point (x1||y1) in uncompressed form; C2: XORed plaintext; C3: SM3 digest over x2 || M || y2. 

const (
	// C1C2C3 means ciphertext bytes are C1 || C2 || C3.
	C1C2C3 Sm2CipherOrder = "c1c2c3"
	// C1C3C2 means ciphertext bytes are C1 || C3 || C2.
	C1C3C2 Sm2CipherOrder = "c1c3c2"
)

Supported SM2 ciphertext orders.

type Sm2KeyPair added in v1.2.0 

type Sm2KeyPair struct {
	// PublicKey contains the PEM-encoded public key
	PublicKey []byte

	// PrivateKey contains the PEM-encoded private key
	PrivateKey []byte

	Order Sm2CipherOrder
	// Window controls internal SM2 fixed-base/wNAF window size (2..6).
	// 4 means use library default.
	Window int

	// UID is the user identifier for SM2 signature operations.
	// If empty, the default UID "1234567812345678" will be used (per GM/T 0009-2012).
	UID []byte
}

Sm2KeyPair represents an SM2 key pair with public and private keys. Keys are handled in PKCS8 (for private) and PKIX (for public) PEM formats.

func NewSm2KeyPair added in v1.2.0 

func NewSm2KeyPair() *Sm2KeyPair

NewSm2KeyPair returns a new Sm2KeyPair with defaults (Order=C1C3C2, Window=4).

func (*Sm2KeyPair) CompressPrivateKey added in v1.2.0 

func (k *Sm2KeyPair) CompressPrivateKey(privateKey []byte) []byte

CompressPrivateKey strips headers/footers and whitespace from the PEM private key.

func (*Sm2KeyPair) CompressPublicKey added in v1.2.0 

func (k *Sm2KeyPair) CompressPublicKey(publicKey []byte) []byte

CompressPublicKey strips headers/footers and whitespace from the PEM public key.

func (*Sm2KeyPair) FormatPrivateKey added in v1.2.0 

func (k *Sm2KeyPair) FormatPrivateKey(privateKey []byte) ([]byte, error)

FormatPrivateKey formats base64-encoded der private key into the specified PEM format.

func (*Sm2KeyPair) FormatPublicKey added in v1.2.0 

func (k *Sm2KeyPair) FormatPublicKey(publicKey []byte) ([]byte, error)

FormatPublicKey formats base64-encoded der public key into the specified PEM format.

func (*Sm2KeyPair) GenKeyPair added in v1.2.0 

func (k *Sm2KeyPair) GenKeyPair() error

GenKeyPair generates a new SM2 key pair and fills PublicKey/PrivateKey. Private key is PKCS#8 (PEM "PRIVATE KEY"), public key is SPKI/PKIX (PEM "PUBLIC KEY").

func (*Sm2KeyPair) LoadPrivateKey added in v1.2.0 

func (k *Sm2KeyPair) LoadPrivateKey(f fs.File) error

LoadPrivateKey reads a PEM-encoded private key from a file.

func (*Sm2KeyPair) LoadPublicKey added in v1.2.0 

func (k *Sm2KeyPair) LoadPublicKey(f fs.File) error

LoadPublicKey reads a PEM-encoded public key from a file.

func (*Sm2KeyPair) ParsePrivateKey added in v1.2.0 

func (k *Sm2KeyPair) ParsePrivateKey() (*ecdsa.PrivateKey, error)

ParsePrivateKey parses the PEM-encoded private key and returns *sm2.PrivateKey.

func (*Sm2KeyPair) ParsePublicKey added in v1.2.0 

func (k *Sm2KeyPair) ParsePublicKey() (*ecdsa.PublicKey, error)

ParsePublicKey parses the PEM-encoded public key and returns *sm2.PublicKey.

func (*Sm2KeyPair) SetOrder added in v1.2.0 

func (k *Sm2KeyPair) SetOrder(order Sm2CipherOrder)

SetOrder sets ciphertext component order to C1C3C2 or C1C2C3. It affects how Encrypt assembles and Decrypt interprets ciphertext.

func (*Sm2KeyPair) SetPrivateKey added in v1.2.0 

func (k *Sm2KeyPair) SetPrivateKey(privateKey []byte) error

SetPrivateKey sets the private key after formatting to PEM. Accepts base64-encoded DER of PKCS#8 PrivateKeyInfo.

func (*Sm2KeyPair) SetPublicKey added in v1.2.0 

func (k *Sm2KeyPair) SetPublicKey(publicKey []byte) error

SetPublicKey sets the public key after formatting to PEM. Accepts base64-encoded DER of SubjectPublicKeyInfo.

func (*Sm2KeyPair) SetUID added in v1.2.2 

func (k *Sm2KeyPair) SetUID(uid []byte)

SetUID sets the user identifier for SM2 signature operations. If uid is nil or empty, the default UID "1234567812345678" will be used.

func (*Sm2KeyPair) SetWindow added in v1.2.0 

func (k *Sm2KeyPair) SetWindow(window int)

SetWindow sets scalar-multiplication window (2..6). Values outside the range are clamped.

type UnsupportedKeyFormatError added in v1.2.2 

type UnsupportedKeyFormatError struct {
}

func (UnsupportedKeyFormatError) Error added in v1.2.2 

func (e UnsupportedKeyFormatError) Error() string

type UnsupportedPaddingSchemeError added in v1.2.2 

type UnsupportedPaddingSchemeError struct {
	Padding string
}

func (UnsupportedPaddingSchemeError) Error added in v1.2.2 

func (e UnsupportedPaddingSchemeError) Error() string

Source Files

  • ed25519.go
  • errors.go
  • keypair.go
  • rsa.go
  • sm2.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.