Support PKCS#11 for mutual TLS on Unix platforms (#451)

Merging the `pkcs11` feature branch to `main`. Previous Pull Requests can be found here:

- #410 - Add PKCS#11 headers
- #408 - Public API first pass
- #412 - Implement library load/unload
- #413 - Get tests running in CI
- #425 - Find private key / begin s2n integration
- #428 - Finish integration with s2n
- #430 - Add tests. Each test now sets up its own tokendir.
- #431 - Misc fixes
- #432 - Add TLS test
- #434 - Handle connection failure during PKCS#11 operations
- #439 - Support multiple digest types for RSA
- #440 - Misc fixes
- #445 - Each CKR_ return value has its own AWS error-code
- #443 - Add license for PKCS#11 headers
- #442 - Behavior enum controls how C_Initialize() and C_Finalize() are called.
- #450 - Misc fixes

Co-authored-by: Prateek Yadav <[email protected]>

Author: graebm

.builder/actions/pkcs11_test_setup.py

@@ -0,0 +1,106 @@
+"""
+Prepare for PKCS#11 tests by configuring SoftHSM2, if it is installed.
+"""
+
+import Builder
+
+import os
+import re
+
+
+class Pkcs11TestSetup(Builder.Action):
+    """
+    Set up this machine for running the PKCS#11 tests.
+    If SoftHSM2 cannot be installed, the tests are skipped.
+
+    This action should be run in the 'pre_build_steps' or 'build_steps' stage.
+    """
+
+    def run(self, env):
+        self.env = env
+
+        # total hack: don't run PKCS#11 tests when building all C libs with -DBUILD_SHARED_LIBS=ON.
+        # here's what happens:  libsofthsm2.so loads the system libcrypto.so and
+        # s2n loads the aws-lc's libcrypto.so and really strange things start happening.
+        # this wouldn't happen in the real world, just in our tests, so just bail out
+        if any('BUILD_SHARED_LIBS=ON' in arg for arg in env.args.args):
+            print("WARNING: PKCS#11 tests disabled when BUILD_SHARED_LIBS=ON due to weird libcrypto.so behavior")
+            return
+
+        # try to install softhsm
+        try:
+            softhsm_install_acion = Builder.InstallPackages(['softhsm'])
+            softhsm_install_acion.run(env)
+        except:
+            print("WARNING: softhsm could not be installed. PKCS#11 tests are disabled")
+            return
+
+        softhsm_lib = self._find_softhsm_lib()
+        if softhsm_lib is None:
+            print("WARNING: libsofthsm2.so not found. PKCS#11 tests are disabled")
+            return
+
+        # set cmake flag so PKCS#11 tests are enabled
+        env.project.config['cmake_args'].append('-DENABLE_PKCS11_TESTS=ON')
+
+        # put SoftHSM config file and token directory under the build dir.
+        softhsm2_dir = os.path.join(env.build_dir, 'softhsm2')
+        conf_path = os.path.join(softhsm2_dir, 'softhsm2.conf')
+        token_dir = os.path.join(softhsm2_dir, 'tokens')
+        env.shell.mkdir(token_dir)
+        self._setenv('SOFTHSM2_CONF', conf_path)
+        with open(conf_path, 'w') as conf_file:
+            conf_file.write(f"directories.tokendir = {token_dir}\n")
+
+        # print SoftHSM version
+        self._exec_softhsm2_util('--version')
+
+        # sanity check SoftHSM is working
+        self._exec_softhsm2_util('--show-slots')
+
+        # set env vars for tests
+        self._setenv('TEST_PKCS11_LIB', softhsm_lib)
+        self._setenv('TEST_PKCS11_TOKEN_DIR', token_dir)
+
+    def _find_softhsm_lib(self):
+        """Return path to SoftHSM2 shared lib, or None if not found"""
+
+        # note: not using `ldconfig --print-cache` to find it because
+        # some installers put it in weird places where ldconfig doesn't look
+        # (like in a subfolder under lib/)
+
+        for lib_dir in ['lib64', 'lib']: # search lib64 before lib
+            for base_dir in ['/usr/local', '/usr', '/',]:
+                search_dir = os.path.join(base_dir, lib_dir)
+                for root, dirs, files in os.walk(search_dir):
+                    for file_name in files:
+                        if 'libsofthsm2.so' in file_name:
+                            return os.path.join(root, file_name)
+        return None
+
+
+    def _exec_softhsm2_util(self, *args, **kwargs):
+        if not 'check' in kwargs:
+            kwargs['check'] = True
+
+        result = self.env.shell.exec('softhsm2-util', *args, **kwargs)
+
+        # older versions of softhsm2-util (2.1.0 is a known offender)
+        # return error code 0 and print the help if invalid args are passed.
+        # This should be an error.
+        #
+        # invalid args can happen because newer versions of softhsm2-util
+        # support more args than older versions, so what works on your
+        # machine might not work on some ancient docker image.
+        if 'Usage: softhsm2-util' in result.output:
+            raise Exception('softhsm2-util failed')
+
+        return result
+
+    def _setenv(self, var, value):
+        """
+        Set environment variable now,
+        and ensure the environment variable is set again when tests run
+        """
+        self.env.shell.setenv(var, value)
+        self.env.project.config['test_env'][var] = value

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
       - '!main'
 
 env:
-  BUILDER_VERSION: v0.8.27
+  BUILDER_VERSION: v0.8.31
   BUILDER_SOURCE: releases
   BUILDER_HOST: https://d19elf31gohf1l.cloudfront.net
   PACKAGE_NAME: aws-c-io

CMakeLists.txt

@@ -147,17 +147,21 @@ elseif (CMAKE_SYSTEM_NAME STREQUAL "FreeBSD" OR CMAKE_SYSTEM_NAME STREQUAL "NetB
 
 endif()
 
-if (NOT BYO_CRYPTO AND USE_S2N)
+if (BYO_CRYPTO)
+    set(USE_S2N OFF)
+
+    if (APPLE OR WIN32)
+            message(FATAL_ERROR "BYO_CRYPTO is only for use with unix systems. It cannot be used on your current platform target")
+    endif()
+endif()
+
+if (USE_S2N)
     file(GLOB AWS_IO_TLS_SRC
             "source/s2n/*.c"
             )
     aws_use_package(s2n)
 endif()
 
-if (BYO_CRYPTO AND (APPLE OR WIN32))
-    message(FATAL_ERROR "BYO_CRYPTO is only for use with unix systems. It cannot be used on your current platform target")
-endif()
-
 file(GLOB IO_HEADERS
         ${AWS_IO_HEADERS}
         ${AWS_IO_OS_HEADERS}

PKCS11.md

@@ -0,0 +1,55 @@
+# PKCS#11 tests
+
+To run the PKCS#11 tests, configure cmake with: `-DENABLE_PKCS11_TESTS=ON`
+
+and set the following environment variables:
+
+```
+TEST_PKCS11_LIB = <path-to-shared-lib>
+TEST_PKCS11_TOKEN_DIR = <path-to-softhsm-token-dir>
+```
+TEST_PKCS11_LIB is used by the tests to peform pkcs11 operations.
+
+TEST_PKCS11_TOKEN_DIR is used by the tests to clear the softhsm tokens before a test begins. This is achieved by cleaning the token directory <b>NOTE: Any tokens created outside the tests will be cleaned up along with all the objects/keys on it as part of the tests.</b> 
+
+
+## The suggested way to set up your machine
+1)  Install [SoftHSM2](https://www.opendnssec.org/softhsm/) via brew / apt / apt-get / yum:
+    ```
+    > apt install softhsm
+    ```
+
+    Check that it's working:
+    ```
+    > softhsm2-util --show-slots
+    ```
+
+    If this spits out an error message, create a config file:
+    *   Default location: `~/.config/softhsm2/softhsm2.conf`
+    *   This file must specify token dir, default value is:
+        ```
+        directories.tokendir = /usr/local/var/lib/softhsm/tokens/
+        ```
+
+2)  Set env vars like so:
+    ```
+    TEST_PKCS11_LIB = <path to libsofthsm2.so>
+    TEST_PKCS11_TOKEN_DIR = /usr/local/var/lib/softhsm/tokens/
+    ```
+
+
+3)  [Example to import your keys, Not used by tests] Create token and private key
+
+    You can use any values for the labels, pin, key, cert, CA etc.
+    Here are copy-paste friendly commands for using files available in this repo.
+    ```
+    > softhsm2-util --init-token --free --label my-test-token --pin 0000 --so-pin 0000
+    ```
+
+    Note which slot the token ended up in
+
+    ```
+    > softhsm2-util --import tests/resources/unittests.p8 --slot <slot-with-token> --label my-test-key --id BEEFCAFE --pin 0000
+    ```
+    <b>WARN: All tokens created outside the tests would be cleaned up as part of the tests, Use a separate token directory for running the tests if you would like to keep your tokens intact.</b>
+

THIRD-PARTY-LICENSES.txt

@@ -0,0 +1,31 @@
+** PKCS#11 Headers; version 2.40 -- http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/include/pkcs11-v2.40/
+
+Copyright (c) OASIS Open 2016. All Rights Reserved.
+
+All capitalized terms in the following text have the meanings assigned to them
+in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The
+full Policy may be found at the OASIS website:
+[http://www.oasis-open.org/policies-guidelines/ipr]
+
+This document and translations of it may be copied and furnished to others, and
+derivative works that comment on or otherwise explain it or assist in its
+implementation may be prepared, copied, published, and distributed, in whole or
+in part, without restriction of any kind, provided that the above copyright
+notice and this section are included on all such copies and derivative works.
+However, this document itself may not be modified in any way, including by
+removing the copyright notice or references to OASIS, except as needed for the
+purpose of developing any document or deliverable produced by an OASIS
+Technical Committee (in which case the rules applicable to copyrights, as set
+forth in the OASIS IPR Policy, must be followed) or as required to translate it
+into languages other than English.
+
+The limited permissions granted above are perpetual and will not be revoked by
+OASIS or its successors or assigns.
+
+This document and the information contained herein is provided on an "AS IS"
+basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
+INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
+FITNESS FOR A PARTICULAR PURPOSE. OASIS AND ITS MEMBERS WILL NOT BE LIABLE FOR
+ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE
+OF THIS DOCUMENT OR ANY PART THEREOF.

builder.json

@@ -12,8 +12,14 @@
         { "name": "aws-c-mqtt" },
         { "name": "aws-c-http" }
     ],
+    "targets": {
+        "linux": {
+            "_comment": "set up SoftHSM2 for PKCS#11 tests (see: ./builder/actions/pkcs11_test_setup.py)",
+            "+pre_build_steps": ["pkcs11-test-setup"]
+        }
+    },
     "build_env": {
-        "LSAN_OPTIONS": "suppressions={source_dir}/tests/resources/suppressions.txt:allow_addr2line=1",
-        "CMAKE_BUILD_PARALLEL_LEVEL": "2"
+        "LSAN_OPTIONS": "suppressions={source_dir}/tests/resources/suppressions-lsan.txt:allow_addr2line=1",
+        "ASAN_OPTIONS": "suppressions={source_dir}/tests/resources/suppressions-asan.txt"
     }
 }

include/aws/io/io.h

@@ -134,6 +134,109 @@ enum aws_io_errors {
     AWS_IO_TLS_ALERT_NOT_GRACEFUL,
     AWS_IO_MAX_RETRIES_EXCEEDED,
     AWS_IO_RETRY_PERMISSION_DENIED,
+    AWS_IO_TLS_DIGEST_ALGORITHM_UNSUPPORTED,
+    AWS_IO_TLS_SIGNATURE_ALGORITHM_UNSUPPORTED,
+
+    AWS_ERROR_PKCS11_VERSION_UNSUPPORTED,
+    AWS_ERROR_PKCS11_TOKEN_NOT_FOUND,
+    AWS_ERROR_PKCS11_KEY_NOT_FOUND,
+    AWS_ERROR_PKCS11_KEY_TYPE_UNSUPPORTED,
+    AWS_ERROR_PKCS11_UNKNOWN_CRYPTOKI_RETURN_VALUE,
+
+    /* PKCS#11 "CKR_" (Cryptoki Return Value) as AWS error-codes */
+    AWS_ERROR_PKCS11_CKR_CANCEL,
+    AWS_ERROR_PKCS11_CKR_HOST_MEMORY,
+    AWS_ERROR_PKCS11_CKR_SLOT_ID_INVALID,
+    AWS_ERROR_PKCS11_CKR_GENERAL_ERROR,
+    AWS_ERROR_PKCS11_CKR_FUNCTION_FAILED,
+    AWS_ERROR_PKCS11_CKR_ARGUMENTS_BAD,
+    AWS_ERROR_PKCS11_CKR_NO_EVENT,
+    AWS_ERROR_PKCS11_CKR_NEED_TO_CREATE_THREADS,
+    AWS_ERROR_PKCS11_CKR_CANT_LOCK,
+    AWS_ERROR_PKCS11_CKR_ATTRIBUTE_READ_ONLY,
+    AWS_ERROR_PKCS11_CKR_ATTRIBUTE_SENSITIVE,
+    AWS_ERROR_PKCS11_CKR_ATTRIBUTE_TYPE_INVALID,
+    AWS_ERROR_PKCS11_CKR_ATTRIBUTE_VALUE_INVALID,
+    AWS_ERROR_PKCS11_CKR_ACTION_PROHIBITED,
+    AWS_ERROR_PKCS11_CKR_DATA_INVALID,
+    AWS_ERROR_PKCS11_CKR_DATA_LEN_RANGE,
+    AWS_ERROR_PKCS11_CKR_DEVICE_ERROR,
+    AWS_ERROR_PKCS11_CKR_DEVICE_MEMORY,
+    AWS_ERROR_PKCS11_CKR_DEVICE_REMOVED,
+    AWS_ERROR_PKCS11_CKR_ENCRYPTED_DATA_INVALID,
+    AWS_ERROR_PKCS11_CKR_ENCRYPTED_DATA_LEN_RANGE,
+    AWS_ERROR_PKCS11_CKR_FUNCTION_CANCELED,
+    AWS_ERROR_PKCS11_CKR_FUNCTION_NOT_PARALLEL,
+    AWS_ERROR_PKCS11_CKR_FUNCTION_NOT_SUPPORTED,
+    AWS_ERROR_PKCS11_CKR_KEY_HANDLE_INVALID,
+    AWS_ERROR_PKCS11_CKR_KEY_SIZE_RANGE,
+    AWS_ERROR_PKCS11_CKR_KEY_TYPE_INCONSISTENT,
+    AWS_ERROR_PKCS11_CKR_KEY_NOT_NEEDED,
+    AWS_ERROR_PKCS11_CKR_KEY_CHANGED,
+    AWS_ERROR_PKCS11_CKR_KEY_NEEDED,
+    AWS_ERROR_PKCS11_CKR_KEY_INDIGESTIBLE,
+    AWS_ERROR_PKCS11_CKR_KEY_FUNCTION_NOT_PERMITTED,
+    AWS_ERROR_PKCS11_CKR_KEY_NOT_WRAPPABLE,
+    AWS_ERROR_PKCS11_CKR_KEY_UNEXTRACTABLE,
+    AWS_ERROR_PKCS11_CKR_MECHANISM_INVALID,
+    AWS_ERROR_PKCS11_CKR_MECHANISM_PARAM_INVALID,
+    AWS_ERROR_PKCS11_CKR_OBJECT_HANDLE_INVALID,
+    AWS_ERROR_PKCS11_CKR_OPERATION_ACTIVE,
+    AWS_ERROR_PKCS11_CKR_OPERATION_NOT_INITIALIZED,
+    AWS_ERROR_PKCS11_CKR_PIN_INCORRECT,
+    AWS_ERROR_PKCS11_CKR_PIN_INVALID,
+    AWS_ERROR_PKCS11_CKR_PIN_LEN_RANGE,
+    AWS_ERROR_PKCS11_CKR_PIN_EXPIRED,
+    AWS_ERROR_PKCS11_CKR_PIN_LOCKED,
+    AWS_ERROR_PKCS11_CKR_SESSION_CLOSED,
+    AWS_ERROR_PKCS11_CKR_SESSION_COUNT,
+    AWS_ERROR_PKCS11_CKR_SESSION_HANDLE_INVALID,
+    AWS_ERROR_PKCS11_CKR_SESSION_PARALLEL_NOT_SUPPORTED,
+    AWS_ERROR_PKCS11_CKR_SESSION_READ_ONLY,
+    AWS_ERROR_PKCS11_CKR_SESSION_EXISTS,
+    AWS_ERROR_PKCS11_CKR_SESSION_READ_ONLY_EXISTS,
+    AWS_ERROR_PKCS11_CKR_SESSION_READ_WRITE_SO_EXISTS,
+    AWS_ERROR_PKCS11_CKR_SIGNATURE_INVALID,
+    AWS_ERROR_PKCS11_CKR_SIGNATURE_LEN_RANGE,
+    AWS_ERROR_PKCS11_CKR_TEMPLATE_INCOMPLETE,
+    AWS_ERROR_PKCS11_CKR_TEMPLATE_INCONSISTENT,
+    AWS_ERROR_PKCS11_CKR_TOKEN_NOT_PRESENT,
+    AWS_ERROR_PKCS11_CKR_TOKEN_NOT_RECOGNIZED,
+    AWS_ERROR_PKCS11_CKR_TOKEN_WRITE_PROTECTED,
+    AWS_ERROR_PKCS11_CKR_UNWRAPPING_KEY_HANDLE_INVALID,
+    AWS_ERROR_PKCS11_CKR_UNWRAPPING_KEY_SIZE_RANGE,
+    AWS_ERROR_PKCS11_CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT,
+    AWS_ERROR_PKCS11_CKR_USER_ALREADY_LOGGED_IN,
+    AWS_ERROR_PKCS11_CKR_USER_NOT_LOGGED_IN,
+    AWS_ERROR_PKCS11_CKR_USER_PIN_NOT_INITIALIZED,
+    AWS_ERROR_PKCS11_CKR_USER_TYPE_INVALID,
+    AWS_ERROR_PKCS11_CKR_USER_ANOTHER_ALREADY_LOGGED_IN,
+    AWS_ERROR_PKCS11_CKR_USER_TOO_MANY_TYPES,
+    AWS_ERROR_PKCS11_CKR_WRAPPED_KEY_INVALID,
+    AWS_ERROR_PKCS11_CKR_WRAPPED_KEY_LEN_RANGE,
+    AWS_ERROR_PKCS11_CKR_WRAPPING_KEY_HANDLE_INVALID,
+    AWS_ERROR_PKCS11_CKR_WRAPPING_KEY_SIZE_RANGE,
+    AWS_ERROR_PKCS11_CKR_WRAPPING_KEY_TYPE_INCONSISTENT,
+    AWS_ERROR_PKCS11_CKR_RANDOM_SEED_NOT_SUPPORTED,
+    AWS_ERROR_PKCS11_CKR_RANDOM_NO_RNG,
+    AWS_ERROR_PKCS11_CKR_DOMAIN_PARAMS_INVALID,
+    AWS_ERROR_PKCS11_CKR_CURVE_NOT_SUPPORTED,
+    AWS_ERROR_PKCS11_CKR_BUFFER_TOO_SMALL,
+    AWS_ERROR_PKCS11_CKR_SAVED_STATE_INVALID,
+    AWS_ERROR_PKCS11_CKR_INFORMATION_SENSITIVE,
+    AWS_ERROR_PKCS11_CKR_STATE_UNSAVEABLE,
+    AWS_ERROR_PKCS11_CKR_CRYPTOKI_NOT_INITIALIZED,
+    AWS_ERROR_PKCS11_CKR_CRYPTOKI_ALREADY_INITIALIZED,
+    AWS_ERROR_PKCS11_CKR_MUTEX_BAD,
+    AWS_ERROR_PKCS11_CKR_MUTEX_NOT_LOCKED,
+    AWS_ERROR_PKCS11_CKR_NEW_PIN_MODE,
+    AWS_ERROR_PKCS11_CKR_NEXT_OTP,
+    AWS_ERROR_PKCS11_CKR_EXCEEDED_MAX_ITERATIONS,
+    AWS_ERROR_PKCS11_CKR_FIPS_SELF_TEST_FAILED,
+    AWS_ERROR_PKCS11_CKR_LIBRARY_LOAD_FAILED,
+    AWS_ERROR_PKCS11_CKR_PIN_TOO_WEAK,
+    AWS_ERROR_PKCS11_CKR_PUBLIC_KEY_INVALID,
+    AWS_ERROR_PKCS11_CKR_FUNCTION_REJECTED,
 
     AWS_IO_ERROR_END_RANGE = AWS_ERROR_ENUM_END_RANGE(AWS_C_IO_PACKAGE_ID),
     AWS_IO_INVALID_FILE_HANDLE = AWS_ERROR_INVALID_FILE_HANDLE,

include/aws/io/logging.h

@@ -29,6 +29,7 @@ enum aws_io_log_subject {
     AWS_LS_IO_SHARED_LIBRARY,
     AWS_LS_IO_EXPONENTIAL_BACKOFF_RETRY_STRATEGY,
     AWS_LS_IO_STANDARD_RETRY_STRATEGY,
+    AWS_LS_IO_PKCS11,
     AWS_IO_LS_LAST = AWS_LOG_SUBJECT_END_RANGE(AWS_C_IO_PACKAGE_ID)
 };