gopkcs11

package module
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Nov 17, 2025 License: MIT Imports: 21 Imported by: 0

README

GoPKCS11

A Go wrapper for PKCS#11 (Cryptoki) operations with HSM (Hardware Security Module) support.

Features

  • Multiple Key Types: RSA, ECDSA, and ED25519 key pair support
  • Symmetric Encryption: AES encryption with CBC mode and PKCS#7 padding
  • Standard Interfaces: Implements Go's crypto.Signer and crypto.Decrypter
  • Comprehensive Testing: Full test suite with SoftHSM integration

Installation

go get github.com/yeaops/gopkcs11

Quick Start

package main

import (
    "context"
    "crypto"
    "crypto/sha256"
    "fmt"
    "time"

    "github.com/yeaops/gopkcs11"
)

func main() {
    // Configure connection to PKCS#11 device
    config := &gopkcs11.Config{
        LibraryPath:           "/usr/lib/softhsm/libsofthsm2.so",
        SlotID:                &[]uint{0}[0], // Use slot 0
        UserPIN:               "1234",
        MaxSessions:           10,
        SessionAcquireTimeout: 5 * time.Second,
    }

    // Create token connection
    token, err := gopkcs11.NewToken(config)
    if err != nil {
        panic(fmt.Sprintf("Failed to create token: %v", err))
    }
    defer token.Close()

    ctx := context.Background()

    // Generate RSA key pair
    keyPair, err := token.GenerateRSAKeyPair(ctx, "my-key", 2048)
    if err != nil {
        panic(fmt.Sprintf("Failed to generate key: %v", err))
    }

    // Use as standard crypto.Signer
    signer := keyPair.AsSigner()
    data := []byte("Hello, PKCS#11!")
    hash := sha256.Sum256(data)
    
    signature, err := signer.Sign(nil, hash[:], crypto.SHA256)
    if err != nil {
        panic(fmt.Sprintf("Failed to sign: %v", err))
    }

    fmt.Printf("Signature created: %d bytes\n", len(signature))
}

Testing

Unit Tests
# Run fast unit tests
go test -v -short ./...

# Run all tests including slower integration tests
go test -v ./...
End-to-End Tests with SoftHSM
# Install SoftHSM (automated script)
cd test/e2e/softhsm
./install-softhsmv2.sh

# Run comprehensive e2e tests
go test -v ./...

# Run specific test categories
go test -run TestRSA -v          # RSA functionality
go test -run TestConcurrent -v   # Concurrency tests
go test -bench=. -v              # Benchmarks
Custom PKCS#11 Library
# Test with your own PKCS#11 library
export PKCS11_LIBRARY_PATH="/path/to/your/pkcs11.so"
go test -v ./...

Requirements

  • Go: 1.24+ (uses iter package)
  • PKCS#11 Library: Hardware HSM or software implementation
    • SoftHSM v2.6.1+ (for testing)
    • Utimaco HSM
  • Build Tools:
    • Linux: build-essential, libssl-dev
    • macOS: Xcode tools
    • Windows: MSYS2/MinGW

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

Constants

View Source 
const (
	// AES BlockSize is 16 bytes.
	AES_BLOCK_SIZE = 16
	// DEFAULT_AES_STREAM_BUFFER_SIZE is the default buffer size for AES streaming operations.
	// It's set to AES_BLOCK_SIZE * 256 = 4096 bytes for optimal performance.
	DEFAULT_AES_STREAM_BUFFER_SIZE = AES_BLOCK_SIZE * 256
)
View Source 
const (
	CKK_EC_EDWARDS              = 0x00000040
	CKM_EC_EDWARDS_KEY_PAIR_GEN = 0x00001055
	CKM_EDDSA                   = 0x00001057
)

Additional PKCS#11 constants for ED25519 support (from PKCS#11 v3.0)

Variables

This section is empty.

Functions

func ConvertPKCS11Error 

func ConvertPKCS11Error(err error) error

ConvertPKCS11Error converts a raw PKCS#11 error into a PKCS11Error with categorized error codes. This function maps specific PKCS#11 CKR codes to more general error categories for easier handling.

func Example 

func Example()

Example demonstrates how to use the new key-type-specific implementation. This example shows the improved design where each key type has consolidated functionality.

func IsAlreadyInitializedError added in v0.0.3 

func IsAlreadyInitializedError(err error) bool

func IsAuthenticationError 

func IsAuthenticationError(err error) bool

IsAuthenticationError checks if an error is related to authentication (PIN verification, login, etc.).

func IsKeyNotFoundError 

func IsKeyNotFoundError(err error) bool

IsKeyNotFoundError checks if an error indicates that a key or object was not found.

func IsPKCS11Error 

func IsPKCS11Error(err error, code ErrorCode) bool

IsPKCS11Error checks if an error is a PKCS11Error with the specified error code.

func IsSessionError 

func IsSessionError(err error) bool

IsSessionError checks if an error is related to session management (invalid session, not initialized, etc.).

Types

type AESCBCCipher added in v0.0.2 

type AESCBCCipher struct {
	// contains filtered or unexported fields
}

AESCBCCipher implements the BlockCipher interface for AES-CBC mode. CBC mode requires an initialization vector (IV) for security.

func NewAESCBCCipher added in v0.0.2 

func NewAESCBCCipher(key *SymmetricKey, iv []byte) (*AESCBCCipher, error)

NewAESCBCCipher creates a new AES-CBC cipher with the given symmetric key and IV. The IV must be exactly 16 bytes (AES block size).

func (*AESCBCCipher) BlockSize added in v0.0.2 

func (c *AESCBCCipher) BlockSize() int

BlockSize returns the block size for AES (16 bytes).

func (*AESCBCCipher) BufferSize added in v0.0.2 

func (c *AESCBCCipher) BufferSize() int

BufferSize returns the current buffer size for streaming operations.

func (*AESCBCCipher) Decrypt added in v0.0.2 

func (c *AESCBCCipher) Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)

Decrypt decrypts the source data and returns the result. For CBC mode, PKCS#7 padding is removed from the result.

func (*AESCBCCipher) DecryptStream added in v0.0.2 

func (c *AESCBCCipher) DecryptStream(ctx context.Context, dst io.Writer, src io.Reader) (int, error)

DecryptStream decrypts data from src and writes to dst in streaming fashion. For CBC mode, PKCS#7 padding is removed from the result.

func (*AESCBCCipher) Encrypt added in v0.0.2 

func (c *AESCBCCipher) Encrypt(ctx context.Context, plaintext []byte) ([]byte, error)

Encrypt encrypts the source data and returns the result. For CBC mode, data is padded using PKCS#7 padding.

func (*AESCBCCipher) EncryptStream added in v0.0.2 

func (c *AESCBCCipher) EncryptStream(ctx context.Context, dst io.Writer, src io.Reader) (int, error)

EncryptStream encrypts data from src and writes to dst in streaming fashion. For CBC mode, data is processed efficiently with manual PKCS#7 padding at the end.

func (*AESCBCCipher) KeySize added in v0.0.2 

func (c *AESCBCCipher) KeySize() int

KeySize returns the key size in bytes.

func (*AESCBCCipher) SetBufferSize added in v0.0.2 

func (c *AESCBCCipher) SetBufferSize(size int) error

SetBufferSize sets the buffer size for streaming operations. The buffer size must be a positive multiple of AES_BLOCK_SIZE.

type AESECBCipher added in v0.0.2 

type AESECBCipher struct {
	// contains filtered or unexported fields
}

AESECBCipher implements the BlockCipher interface for AES-ECB mode. ECB mode does not use an initialization vector (IV) and is not recommended for most applications due to security concerns, but is included for compatibility.

func NewAESECBCipher added in v0.0.2 

func NewAESECBCipher(key *SymmetricKey) (*AESECBCipher, error)

NewAESECBCipher creates a new AES-ECB cipher with the given symmetric key.

func (*AESECBCipher) BlockSize added in v0.0.2 

func (c *AESECBCipher) BlockSize() int

BlockSize returns the block size for AES (16 bytes).

func (*AESECBCipher) BufferSize added in v0.0.2 

func (c *AESECBCipher) BufferSize() int

BufferSize returns the current buffer size for streaming operations.

func (*AESECBCipher) Decrypt added in v0.0.2 

func (c *AESECBCipher) Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)

Decrypt decrypts the source data and returns the result. For ECB mode, PKCS#7 padding is removed from the result.

func (*AESECBCipher) DecryptStream added in v0.0.2 

func (c *AESECBCipher) DecryptStream(ctx context.Context, dst io.Writer, src io.Reader) (int, error)

DecryptStream decrypts data from src and writes to dst in streaming fashion. For ECB mode, PKCS#7 padding is manually removed from the final result.

func (*AESECBCipher) Encrypt added in v0.0.2 

func (c *AESECBCipher) Encrypt(ctx context.Context, plaintext []byte) ([]byte, error)

Encrypt encrypts the source data and writes the result to destination. For ECB mode, data is padded using PKCS#7 padding.

func (*AESECBCipher) EncryptStream added in v0.0.2 

func (c *AESECBCipher) EncryptStream(ctx context.Context, dst io.Writer, src io.Reader) (int, error)

EncryptStream encrypts data from src and writes to dst in streaming fashion. For ECB mode, data is processed efficiently with manual PKCS#7 padding at the end.

func (*AESECBCipher) KeySize added in v0.0.2 

func (c *AESECBCipher) KeySize() int

KeySize returns the key size in bytes.

func (*AESECBCipher) SetBufferSize added in v0.0.2 

func (c *AESECBCipher) SetBufferSize(size int) error

SetBufferSize sets the buffer size for streaming operations. The buffer size must be a positive multiple of AES_BLOCK_SIZE.

type AESGCMCipher added in v0.0.2 

type AESGCMCipher struct {
	// contains filtered or unexported fields
}

AESGCMCipher implements the BlockCipher interface for AES-GCM mode. GCM mode provides authenticated encryption with additional data (AEAD).

func NewAESGCMCipher added in v0.0.2 

func NewAESGCMCipher(key *SymmetricKey, iv []byte) (*AESGCMCipher, error)

NewAESGCMCipher creates a new AES-GCM cipher with the given symmetric key and IV. The IV should be 12 bytes for optimal security in GCM mode. Additional authenticated data (AAD) is set to nil by default. Tag length is set to 16 bytes by default. AAD and tag length can be set using SetAAD and SetTagLength methods.

func (*AESGCMCipher) BlockSize added in v0.0.2 

func (c *AESGCMCipher) BlockSize() int

BlockSize returns the block size for AES (16 bytes).

func (*AESGCMCipher) BufferSize added in v0.0.2 

func (c *AESGCMCipher) BufferSize() int

BufferSize returns the current buffer size for streaming operations.

func (*AESGCMCipher) Decrypt added in v0.0.2 

func (c *AESGCMCipher) Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)

Decrypt decrypts the source data and returns the result. For GCM mode, the source data should include the authentication tag.

func (*AESGCMCipher) DecryptStream added in v0.0.2 

func (c *AESGCMCipher) DecryptStream(ctx context.Context, dst io.Writer, src io.Reader) (int, error)

DecryptStream decrypts data from src and writes to dst in streaming fashion. For GCM mode, the authentication tag is expected to be included in the input.

func (*AESGCMCipher) Encrypt added in v0.0.2 

func (c *AESGCMCipher) Encrypt(ctx context.Context, plaintext []byte) ([]byte, error)

Encrypt encrypts the source data and returns the result. For GCM mode, the result includes the authentication tag.

func (*AESGCMCipher) EncryptStream added in v0.0.2 

func (c *AESGCMCipher) EncryptStream(ctx context.Context, dst io.Writer, src io.Reader) (int, error)

EncryptStream encrypts data from src and writes to dst in streaming fashion. For GCM mode, the authentication tag is included in the output at the end.

func (*AESGCMCipher) KeySize added in v0.0.2 

func (c *AESGCMCipher) KeySize() int

KeySize returns the key size in bytes.

func (*AESGCMCipher) SetAAD added in v0.0.2 

func (c *AESGCMCipher) SetAAD(aad []byte)

SetAAD sets the additional authenticated data for GCM mode.

func (*AESGCMCipher) SetBufferSize added in v0.0.2 

func (c *AESGCMCipher) SetBufferSize(size int) error

SetBufferSize sets the buffer size for streaming operations. The buffer size must be a positive multiple of AES_BLOCK_SIZE.

func (*AESGCMCipher) SetTagLength added in v0.0.2 

func (c *AESGCMCipher) SetTagLength(length int) error

SetTagLength sets the authentication tag length for GCM mode. Valid tag lengths are 12, 13, 14, 15, or 16 bytes(96, 104, 112, 120, or 128 bits). The default is 16 bytes (128 bits). NIST SP 800-38D recommends 12 bytes (96 bits) for most applications. (96, 104, 112, 120, or 128 bits)

type Attribute added in v0.0.2 

type Attribute = pkcs11.Attribute

func NewIDAttribute added in v0.0.2 

func NewIDAttribute(id []byte) *Attribute

func NewLabelAttribute added in v0.0.2 

func NewLabelAttribute(label string) *Attribute

type BlockCipher added in v0.0.2 

type BlockCipher interface {
	Encrypt(ctx context.Context, plaintext []byte) ([]byte, error)
	Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)

	EncryptStream(ctx context.Context, dst io.Writer, src io.Reader) (int, error)
	DecryptStream(ctx context.Context, dst io.Writer, src io.Reader) (int, error)

	BlockSize() int
	KeySize() int
}

BlockCipher represents a block cipher that can be used for encryption and decryption. It provides methods for both in-place and streaming operations.

type Config 

type Config struct {
	// LibraryPath is the filesystem path to the PKCS#11 library (.so, .dll, or .dylib)
	LibraryPath string

	// Slot identification method (only one should be used)
	// SlotID is the slot id of the PKCS#11 device to use
	SlotID *uint
	// SlotIndex is the index of the slot to use (alternative to SlotID)
	SlotIndex *uint
	// TokenLabel is used to identify the token to use by label
	TokenLabel string
	// TokenSerialNumber is the serial number of the token to use
	TokenSerialNumber string

	// UserPIN is the PIN used to authenticate as a normal user (not SO)
	UserPIN string

	// Session Pool configuration
	// MaxSessions is the maximum number of sessions in the pool (default: 1024)
	MaxSessions int
	// SessionAcquireTimeout is the timeout for acquiring a session from the pool
	// (default: 0 means blocking wait)
	SessionAcquireTimeout time.Duration
}

Config holds the configuration parameters for connecting to a PKCS#11 device.

func (*Config) GetSlotIdentificationType 

func (c *Config) GetSlotIdentificationType() (SlotIdentificationType, error)

GetSlotIdentificationType returns the type of slot identification method configured

func (*Config) String 

func (c *Config) String() string

String returns a string representation of the config with the PIN redacted for security.

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks that the configuration is valid and the library path exists. Returns an error if the library path is empty, the file doesn't exist, the user PIN is empty, or if multiple slot identification methods are specified.

type ECDSAKeyPair 

type ECDSAKeyPair struct {
	*KeyPair
}

ECDSAKeyPair wraps a KeyPair and implements the crypto.Signer interface for ECDSA keys. Note that ECDSA keys do not support encryption/decryption operations.

func NewECDSAKeyPair 

func NewECDSAKeyPair(keyPair *KeyPair) (*ECDSAKeyPair, error)

NewECDSAKeyPair creates a new ECDSAKeyPair from a KeyPair. Returns an error if the KeyPair is not an ECDSA key.

func (*ECDSAKeyPair) Public 

func (e *ECDSAKeyPair) Public() crypto.PublicKey

Public returns the public key corresponding to the private key.

func (*ECDSAKeyPair) Sign 

func (e *ECDSAKeyPair) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)

Sign implements crypto.Signer interface for ECDSA keys. The digest parameter should be the already-hashed data. ECDSA signatures are converted to DER format for compatibility with Go's crypto interfaces.

func (*ECDSAKeyPair) SignHash 

func (e *ECDSAKeyPair) SignHash(hash crypto.Hash, digest []byte) ([]byte, error)

SignHash provides a convenient method for ECDSA signing with a specific hash function. It expects the digest to be already computed with the specified hash function.

type ED25519KeyPair 

type ED25519KeyPair struct {
	*KeyPair
}

ED25519KeyPair wraps a KeyPair and implements the crypto.Signer interface for ED25519 keys. Note that ED25519 keys do not support encryption/decryption operations.

func NewED25519KeyPair 

func NewED25519KeyPair(keyPair *KeyPair) (*ED25519KeyPair, error)

NewED25519KeyPair creates a new ED25519KeyPair from a KeyPair. Returns an error if the KeyPair is not an ED25519 key.

func (*ED25519KeyPair) Public 

func (e *ED25519KeyPair) Public() crypto.PublicKey

Public returns the public key corresponding to the private key.

func (*ED25519KeyPair) Sign 

func (e *ED25519KeyPair) Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) ([]byte, error)

Sign implements crypto.Signer interface for ED25519 keys. ED25519 signatures are deterministic and don't require a hash function. The message parameter should be the raw message data, not a pre-hashed digest.

func (*ED25519KeyPair) SignMessage 

func (e *ED25519KeyPair) SignMessage(message []byte) ([]byte, error)

SignMessage provides a convenient method for ED25519 signing. It expects the raw message data, not a pre-computed hash.

type ErrorCode 

type ErrorCode int

ErrorCode represents different categories of PKCS#11 errors for easier error handling. 

const (
	// ErrUnknown represents an unknown or unmapped PKCS#11 error
	ErrUnknown ErrorCode = iota
	// ErrNotInitialized indicates the PKCS#11 library is not initialized
	ErrNotInitialized
	// ErrAlreadyInitialized indicates the PKCS#11 library is already initialized
	ErrAlreadyInitialized
	// ErrSessionInvalid indicates the session handle is invalid
	ErrSessionInvalid
	// ErrKeyNotFound indicates a requested key could not be found
	ErrKeyNotFound
	// ErrOperationFailed indicates a cryptographic operation failed
	ErrOperationFailed
	// ErrInvalidInput indicates invalid input parameters or templates
	ErrInvalidInput
	// ErrAuthenticationFailed indicates PIN verification or login failed
	ErrAuthenticationFailed
	// ErrSlotNotFound indicates the specified slot is not available
	ErrSlotNotFound
	// ErrObjectNotFound indicates a PKCS#11 object could not be found
	ErrObjectNotFound
	// ErrSignatureFailed indicates a signature operation failed
	ErrSignatureFailed
	// ErrDecryptionFailed indicates a decryption operation failed
	ErrDecryptionFailed
)

type KeyPair 

type KeyPair struct {

	// Handle is the PKCS#11 object handle for the private key
	Handle pkcs11.ObjectHandle
	// PublicHandle is the PKCS#11 object handle for the public key
	PublicHandle pkcs11.ObjectHandle
	// Label is the human-readable label for the key pair
	Label string
	// ID is the unique identifier for the key pair (generated from label)
	ID []byte
	// KeyType indicates whether this is an RSA or ECDSA key pair
	KeyType KeyPairType
	// KeySize is the key size in bits (e.g., 2048 for RSA, 256 for P-256)
	KeySize int
	// PublicKey is the public key material extracted from the HSM
	PublicKey crypto.PublicKey
	// contains filtered or unexported fields
}

KeyPair represents an asymmetric key pair stored in the PKCS#11 device. It contains both the handle to the private key in the HSM and the public key material.

func (*KeyPair) AsDecrypter 

func (kp *KeyPair) AsDecrypter() (crypto.Decrypter, error)

AsDecrypter returns a crypto.Decrypter implementation for this key pair. Only RSA keys support decryption operations.

func (*KeyPair) AsSigner 

func (kp *KeyPair) AsSigner() crypto.Signer

AsSigner returns a crypto.Signer implementation for this key pair. Supports RSA, ECDSA, and ED25519 key types.

func (*KeyPair) Public added in v0.0.2 

func (kp *KeyPair) Public() crypto.PublicKey

func (*KeyPair) String 

func (k *KeyPair) String() string

String returns a string representation of the key pair with label, type, and size.

type KeyPairType 

type KeyPairType int

KeyPairType represents the type of asymmetric key pair. 

const (
	// KeyPairTypeRSA represents RSA key pairs for signing and encryption
	KeyPairTypeRSA KeyPairType = iota + 1
	// KeyPairTypeECDSA represents ECDSA key pairs for signing
	KeyPairTypeECDSA
	// KeyPairTypeED25519 represents ED25519 key pairs for signing
	KeyPairTypeED25519
)

type PKCS11Error 

type PKCS11Error struct {
	// Code is the categorized error code for easier error handling
	Code ErrorCode
	// Message is a human-readable error message
	Message string
	// CKRCode is the raw PKCS#11 CKR error code
	CKRCode uint
	// Cause is the underlying error that caused this PKCS#11 error
	Cause error
}

PKCS11Error represents a PKCS#11 specific error with additional context. It wraps the underlying PKCS#11 error code and provides a categorized error code for easier handling.

func NewPKCS11Error 

func NewPKCS11Error(code ErrorCode, message string, cause error) *PKCS11Error

NewPKCS11Error creates a new PKCS11Error with the specified parameters.

func (*PKCS11Error) Error 

func (e *PKCS11Error) Error() string

func (*PKCS11Error) Unwrap 

func (e *PKCS11Error) Unwrap() error

type Pool added in v0.0.3 

type Pool struct {
	// contains filtered or unexported fields
}

Pool manages a pool of PKCS#11 sessions for concurrent access. All sessions share the same PKCS#11 context from the Token. It provides thread-safe allocation and deallocation with configurable pool size limits and acquisition timeouts.

type RSAKeyPair 

type RSAKeyPair struct {
	*KeyPair
}

RSAKeyPair wraps a KeyPair and implements both crypto.Signer and crypto.Decrypter interfaces for RSA keys. It provides all RSA operations (signing and decryption) in a single type.

func NewRSAKeyPair 

func NewRSAKeyPair(keyPair *KeyPair) (*RSAKeyPair, error)

NewRSAKeyPair creates a new RSAKeyPair from a KeyPair. Returns an error if the KeyPair is not an RSA key.

func (*RSAKeyPair) Decrypt 

func (r *RSAKeyPair) Decrypt(rand io.Reader, ciphertext []byte, opts crypto.DecrypterOpts) ([]byte, error)

Decrypt implements crypto.Decrypter interface for RSA keys. Supports PKCS#1 v1.5 and OAEP padding schemes based on the opts parameter. If opts is nil, PKCS#1 v1.5 padding is used by default.

func (*RSAKeyPair) DecryptOAEP 

func (r *RSAKeyPair) DecryptOAEP(hash crypto.Hash, ciphertext []byte, label []byte) ([]byte, error)

DecryptOAEP provides a convenient method for RSA decryption with OAEP padding.

func (*RSAKeyPair) DecryptPKCS1v15 

func (r *RSAKeyPair) DecryptPKCS1v15(ciphertext []byte) ([]byte, error)

DecryptPKCS1v15 provides a convenient method for RSA decryption with PKCS#1 v1.5 padding.

func (*RSAKeyPair) PrivateEncrypt added in v0.0.3 

func (r *RSAKeyPair) PrivateEncrypt(data []byte, padding RSAPrivateEncryptPadding) ([]byte, error)

PrivateEncrypt provides a method to perform RSA private key encryption without padding (signing) RSA_NO_PADDING RSA_PKCS1_PADDING https://docs.openssl.org/master/man3/RSA_private_encrypt/ TODO：refactor to Sign method by options

func (*RSAKeyPair) Public 

func (r *RSAKeyPair) Public() crypto.PublicKey

Public returns the public key corresponding to the private key.

func (*RSAKeyPair) Sign 

func (r *RSAKeyPair) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)

Sign implements crypto.Signer interface for RSA keys. Supports PKCS#1 v1.5 and PSS padding schemes based on the opts parameter.

func (*RSAKeyPair) SignPKCS1v15 

func (r *RSAKeyPair) SignPKCS1v15(hash crypto.Hash, digest []byte) ([]byte, error)

SignPKCS1v15 provides a convenient method for RSA signing with PKCS#1 v1.5 padding.

func (*RSAKeyPair) SignPSS 

func (r *RSAKeyPair) SignPSS(hash crypto.Hash, digest []byte) ([]byte, error)

SignPSS provides a convenient method for RSA signing with PSS padding.

type RSAPrivateEncryptPadding added in v0.0.3 

type RSAPrivateEncryptPadding int
const (
	RSA_PRIVATEENCRYPT_NO_PADDING RSAPrivateEncryptPadding = iota + 1
	RSA_PRIVATEENCRYPT_PKCS1_PADDING
)

type Session added in v0.0.3 

type Session struct {
	// contains filtered or unexported fields
}

Session wraps a PKCS#11 session handle. All sessions share the Token's PKCS#11 context for efficiency.

func (*Session) GetCtx added in v0.0.3 

func (c *Session) GetCtx() *pkcs11.Ctx

GetCtx returns the underlying PKCS#11 context.

func (*Session) GetHandle added in v0.0.3 

func (c *Session) GetHandle() pkcs11.SessionHandle

GetHandle returns the underlying PKCS#11 session handle.

func (*Session) Release added in v0.0.3 

func (c *Session) Release()

Release returns the context back to the pool for reuse.

type SlotIdentificationType 

type SlotIdentificationType int

SlotIdentificationType represents the type of slot identification method used 

const (
	SlotIdentificationByID SlotIdentificationType = iota
	SlotIdentificationByIndex
	SlotIdentificationByTokenLabel
	SlotIdentificationByTokenSerial
)

func (SlotIdentificationType) String 

func (s SlotIdentificationType) String() string

String returns the string representation of the slot identification type

type SymmetricKey 

type SymmetricKey struct {

	// Handle is the PKCS#11 object handle for the symmetric key
	Handle pkcs11.ObjectHandle
	// Label is the human-readable label for the symmetric key
	Label string
	// ID is the unique identifier for the symmetric key (generated from label)
	ID []byte
	// KeyType indicates the type of symmetric key (AES, DES, 3DES)
	KeyType SymmetricKeyType
	// KeySize is the key size in bits
	KeySize int
	// contains filtered or unexported fields
}

SymmetricKey represents a symmetric encryption key stored in the PKCS#11 HSM. It can be used for encryption, decryption, key wrapping, and key unwrapping operations.

func (*SymmetricKey) String 

func (k *SymmetricKey) String() string

String returns a string representation of the symmetric key.

type SymmetricKeyType 

type SymmetricKeyType int

SymmetricKeyType represents the type of symmetric encryption key. 

const (
	// SymmetricKeyTypeAES represents AES symmetric keys (128, 192, 256 bits)
	SymmetricKeyTypeAES SymmetricKeyType = iota + 1
	// SymmetricKeyTypeDES represents DES symmetric keys (64 bits)
	SymmetricKeyTypeDES
	// SymmetricKeyType3DES represents 3DES symmetric keys (192 bits)
	SymmetricKeyType3DES
)

type Token added in v0.0.3 

type Token struct {
	Config *Config
	// contains filtered or unexported fields
}

Token represents a connection to a PKCS#11 device (HSM). It manages the session pool for concurrent access with isolated sessions. Token is thread-safe and can be used concurrently from multiple goroutines.

func NewToken added in v0.0.3 

func NewToken(config *Config) (*Token, error)

NewToken creates a new PKCS#11 token with the provided configuration. It validates the configuration and initializes the session pool. The token must be closed using Close() when no longer needed.

func (*Token) Close added in v0.0.3 

func (t *Token) Close() error

Close properly shuts down the PKCS#11 token by closing the context pool. All context cleanup is handled by the context pool itself. This method is safe to call multiple times and is thread-safe.

func (*Token) DeleteKeyPair added in v0.0.3 

func (t *Token) DeleteKeyPair(ctx context.Context, keyID []byte) error

DeleteKeyPairByID deletes a key pair from the PKCS#11 device by its unique ID. Both the private and public key objects are removed from the device. Returns an error if the key pair is not found or if the deletion fails.

func (*Token) DeleteSymmetricKey added in v0.0.3 

func (t *Token) DeleteSymmetricKey(ctx context.Context, keyID []byte) error

DeleteSymmetricKey deletes a symmetric key from the PKCS#11 device. Returns an error if the deletion fails.

func (*Token) Generate3DESKey added in v0.0.3 

func (t *Token) Generate3DESKey(ctx context.Context, attrs ...*Attribute) (*SymmetricKey, error)

Generate3DESKey generates a new 3DES symmetric key (192 bits) in the PKCS#11 device. The generated key is marked as non-extractable and sensitive for security.

func (*Token) GenerateAESKey added in v0.0.3 

func (t *Token) GenerateAESKey(ctx context.Context, keySize int, attrs ...*Attribute) (*SymmetricKey, error)

GenerateAESKey generates a new AES symmetric key in the PKCS#11 device. Supported key sizes are 128, 192, and 256 bits. The generated key is marked as non-extractable and sensitive for security.

func (*Token) GenerateDESKey added in v0.0.3 

func (t *Token) GenerateDESKey(ctx context.Context, attrs ...*Attribute) (*SymmetricKey, error)

GenerateDESKey generates a new DES symmetric key (64 bits) in the PKCS#11 device. The generated key is marked as non-extractable and sensitive for security.

func (*Token) GenerateECDSAKeyPair added in v0.0.3 

func (t *Token) GenerateECDSAKeyPair(ctx context.Context, curve elliptic.Curve, attrs ...*Attribute) (*KeyPair, error)

GenerateECDSAKeyPair generates a new ECDSA key pair in the PKCS#11 device. Supported curves are P-256 and P-384. The generated keys are marked as non-extractable and sensitive for security.

func (*Token) GenerateED25519KeyPair added in v0.0.3 

func (t *Token) GenerateED25519KeyPair(ctx context.Context, attrs ...*Attribute) (*KeyPair, error)

GenerateED25519KeyPair generates a new ED25519 key pair in the PKCS#11 device. ED25519 is a modern elliptic curve signature scheme providing high security and performance. The generated keys are marked as non-extractable and sensitive for security.

func (*Token) GenerateRSAKeyPair added in v0.0.3 

func (t *Token) GenerateRSAKeyPair(ctx context.Context, keySize int, attrs ...*Attribute) (*KeyPair, error)

GenerateRSAKeyPair generates a new RSA key pair in the PKCS#11 device. Supported key sizes are 2048 and 4096 bits. The generated keys are marked as non-extractable and sensitive for security.

func (*Token) GetKeyPair added in v0.0.3 

func (t *Token) GetKeyPair(ctx context.Context, id []byte) (*KeyPair, error)

GetKeyPair searches for a key pair by its unique ID. Returns an error if no key is found with the specified ID.

func (*Token) GetSession added in v0.0.3 

func (t *Token) GetSession(ctx context.Context) (*Session, error)

GetContext acquires a context from the context pool. It supports timeout control through the context parameter. The returned Context must be released back to the pool using Release(). This method is thread-safe and supports true concurrent access.

func (*Token) GetSlotID added in v0.0.3 

func (t *Token) GetSlotID() uint

func (*Token) GetSlotInfo added in v0.0.3 

func (t *Token) GetSlotInfo(ctx context.Context) (*pkcs11.SlotInfo, error)

func (*Token) GetSymmetricKey added in v0.0.3 

func (t *Token) GetSymmetricKey(ctx context.Context, keyID []byte) (*SymmetricKey, error)

func (*Token) GetTokenInfo added in v0.0.3 

func (t *Token) GetTokenInfo(ctx context.Context) (*pkcs11.TokenInfo, error)

func (*Token) Import3DESKey added in v0.0.3 

func (t *Token) Import3DESKey(ctx context.Context, keyMaterial []byte, attrs ...*Attribute) (*SymmetricKey, error)

Import3DESKey imports existing 3DES key material into the PKCS#11 device. Key material must be exactly 24 bytes (192 bits). The imported key is marked as non-extractable and sensitive for security.

func (*Token) ImportAESKey added in v0.0.3 

func (t *Token) ImportAESKey(ctx context.Context, keyMaterial []byte, attrs ...*Attribute) (*SymmetricKey, error)

ImportAESKey imports existing AES key material into the PKCS#11 device. Supported key sizes are 16, 24, or 32 bytes (128, 192, or 256 bits). The imported key is marked as non-extractable and sensitive for security.

func (*Token) ImportDESKey added in v0.0.3 

func (t *Token) ImportDESKey(ctx context.Context, keyMaterial []byte, attrs ...*Attribute) (*SymmetricKey, error)

ImportDESKey imports existing DES key material into the PKCS#11 device. Key material must be exactly 8 bytes (64 bits). The imported key is marked as non-extractable and sensitive for security.

func (*Token) ImportECDSAKeyPair added in v0.0.3 

func (t *Token) ImportECDSAKeyPair(ctx context.Context, privateKey *ecdsa.PrivateKey, attrs ...*Attribute) (*KeyPair, error)

ImportECDSAKeyPair imports an existing ECDSA private key into the PKCS#11 device. The imported key is marked as non-extractable and sensitive for security. Both the private and public key objects are created in the device.

func (*Token) ImportED25519KeyPair added in v0.0.3 

func (t *Token) ImportED25519KeyPair(ctx context.Context, privateKey ed25519.PrivateKey, attrs ...*Attribute) (*KeyPair, error)

ImportED25519KeyPair imports an existing ED25519 private key into the PKCS#11 device. The imported key is marked as non-extractable and sensitive for security. Both the private and public key objects are created in the device. Uses a fallback strategy to handle different PKCS#11 implementation requirements.

func (*Token) ImportKeyPair added in v0.0.3 

func (t *Token) ImportKeyPair(ctx context.Context, privateKey crypto.PrivateKey, attrs ...*Attribute) (*KeyPair, error)

ImportKeyPair imports a private key into the PKCS#11 device. It automatically detects the key type (RSA, ECDSA, or ED25519) and calls the appropriate import function.

func (*Token) ImportRSAKeyPair added in v0.0.3 

func (t *Token) ImportRSAKeyPair(ctx context.Context, privateKey *rsa.PrivateKey, attrs ...*Attribute) (*KeyPair, error)

ImportRSAKeyPair imports an existing RSA private key into the PKCS#11 device. The imported key is marked as non-extractable and sensitive for security. Both the private and public key objects are created in the device.

func (*Token) ListKeyPairs added in v0.0.3 

func (t *Token) ListKeyPairs(ctx context.Context, attrs ...*Attribute) ([]*KeyPair, error)

ListKeyPairs returns all key pairs stored in the PKCS#11 device. Keys that cannot be processed (due to unsupported types, etc.) are silently skipped.

func (*Token) ListSymmetricKeys added in v0.0.3 

func (t *Token) ListSymmetricKeys(ctx context.Context, attrs ...*Attribute) ([]*SymmetricKey, error)

ListSymmetricKeys returns all symmetric keys stored in the PKCS#11 device. Keys that cannot be processed (due to unsupported types, etc.) are silently skipped.

func (*Token) Ping added in v0.0.3 

func (t *Token) Ping(ctx context.Context) error

Ping tests the connection to the PKCS#11 device by performing a simple session info query. It returns an error if the device is not accessible or the session is invalid.

Source Files

View all Source files

Directories

Path Synopsis
test
e2e
e2e/softhsm
e2e/utimaco

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.
⌂ 换网址