1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

"""
HSM operations via PKCS#11 interface.
PKCS#11 is the standard API for cryptographic tokens including HSMs.
"""
import pkcs11
from pkcs11 import KeyType, ObjectClass, Mechanism
from pkcs11.util.rsa import encode_rsa_public_key
 
class HSMCryptography:
    """
    Interface to HSM via PKCS#11 for cryptographic operations.
    Works with Luna, nCipher, AWS CloudHSM, etc.
    """
    
    def __init__(self, library_path: str, token_label: str, pin: str):
        # Load the PKCS#11 library provided by HSM vendor
        self.lib = pkcs11.lib(library_path)
        self.token = self.lib.get_token(token_label=token_label)
        self.session = self.token.open(user_pin=pin, rw=True)
    
    def generate_rsa_key_pair(self, key_label: str, 
                               key_size: int = 4096) -> tuple:
        """
        Generate RSA key pair inside HSM.
        Private key NEVER leaves the HSM in plaintext.
        """
        public_key, private_key = self.session.generate_keypair(
            KeyType.RSA,
            key_size,
            store=True,  # Persist in HSM
            label=key_label,
            capabilities={
                # Public key can encrypt and verify
                ObjectClass.PUBLIC_KEY: ['encrypt', 'verify', 'wrap'],
                # Private key can decrypt and sign
                ObjectClass.PRIVATE_KEY: ['decrypt', 'sign', 'unwrap']
            }
        )
        return public_key, private_key
    
    def sign_data(self, private_key_label: str, data: bytes) -> bytes:
        """
        Sign data using private key stored in HSM.
        The signing operation happens entirely inside the HSM.
        """
        # Find the private key by label
        private_key = self.session.get_key(
            key_type=KeyType.RSA,
            object_class=ObjectClass.PRIVATE_KEY,
            label=private_key_label
        )
        
        # Sign using SHA-256 with RSA PKCS#1 v1.5
        signature = private_key.sign(
            data,
            mechanism=Mechanism.SHA256_RSA_PKCS
        )
        return signature
    
    def generate_aes_key(self, key_label: str, 
                          key_size: int = 256) -> object:
        """Generate AES key inside HSM."""
        key = self.session.generate_key(
            KeyType.AES,
            key_size,
            store=True,
            label=key_label,
            capabilities=['encrypt', 'decrypt', 'wrap', 'unwrap']
        )
        return key
    
    def wrap_key(self, wrapping_key_label: str, 
                  target_key_label: str) -> bytes:
        """
        Export a key encrypted under another key.
        This is how keys are backed up from HSMs.
        """
        wrapping_key = self.session.get_key(label=wrapping_key_label)
        target_key = self.session.get_key(label=target_key_label)
        
        wrapped_key = wrapping_key.wrap_key(
            target_key,
            mechanism=Mechanism.AES_KEY_WRAP
        )
        return wrapped_key
    
    def close(self):
        self.session.close()
 
# Usage with AWS CloudHSM
# hsm = HSMCryptography(
#     library_path='/opt/cloudhsm/lib/libcloudhsm_pkcs11.so',
#     token_label='cavium',
#     pin='crypto_user:password'
# )
# public_key, private_key = hsm.generate_rsa_key_pair('signing-key')
# signature = hsm.sign_data('signing-key', document_hash)