Elliptic curve support

Author: Danielle Madeley

README.rst

@@ -88,9 +88,7 @@ Diffie-Hellman
 
     with token.open() as session:
         # Given shared Diffie-Hellman parameters
-        parameters = session.create_object({
-            Attribute.CLASS: ObjectClass.DOMAIN_PARAMETERS,
-            Attribute.KEY_TYPE: KeyType.DH,
+        parameters = session.create_domain_parameters(KeyType.DH, {
             Attribute.PRIME: prime,  # Diffie-Hellman parameters
             Attribute.BASE: base,
         })
@@ -109,6 +107,36 @@ Diffie-Hellman
             mechanism_param=other_value)
 
 
+Elliptic-Curve Diffie-Hellman
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    import pkcs11
+
+    lib = pkcs11.lib(os.environ['PKCS11_MODULE'])
+    token = lib.get_token(token_label='DEMO')
+
+    with token.open() as session:
+        # Given DER encocded EC parameters, e.g. from
+        #    openssl ecparam -outform der -name <named curve>
+        parameters = session.create_domain_parameters(KeyType.EC, {
+            Attribute.EC_PARAMS: ecparams,
+        })
+
+        # Generate a DH key pair from the public parameters
+        public, private = parameters.generate_keypair()
+
+        # Share the public half of it with our other party.
+        _network_.write(public[Attribute.EC_POINT])
+        # And get their shared value
+        other_value = _network_.read()
+
+        # Derive a shared session key
+        session_key = private.derive_key(
+            KeyType.AES, 128,
+            mechanism_param=(KDF.NULL, None, other_value))
+
 Tested Compatibility
 --------------------
 
@@ -134,6 +162,7 @@ Mechanisms:
 * AES
 * RSA
 * Diffie-Hellman
+* ECDH
 
 Operations:
 

pkcs11/_pkcs11.pyx

@@ -187,6 +187,16 @@ class Session(types.Session):
 
         return Object._make(self, new)
 
+    def create_domain_parameters(self, key_type, attrs, local=False):
+        attrs = dict(attrs)
+        attrs[Attribute.CLASS] = ObjectClass.DOMAIN_PARAMETERS
+        attrs[Attribute.KEY_TYPE] = key_type
+
+        if local:
+            return DomainParameters(self, None, attrs)
+        else:
+            return self.create_object(attrs)
+
     def generate_key(self, key_type, key_length,
                      id=None, label=None,
                      store=True, capabilities=None,
@@ -453,11 +463,13 @@ class DomainParameters(types.DomainParameters):
             Attribute.VERIFY: MechanismFlag.VERIFY & capabilities,
         }
 
-        # Copy in our domain parameters
+        # Copy in our domain parameters.
+        # Not all parameters are appropriate for all domains.
         for attribute in (
                 Attribute.BASE,
                 Attribute.PRIME,
                 Attribute.SUBPRIME,
+                Attribute.EC_PARAMS,
         ):
             try:
                 public_template_[attribute] = self[attribute]
@@ -849,11 +861,37 @@ class DeriveMixin(types.DeriveMixin):
                 raise ArgumentsBad("No default capabilities for this key "
                                    "type. Please specify `capabilities`.")
 
-        cdef CK_MECHANISM mech = \
-            _make_CK_MECHANISM(self.key_type, DEFAULT_DERIVE_MECHANISMS,
-                               mechanism, mechanism_param)
+        cdef CK_MECHANISM mech
+        cdef CK_ECDH1_DERIVE_PARAMS ecdh1_params
         cdef CK_OBJECT_HANDLE key
 
+        # Do the mechanism param ourselves so we can handle complex mechanism
+        # params like ECDH1.
+        # FIXME: this won't scale, we need a better solution than this!
+        mech = _make_CK_MECHANISM(self.key_type,
+                                  DEFAULT_DERIVE_MECHANISMS,
+                                  mechanism, None)
+
+        if mech.mechanism == Mechanism.ECDH1_DERIVE:
+            mech.pParameter = &ecdh1_params
+            mech.ulParameterLen = sizeof(CK_ECDH1_DERIVE_PARAMS)
+
+            (kdf, shared_data, public_data) = mechanism_param
+            ecdh1_params.kdf = kdf
+
+            if shared_data is None:
+                ecdh1_params.pSharedData = NULL
+                ecdh1_params.ulSharedDataLen = 0
+            else:
+                ecdh1_params.pSharedData = shared_data
+                ecdh1_params.ulSharedDataLen = len(shared_data)
+
+            ecdh1_params.pPublicData = public_data
+            ecdh1_params.ulPublicDataLen = len(public_data)
+        else:
+            mech.pParameter = <CK_CHAR *> mechanism_param
+            mech.ulParameterLen = len(mechanism_param)
+
         # Build attributes
         template_ = {
             Attribute.CLASS: ObjectClass.SECRET_KEY,

pkcs11/_pkcs11_defn.pxd

@@ -10,9 +10,10 @@ cdef extern from '../extern/pkcs11.h':
     ctypedef unsigned char CK_CHAR
     ctypedef unsigned long int CK_ULONG
     ctypedef CK_ULONG CK_ATTRIBUTE_TYPE
+    ctypedef CK_ULONG CK_EC_KDF_TYPE
     ctypedef CK_ULONG CK_FLAGS
     ctypedef CK_ULONG CK_MECHANISM_TYPE
-    ctypedef CK_ULONG CK_OBJECT_HANDLE;
+    ctypedef CK_ULONG CK_OBJECT_HANDLE
     ctypedef CK_ULONG CK_SESSION_HANDLE
     ctypedef CK_ULONG CK_SLOT_ID
 
@@ -203,6 +204,13 @@ cdef extern from '../extern/pkcs11.h':
         void *pValue
         CK_ULONG ulValueLen
 
+    ctypedef struct CK_ECDH1_DERIVE_PARAMS:
+        CK_EC_KDF_TYPE kdf
+        CK_ULONG ulSharedDataLen
+        CK_BYTE *pSharedData
+        CK_ULONG ulPublicDataLen
+        CK_BYTE *pPublicData
+
     CK_RV C_Initialize(void *)
     CK_RV C_Finalize(void *)
     CK_RV C_GetInfo(CK_INFO *info)

pkcs11/_utils.pyx

@@ -19,7 +19,7 @@ cdef CK_ULONG_buffer(length):
 
 
 cdef CK_MECHANISM _make_CK_MECHANISM(key_type, default_map,
-                                     mechanism=None, param=b'') except *:
+                                     mechanism=None, param=None) except *:
     """Build a CK_MECHANISM."""
 
     if mechanism is None:
@@ -34,8 +34,17 @@ cdef CK_MECHANISM _make_CK_MECHANISM(key_type, default_map,
 
     cdef CK_MECHANISM mech
     mech.mechanism = mechanism.value
-    mech.pParameter = <CK_CHAR *> param if param is not None else NULL
-    mech.ulParameterLen = len(param) if param is not None else 0
+
+    if param is None:
+        mech.pParameter = NULL
+        mech.ulParameterLen = 0
+
+    elif isinstance(param, bytes):
+        mech.pParameter = <CK_CHAR *> param
+        mech.ulParameterLen = len(param)
+
+    else:
+        raise ArgumentsBad("Unexpected argument to mechanism_param")
 
     return mech
 

pkcs11/constants.py

@@ -180,8 +180,18 @@ class Attribute(IntEnum):
     MODIFIABLE = 0x00000170
     """Object can be modified (:class:`bool`)."""
 
-    ECDSA_PARAMS = 0x00000180
     EC_PARAMS = 0x00000180
+    """
+    DER-encoded ANSI X9.62 Elliptic-Curve domain parameters.
+
+    These can be output by OpenSSL.
+
+    ::
+
+        openssl ecparam -outform der -name <curve name> | base64
+
+    Or packed using :mod:`pyasn1`.
+    """
 
     EC_POINT = 0x00000181
 

pkcs11/defaults.py

@@ -15,23 +15,21 @@
     KeyType.AES: Mechanism.AES_KEY_GEN,
     KeyType.RSA: Mechanism.RSA_PKCS_KEY_PAIR_GEN,
     KeyType.DH: Mechanism.DH_PKCS_KEY_PAIR_GEN,
+    KeyType.EC: Mechanism.EC_KEY_PAIR_GEN,
 }
 """
 Default mechanisms for generating keys.
 """
 
-_DEFAULT_CAPS = \
-    MechanismFlag.ENCRYPT | \
-    MechanismFlag.DECRYPT | \
-    MechanismFlag.SIGN | \
-    MechanismFlag.VERIFY | \
-    MechanismFlag.WRAP | \
-    MechanismFlag.UNWRAP
+_ENCRYPTION = MechanismFlag.ENCRYPT | MechanismFlag.DECRYPT
+_SIGNING = MechanismFlag.SIGN | MechanismFlag.VERIFY
+_WRAPPING = MechanismFlag.WRAP | MechanismFlag.UNWRAP
 
 DEFAULT_KEY_CAPABILITIES = {
-    KeyType.AES: _DEFAULT_CAPS,
-    KeyType.RSA: _DEFAULT_CAPS,
-    KeyType.DH: _DEFAULT_CAPS | MechanismFlag.DERIVE,
+    KeyType.AES: _ENCRYPTION | _SIGNING | _WRAPPING,
+    KeyType.RSA: _ENCRYPTION | _SIGNING | _WRAPPING,
+    KeyType.DH: MechanismFlag.DERIVE,
+    KeyType.EC: _SIGNING | MechanismFlag.DERIVE,
 }
 """
 Default capabilities for generating keys.
@@ -63,6 +61,7 @@
 
 DEFAULT_DERIVE_MECHANISMS = {
     KeyType.DH: Mechanism.DH_PKCS_DERIVE,
+    KeyType.EC: Mechanism.ECDH1_DERIVE,
 }
 """
 Default mechanisms for key derivation
@@ -95,6 +94,8 @@ def _enum(type_):
     Attribute.CLASS: _enum(ObjectClass),
     Attribute.DECRYPT: _bool,
     Attribute.DERIVE: _bool,
+    Attribute.EC_PARAMS: _bytes,
+    Attribute.EC_POINT: _bytes,
     Attribute.ENCRYPT: _bool,
     Attribute.EXTRACTABLE: _bool,
     Attribute.ID: _bytes,

pkcs11/mechanisms.py

@@ -23,8 +23,13 @@ class KeyType(IntEnum):
     of the PKCS#11 specification for valid :class:`Mechanism` and
     :class:`pkcs11.constants.Attribute` types.
     """
-    ECDSA = 0x00000003
     EC = 0x00000003
+    """
+    See the `Elliptic Curve section
+    <http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/csd01/pkcs11-curr-v2.40-csd01.html#_Toc372721391>`_
+    of the PKCS#11 specification for valid :class:`Mechanism` and
+    :class:`pkcs11.constants.Attribute` types.
+    """
     X9_42_DH = 0x00000004
     KEA = 0x00000005
     GENERIC_SECRET = 0x00000010
@@ -120,7 +125,22 @@ class Mechanism(IntEnum):
     DSA_SHA384 = 0x00000015
     DSA_SHA512 = 0x00000016
     DH_PKCS_KEY_PAIR_GEN = 0x00000020
+    """
+    Default mechanism for generating :attr:`KeyType.DH` keypairs from
+    :class:`pkcs11.DomainParameters`.
+
+    Requires :class:`pkcs11.DomainParameters` of
+    :attr:`pkcs11.constants.Attribute.BASE` and
+    :attr:`pkcs11.constants.Attribute.PRIME`.
+    """
     DH_PKCS_DERIVE = 0x00000021
+    """
+    Default mechanism for deriving shared keys from :attr:`KeyType.DH` private
+    keys.
+
+    Takes the other participant's public key
+    :attr:`pkcs11.constants.Attribute.VALUE` as the `mechanism_param`.
+    """
 
     X9_42_DH_KEY_PAIR_GEN = 0x00000030
     X9_42_DH_DERIVE = 0x00000031
@@ -375,8 +395,14 @@ class Mechanism(IntEnum):
     BATON_SHUFFLE = 0x00001035
     BATON_WRAP = 0x00001036
 
-    ECDSA_KEY_PAIR_GEN = 0x00001040
     EC_KEY_PAIR_GEN = 0x00001040
+    """
+    Default mechanism for generating :attr:`KeyType.EC` keypairs from
+    :class:`pkcs11.DomainParameters`.
+
+    Requires :class:`pkcs11.DomainParameters` of
+    :attr:`pkcs11.constants.Attribute.EC_PARAMS`.
+    """
 
     ECDSA = 0x00001041
     ECDSA_SHA1 = 0x00001042
@@ -386,6 +412,19 @@ class Mechanism(IntEnum):
     ECDSA_SHA512 = 0x00001046
 
     ECDH1_DERIVE = 0x00001050
+    """
+    Default mechanism for deriving shared keys from :attr:`KeyType.EC` private
+    keys.
+
+    Takes a tuple of:
+
+    * key derivation function (:class:`pkcs11.mechanisms.KDF`);
+    * shared value (:class:`bytes`); and
+    * other participant's :attr:`pkcs11.constants.Attribute.EC_POINT`
+      (:class:`bytes`)
+
+    as the `mechanism_param`.
+    """
     ECDH1_COFACTOR_DERIVE = 0x00001051
     ECMQV_DERIVE = 0x00001052
 
@@ -464,3 +503,22 @@ class Mechanism(IntEnum):
 
     def __repr__(self):
         return '<Mechanism.%s>' % self.name
+
+
+class KDF(IntEnum):
+    """
+    Key Derivation Functions.
+    """
+    NULL = 0x00000001
+    SHA1 = 0x00000002
+
+    SHA1_ASN1 = 0x00000003
+    SHA1_CONCATENATE = 0x00000004
+    SHA224 = 0x00000005
+    SHA256 = 0x00000006
+    SHA384 = 0x00000007
+    SHA512 = 0x00000008
+    CPDIVERSIFY = 0x00000009
+
+    def __repr__(self):
+        return '<KDF.%s>' % self.name