.. hsm2-tools-python-yubihsm.rst

.. _hsm2-tools-python-yubihsm-label:

Python Library
================

The `Python library <https://developers.yubico.com/python-yubihsm/>`_ allows you to interface with a YubiHSM 2 through both the Connector service and direct USB connection using the Python programming language. It supports Python 3.8 or later.

The recommended way to install the library is by using ``pip`` inside a ``virtualenv``. To create and activate a ``virtualenv``, run:

.. code-block:: bash

   $ virtualenv yubihsm
   Running virtualenv with interpreter /usr/bin/python3
   New python executable in /home/user/yubihsm/bin/python3
   Also creating executable in /home/user/yubihsm/bin/python
   Installing setuptools, pkg_resources, pip, wheel...done.

   $ source yubihsm/bin/activate
   (yubihsm) $ pip install yubihsm[http,usb]
   Collecting yubihsm-2.0.0
   ...
   Successfully installed asn1crypto-0.22.0 cffi-1.10.0 cryptography-1.8.1
      enum34-1.1.6 idna-2.5 ipaddress-1.0.18 pycparser-2.17 pyusb-1.0.2
      requests-2.13.0 yubihsm-2.0.0
   (yubihsm) $


.. Note::
   The ``cryptography`` dependency uses C extensions, and therefore has some build dependencies. For detailed instructions, see: https://cryptography.io/en/latest/installation/

   .. code-block:: bash

      from yubihsm import YubiHsm
      from yubihsm.objects import AsymmetricKey
      from yubihsm.defs import ALGORITHM, CAPABILITY

      # Connect to the Connector and establish a session using the default
      # auth key:
      hsm = YubiHsm.connect("http://localhost:12345")
      session = hsm.create_session_derived(1, "password")

      # Create a new EC key for signing:
      key = AsymmetricKey.generate(session, 0, "EC Key", 1, CAPABILITY.SIGN_ECDSA, ALGORITHM.EC_P256)

      # Sign a message
      data = b'Hello world!'
      signature = key.sign_ecdsa(data)

      # Delete the key from the YubiHSM 2
      key.delete()

      # Close session and connection:
      session.close()
      hsm.close()