# Using with SmartCard-HSM (Nitrokey HSM)

Support for the SmartCard-HSM and Nitrokey HSM is provided through the OpenSC project.

The device is not a cryptographic accelerator. Only key generation and the private key operations (sign and decrypt) are supported. Public key operations should be done by extracting the public key and working on the computer.

The following mechanisms are available:

Cipher | Capabilities | Variants
--- | --- | ---
RSA (v1.5/X.509) | Decrypt, Verify, Sign | MD5, SHA1, SHA256, SHA384, SHA512
ECDSA | Sign | SHA1
ECDH | Derive | Cofactor Derive

Session lifetime objects are not supported and the value of `pkcs11.constants.Attribute.TOKEN` and the store keyword argument are ignored. All objects will be stored to the device.

The following named curves are supported:

> - secp192r1 (aka prime192v1)

> - secp256r1 (aka prime256v1)

> - brainpoolP192r1

> - brainpoolP224r1

> - brainpoolP256r1

> - brainpoolP320r1

> - secp192k1

> - secp256k1 (the Bitcoin curve)

More information is available in the Nitrokey FAQ.

## Getting Started

Initialize the device with sc-hsm-tool, e.g.

    sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --label "Nitrokey"

See the documentation for more information on the parameters.

The OpenSC PKCS #11 module is opensc-pkcs11.so.

## Generating Keys

### RSA

    import pkcs11

    with token.open(user_pin='1234', rw=True) as session:
        pub, priv = session.generate_keypair(pkcs11.KeyType.RSA, 2048,
                                             store=True,
                                             label="My RSA Keypair")

### EC

    with token.open(user_pin='1234', rw=True) as session:
        ecparams = session.create_domain_parameters(
            pkcs11.KeyType.EC, {
                pkcs11.Attribute.EC_PARAMS: pkcs11.util.ec.encode_named_curve_parameters('secp256r1'),
            }, local=True)

        pub, priv = ecparams.generate_keypair(store=True,
                                              label="My EC Keypair")

## Exporting Public Keys for External Use

While we don’t want our private keys to leave the boundary of our HSM, we can extract the public keys for use with a cryptographic library of our choosing. Importing/Exporting Keys has more information on functions for exporting keys.

### RSA

PyCrypto example:

    from pkcs11 import KeyType, ObjectClass, Mechanism
    from pkcs11.util.rsa import encode_rsa_public_key

    from Crypto.PublicKey import RSA
    from Crypto.Cipher import PKCS1_v1_5

    # Extract public key
    key = session.get_key(key_type=KeyType.RSA,
                          object_class=ObjectClass.PUBLIC_KEY)
    key = RSA.importKey(encode_rsa_public_key(key))

    # Encryption on the local machine
    cipher = PKCS1_v1_5.new(key)
    crypttext = cipher.encrypt(b'Data to encrypt')

    # Decryption in the HSM
    priv = self.session.get_key(key_type=KeyType.RSA,
                                object_class=ObjectClass.PRIVATE_KEY)

    plaintext = priv.decrypt(crypttext, mechanism=Mechanism.RSA_PKCS)

### ECDSA

oscrypto example:

    from pkcs11 import KeyType, ObjectClass, Mechanism
    from pkcs11.util.ec import encode_ec_public_key, encode_ecdsa_signature

    from oscrypto.asymmetric import load_public_key, ecdsa_verify

    # Sign data in the HSM
    priv = self.session.get_key(key_type=KeyType.EC,
                                object_class=ObjectClass.PRIVATE_KEY)
    signature = priv.sign(b'Data to sign', mechanism=Mechanism.ECDSA_SHA1)
    # Encode as ASN.1 for interchange
    signature = encode_ecdsa_signature(signature)

    # Extract the public key
    pub = self.session.get_key(key_type=KeyType.EC,
                               object_class=ObjectClass.PUBLIC_KEY)

    # Verify the signature on the local machine
    key = load_public_key(encode_ec_public_key(pub))
    ecdsa_verify(key, signature, b'Data to sign', 'sha1')

### ECDH

Smartcard-HSM can generate a shared key via ECDH key exchange.

Warning

Where possible, e.g. over networks, you should use ephemeral keys, to allow for perfect forward secrecy. Smartcard HSM’s ECDH is only useful when need to repeatedly retrieve the same shared secret, e.g. encrypting files in a hybrid cryptosystem.

cryptography example:

    from cryptography.hazmat.backends import default_backend
    from cryptography.hazmat.primitives.asymmetric import ec
    from cryptography.hazmat.primitives.serialization import \
        Encoding, PublicFormat, load_der_public_key

    # Retrieve our keypair, with our public key encoded for interchange
    alice_priv = self.session.get_key(key_type=KeyType.EC,
                                        object_class=ObjectClass.PRIVATE_KEY)
    alice_pub = self.session.get_key(key_type=KeyType.EC,
                                        object_class=ObjectClass.PUBLIC_KEY)
    alice_pub = encode_ec_public_key(alice_pub)

    # Bob generates a keypair, with their public key encoded for
    # interchange
    bob_priv = ec.generate_private_key(ec.SECP256R1,
                                        default_backend())
    bob_pub = bob_priv.public_key().public_bytes(
        Encoding.DER,
        PublicFormat.SubjectPublicKeyInfo,
    )

    # Bob converts Alice's key to internal format and generates their
    # shared key
    bob_shared_key = bob_priv.exchange(
        ec.ECDH(),
        load_der_public_key(alice_pub, default_backend()),
    )

    key = alice_priv.derive_key(
        KeyType.GENERIC_SECRET, 256,
        mechanism_param=(
            KDF.NULL, None,
            # SmartcardHSM doesn't accept DER-encoded EC_POINTs for derivation
            decode_ec_public_key(bob_pub, encode_ec_point=False)
            [Attribute.EC_POINT],
        ),
    )
    alice_shared_key = key[Attribute.VALUE]

When decoding the other user’s EC_POINT for passing into the key derivation the standard says to pass a raw octet string (set encode_ec_point to False), however some PKCS #11 implementations require a DER-encoded octet string (i.e. the format of the `pkcs11.constants.Attribute.EC_POINT` attribute).

## Encrypting Files

The device only supports asymmetric mechanisms. To do file encryption, you will need to generate AES keys locally, which you can encrypt with your RSA public key (this is how the Nitrokey storage key works); or by using ECDH to generate a shared secret from a locally generated public key.

## Debugging

The parameter OPENSC_DEBUG will enable debugging of the OpenSC driver. A higher number indicates more verbosity.

## Thanks

Thanks to Nitrokey for their support of open software and sending a Nitrokey HSM to test with python-pkcs11.