search

zephyrproject-rtos / zephyr

Primary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.
https://docs.zephyrproject.org
Apache License 2.0
10.8k stars 6.58k forks source link

Zephyr Authentication - ZAUTH #23465

Closed deangereaux closed 3 years ago

deangereaux commented 4 years ago

ZAUTH - Zephyr Authentication

November 2020

More and more devices can now connect to each other, remote servers, and mobile devices. This added functionality provides end-users with better, more fully featured products, but at the very real risk of malicious attacks. The ability to authenticate peer communications, along with secure messaging, is how devices can protect themselves. Unfortunately, most RTOS systems do not have a framework or library to authenticate devices. The purpose of this ZAUTH proposal is to provide an easy to use framework to authenticate two peers over different transports such as Bluetooth and Serial. Zephyr is uniquely positioned with a large installed base and security as one of its key goals.

Some examples of device connectivity include:

  1. Mobile app connecting to a room control via Bluetooth to control light settings.
  2. Conveyor controller and remote sensors to detect speed and load.
  3. Consumable authentication such as printer cartridges or continuous glucose monitor sensor.

An initial implementation can be found here: https://github.com/GoldenBitsSoftware/zephyr see: feature/auth_lib branch. BLE Authentication source files are located here: subsystem/bluetooth/services/auth_*.c. Sample source files are located here: samples/bluetooth/authenticated_connection

Proposed Change

ZAUTH is a library to provide a consistent set of APIs to authenticate peer devices over an arbitrary transport such as Bluetooth or Serial. The authentication method and transport layer are selectable using the existing Zephyr KConfig process. The underlying transport is abstracted from the ZAUTH authentication methods using an opaque transport handle. This initial proposal supports Bluetooth and Serial (UART) transports along with Challenge-Response and DTLS authentication methods. ZAUTH is design to accommodate additional authentication methods and transports.

ZAUTH library code location is in the following directories from the Zephyr root:

Directory Description
lib/auth Source and internal header files
include/auth Public header files for use by applications
samples/auth ZAUTH Samples
test/lib/auth Unit test files
doc/reference/auth Documentation

Ease of use is an important goal of ZAUTH, most developers treat security as a headache. ZAUTH is easily integrated by using the following KConfig menu selections under “Additional libraries->Authentication library” as shown below.

Kconfig

Authentication API

The Authentication API is designed to abstract away the authentication method and transport. The calling application configures the ZAUTH library, starts the authentication process and monitors results via a status callback. The API is also designed to handle multiple concurrent authentication processes, for example If device is acting as a Bluetooth Central and Peripheral. An example of the API used is shown in the following code snippet.

static authenticate_conn central_auth_conn;

void auth_status(struct authenticate_conn *auth_conn, enum auth_instance_id instance, auth_status_t status, void *context)
{
    if(status == AUTH_STATUS_SUCCESSFUL) {
        printk(“Authentication Successful.\n”);
    } else {
        printk(“Authentication status: %s\n”, auth_lib_getstatus_str(status));
    }
}

/* BLE connection callback */
void connected(struct bt_conn *conn, u8_t err) 
{
   /* start authentication */
   auth_lib_start(&central_auth_conn);
}

void main(void)
{
    int err = auth_lib_init(&central_auth_conn, AUTH_INST_1, auth_status, NULL,
                             opt_parms, flags);

    err = bt_enabled(NULL);

    while(true) {
        k_yield();
    }
}

Client Server Model

ZAUTH is designed as a client server model for the authentication message flow. The client initiates the authentication messaging sequence where the server responds. Depending on the authentication method chosen (Challenge-Response, DTLS, other), mutual authentication can be used to authenticate both sides of the connection. For some transports, this model maps nicely to the native transport model. Bluetooth is an example of this, a peripheral is in the server role and the central is in the client role. For Serial transports, the choice of which endpoint acts as the client or server is up to the application firmware.

Authentication Instances

Multiple authentication instances are possible concurrently authenticating connections over different communication links. For example, a Bluetooth central device could use different instances to authenticate different peripherals. Another example could be a HVAC controller with Bluetooth to communicate with mobile devices and a serial interface to control HVAC equipment. One instance would authenticate the mobile device, the second instance would authenticate the HVAC equipment.

Under the hood, an authentication Instance is a Zephyr thread and authentication method.

Authentication Methods

Two authentication methods are proposed, DTLS and simple Challenge-Response. However, the authentication architecture can support additional authentication methods in the future.

The proposed authentication is done at the application layer after connecting over the lower transport. This requires the firmware application to ignore or reject any messages until the authentication process has completed. This complicates the application firmware but does enable authentication independent of a vendor’s stack such as Bluetooth, TCP/IP, or serial. In addition, most embedded engineers have no desire to modify a vendor’s stack.

Secure Hardware Elements

Secure hardware elements provide a high level of security and cryptographic functionality at a low cost and power consumption. Ideal for resource constraint IoT devices. The key material and operations are performed in hardware, no keys are stored in the code. Common use cases include ECC or RSA key generation, signature verification, certificate storage, and key storage. Some examples of secure hardware are the Microchip ATECC608A, NXP SE050, and Infineon OPTIGA Trust M SLS32AIA. Each authentication method can potentially use secure hardware, however this initial version of ZAUTH will not support secure elements.

Detailed Design

The high-level diagram below shows the main ZAUTH components.

Highlevel

Authentication is performed in a separate thread started by the application. Each authentication method uses a dedicated thread to exchange authentication message with their peer. Adding additional authentication methods is done by creating a authentication instance. Messages are passed between the authentication thread and lower transport using an abstracted transport handle which maps to a Tx or Rx queue. The authentication threads are unaware of how messages are transferred. Optionally the lower transport can be configured to bypass the Tx queue and send the message directly to the lower transport, by passing the Tx queue. This is ideal for lower transports that handle their own message queueing.

An Authentication method is a defined message protocol between two peers. The message protocol contains details of the contents and the order of messages. The DTLS protocol is an example of a detailed authentication protocol. Messages are different sizes and depending on the lower transport, may not fit into a transports MTU size. For example, the default MTU for Bluetooth is 23 bytes versus the 512 byte minimum possible for DTLS record.

Authentication messages larger than the underlying transport MTU are fragmented; ZAUTH disassembles and re-assembles messages over the transport layer. For example, if a 267 byte message is send over a Bluetooth link with an MTU of 150, ZAUTH will break up the message into one 150 byte message and a second 117 byte fragments when sending. The receiving side will reassemble the fragments into the original 267 byte message before forwarding to the Rx queue. An important caveat is ZAUTH does not handle reordering of fragments, if fragment 2 arrives before fragment 1, the message is corrupted. The diagram below shows how the Tx and Rx queues are used along with message fragmentation.

Highlevel

The Bluetooth Central Authentication sample (see samples/authentication/bluetooth/central_auth) provides a good example to drill deeper into the transport layer interface and how Bluetooth is “hooked up” to ZAUTH. The GREEN boxes are Bluetooth transport specific.

Transport Layer In auth_xp_bt_init() the Bluetooth connection (struct bt_conn) is added, along with the transport handle, to a connection using the struct auth_xport_connection_map

Transport Layer Interface

Transport layer details vary greatly, it does not make sense to create a one-size-fits-all transport API. ZAUTH separates the transport into transport independent and transport specific. For example, the details of the Bluetooth transport are in the auth_xport_bt.c file. This includes direct calls into the Zephyr Bluetooth stack. The transport common function, auth_xport_init(), calls the transport specific initialization function, passing the opaque transport handle (auth_xport_hdl_t) as an argument and transport specific parameters. The lower transport is responsible for mapping any transport specific variables to the transport handle. For example, the Bluetooth transport internally maps the transport handle to a Bluetooth connection handle, struct bt_conn.

The organization of the transport layers are show in the following diagram

Transport Interface

Additional Topics

Comparison of Bluetooth Pairing and Authentication

Simply put, for commercial IoT applications pairing is not authentication. The Bluetooth version 5 specification does define three methods of authentication (Bluetooth spec version 5, Vol 2, Part F, Section 4.2.9): a) Numeric Comparison, b) Passkey, and c) Out of Band. All of these methods require a display on the device and a human in the loop. In all of these options, the user is manually performing the authentication. For commercial IoT applications, this is not an option. Imagine a commercial building where hundreds of light switches (the IoT devices) must be manually paired. Error prone and costly work.

Pairing establishes an encryption key for both parties (Central and Peripheral), which is different from validating the identity of the remote peer. This is true for both Legacy and LE Secure pairing. While LE Secure pairing uses an ECC keypair and Diffie-Hellman Elliptic Curve to protect against eavesdropping, there is no capability to identify the remote peer.

GATT Authentication

GATT Authentication defined in the Bluetooth spec (Version 5, Vol 3, Part G, Section 8.1) is used to enable a per characteristic authentication using a shared key. It does not authenticate a Bluetooth peer (Central or Peripheral).

Google Fast Pair Service (GFPS)

This is a pairing method developed by Google to quickly pair consumer devices with and a phone and user’s account. See: https://developers.google.com/nearby/fast-pair/spec, for details. It is part of Google’s Nearby platform (see: https://developers.google.com/nearby). Authentication is accomplished by pre-shared keys provide by Google after registering your device (the thing you’re developing) with Google. While GFPS provides a great user experience, it has several drawbacks, specifically: a) requires a mobile phone, b) requires Google approval for your device, and c) licensing may not be consistent with Zephyr.

aescolar commented 4 years ago

CC: @jhedberg @carlescufi @Vudentz

carlescufi commented 4 years ago

@deangereaux thanks for the submission!

Could you please include a small paragraph about why the existing fast-pair spec is not a viable alternative?

deangereaux commented 4 years ago

@carlescufi Added paragraph. I view GFPS as another possible authentication method provided by ZEBRA. Let me know if I missed any key points about GFPS. Thanks!!

dleach02 commented 4 years ago

However Why not use this shared key for BLE link layer encryption? Why not set this key into the Zephyr Bluetooth stack after the DTLS handshake

Not sure you need to complicate this as it seems the key establishment in BLE is okay. Since you are attempting to deal with the "I have the device" and "I'm authenticated" to use the device this seems to fill the "Out of Band" part of the section you referenced above.

endian-benjamin commented 4 years ago

Maybe I'm missing a crucial paragraph, but it seems to me that this has little to do with Bluetooth specifically? I mean, it seems you want to decouple DTLS from its traditional UDP/IP dependency, which seems like a noble goal to me, but this all sounds equally applicable to for example direct serial communication, or NFC, or the homebrew 433 MHz Footooth protocol I just made up. Right?

Why not just decouple it further - an easy-to-use, transport-agnostic authentication lib on one hand, and a Bluetooth-specific implementation on the other?

deangereaux commented 4 years ago

The API is designed to be transport agnostic so yes in future versions there is no reason why ZEBRA shouldn’t be able to authenticate over a serial line or other transport. The ZEBRA design allows for different authentication methods and potentially different transports by adding a different transport specific thread, serial for example. However the transport and authentication are not cleanly decoupled as suggested, which has been previously suggested and is a very good idea. I’ll take hard look at implementing this separation.

The reason Bluetooth is the initial focus is simple, it is the most common use case. This is actually why I started creating ZEBRA, I’ve been asked many times over the past 3 years to design and develop an authentication method for a phone to device via BLE

Thanks for the feedback.

carlescufi commented 4 years ago

API meeting:

Dean proposes: subsys/auth/zebra and include/auth/zebra.h

galak commented 4 years ago

dev-review: (Apr 16) - suggestion is put it under lib.

Some comment about having this as a module:

pabigot commented 4 years ago

For context: it appears these are the files changed/added to support this feature in its current form from https://github.com/GoldenBitsSoftware/zephyr (there may be false positives, since a rebase had a lot of conflicts):

:100644 100644 fcc258172c 9babd347a1 M  include/bluetooth/conn.h
:000000 100644 0000000000 4c3595ebc1 A  include/bluetooth/services/auth_svc.h
:100644 100644 4faf696d13 cb76da7b2a M  include/bluetooth/uuid.h
:000000 100644 0000000000 06f1c57a9e A  samples/bluetooth/authenticated_connection/README.rst
:000000 100644 0000000000 168bc616f4 A  samples/bluetooth/authenticated_connection/central_auth/CMakeLists.txt
:000000 100644 0000000000 88d3044b90 A  samples/bluetooth/authenticated_connection/central_auth/prj.conf
:000000 100644 0000000000 a287aea3d3 A  samples/bluetooth/authenticated_connection/central_auth/sample.yaml
:000000 100644 0000000000 eabd45cc4e A  samples/bluetooth/authenticated_connection/central_auth/src/main.c
:000000 100644 0000000000 ac6fc11d64 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_ca_chain.h
:000000 100644 0000000000 ccf71ccacb A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_central.crt
:000000 100644 0000000000 984996a6df A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_central.der
:000000 100644 0000000000 f19f56c8e8 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_central_cert.h
:000000 100644 0000000000 a9b784789b A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_central_key.h
:000000 100644 0000000000 64773a94d4 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_central_key.pem
:000000 100644 0000000000 0e06a7b819 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_interca.crt
:000000 100644 0000000000 04397276f3 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_interca.der
:000000 100644 0000000000 a9c7686ba7 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_peripheral.crt
:000000 100644 0000000000 baf15b1dd8 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_peripheral.der
:000000 100644 0000000000 fcb4a32789 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_peripheral_cert.h
:000000 100644 0000000000 195b8c9dcc A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_peripheral_key.h
:000000 100644 0000000000 9114e38d82 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_peripheral_key.pem
:000000 100644 0000000000 c8e2bf9fbd A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_rootca.crt
:000000 100644 0000000000 0952e11559 A  samples/bluetooth/authenticated_connection/cert_chain/ble_auth_all_certs/bleauth_rootca.der
:000000 100644 0000000000 5d88823fd6 A  samples/bluetooth/authenticated_connection/peripheral_auth/CMakeLists.txt
:000000 100644 0000000000 57ba915463 A  samples/bluetooth/authenticated_connection/peripheral_auth/prj.conf
:000000 100644 0000000000 a287aea3d3 A  samples/bluetooth/authenticated_connection/peripheral_auth/sample.yaml
:000000 100644 0000000000 9d66a85035 A  samples/bluetooth/authenticated_connection/peripheral_auth/src/main.c
:100644 100644 2ac270f2ff 7f9d1a561c M  samples/bluetooth/central_hr/src/main.c
:100644 100644 b0d8248bc7 0bc4072d62 M  subsys/bluetooth/Kconfig
:100644 100644 e9c0c6010c b075866842 M  subsys/bluetooth/host/conn.c
:100644 100644 d345df0369 5f104ffc8a M  subsys/bluetooth/host/conn_internal.h
:100644 100644 a321120997 47c6d3f12a M  subsys/bluetooth/services/CMakeLists.txt
:100644 100644 8e0202c8c9 60afeab5b7 M  subsys/bluetooth/services/Kconfig
:000000 100644 0000000000 2466cac0de A  subsys/bluetooth/services/Kconfig.auths
:000000 100644 0000000000 eb7f519013 A  subsys/bluetooth/services/auth_chalresp.c
:000000 100644 0000000000 9148e4ed81 A  subsys/bluetooth/services/auth_common.c
:000000 100644 0000000000 23326d1374 A  subsys/bluetooth/services/auth_internal.h
:000000 100644 0000000000 78f20b7c0f A  subsys/bluetooth/services/auth_l2cap.c
:000000 100644 0000000000 b44f2b4964 A  subsys/bluetooth/services/auth_loopback.c
:000000 100644 0000000000 777c97d9c6 A  subsys/bluetooth/services/auth_svc.c
:000000 100644 0000000000 37684fb5cf A  subsys/bluetooth/services/auth_tls.c

Based on this it appears a module could work. It does not look like something I would expect to find in lib. Could {subsys,include}/bluetooth be extended with a ext or not-sig or other subdirectory for extensions that are not standard (yet)?

deangereaux commented 4 years ago

@pabigot Regarding the current state of: https://github.com/GoldenBitsSoftware/zephyr. Yes I need to update, rebase, etc.

deangereaux commented 4 years ago

Current status.
a) Moving code to lib/auth b) Refactoring code to make library independent of transport (ie Bluetooth, Serial, etc). c) Adding transport layer API.

pabigot commented 4 years ago

API 2020-07-07: Moved from triage to in-progress.

deangereaux commented 4 years ago

Current status: a) The transport independent layer is in place. b) Adding serial (UART) transport example. c) Added code to handle message (dis)assembly when sending a larger message over a transport with smaller MTU. d) Created samples/authentication directory to contain all authentication samples. e) Current work in progress can be found here: https://github.com/GoldenBitsSoftware/zephyr/tree/feature/auth_lib

deangereaux commented 4 years ago

I've re-worked the majority of the code, still more to do but getting close to formally creating a PR. Here is the latest design document.
ZAUTH_Zephyr_9-2020.pdf

Chandranshu9 commented 3 years ago

If this is not the right place to ask this question then please tell me where to ask.

Please help me integrate Zephyr authentication- ZAUTH so that I can run sample bluetooth authentication code available. Below is the error I am getting while doing build in Ubuntu terminal:

Parsing /home/chandranshu/zephyrproject/zephyr/Kconfig Loaded configuration '/home/chandranshu/zephyrproject/zephyr/boards/arm/arduino_nano_33_iot/arduino_nano_33_iot_defconfig' Merged configuration '/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf'

error: HAS_NRFX (defined at modules/Kconfig.nordic:187) is assigned in a configuration file, but is not directly user-configurable (has no prompt). It gets its value indirectly from other symbols. See http://docs.zephyrproject.org/latest/reference/kconfig/CONFIG_HAS_NRFX.html and/or look up HAS_NRFX in the menuconfig/guiconfig interface. The Application Development Primer, Setting Configuration Values, and Kconfig - Tips and Best Practices sections of the manual might be helpful too.

CMake Error at /home/chandranshu/zephyrproject/zephyr/cmake/kconfig.cmake:251 (message): command failed with return code: 1 Call Stack (most recent call first): /home/chandranshu/zephyrproject/zephyr/cmake/app/boilerplate.cmake:608 (include) CMakeLists.txt:4 (include)

-- Configuring incomplete, errors occurred!

deangereaux commented 3 years ago

@Chandranshu9 HAS_NRFX is platform specific for the Nordic nRF52 SOCs and should not be in the prj.conf file. Go ahead and remove and try to re-create. Also I fixed a bug recently, the stack size of the main thread was too small. You should also add CONFIG_MAIN_STACK_SIZE=4096 to the proj.conf file.

ZAUTH is still a work in progress, so there will be bugs. All of the initial development has been with the Nordic nRF52840 Dev kit (see: https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-DK). I'm hoping to finish and submit a formal PR by the end of December.

Chandranshu9 commented 3 years ago

@Chandranshu9 HAS_NRFX is platform specific for the Nordic nRF52 SOCs and should not be in the prj.conf file. Go ahead and remove and try to re-create. Also I fixed a bug recently, the stack size of the main thread was too small. You should also add CONFIG_MAIN_STACK_SIZE=4096 to the proj.conf file.

ZAUTH is still a work in progress, so there will be bugs. All of the initial development has been with the Nordic nRF52840 Dev kit (see: https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-DK). I'm hoping to finish and submit a formal PR by the end of December.

Hello @deangereaux, Thanks for your quick response, Yes removing HAS_NRFX solved my issue, Now I am receiving some Kconfig warnings, The same warnings were also shown when I was running the test version of authentication. Please help me with this. I am eagerly waiting for the final version of your ZAUTH, it looks very promising. Below is the error that I am receiving while building the code:-

Parsing /home/chandranshu/zephyrproject/zephyr/Kconfig Loaded configuration '/home/chandranshu/zephyrproject/zephyr/boards/arm/arduino_nano_33_iot/arduino_nano_33_iot_defconfig' Merged configuration '/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf'

/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf:6: warning: attempt to assign the value 'y' to the undefined symbol BT_GATT_DIS

/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf:22: warning: attempt to assign the value 'y' to the undefined symbol AUTH_LIB

/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf:23: warning: attempt to assign the value 'y' to the undefined symbol BT_XPORT

/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf:24: warning: attempt to assign the value 'y' to the undefined symbol AUTH_CHALLENGE_RESPONSE

/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf:27: warning: attempt to assign the value 'y' to the undefined symbol AUTH_CHALLENGE_RESPONSE

/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf:31: warning: attempt to assign the value '3' to the undefined symbol AUTH_LOG_LEVEL

/home/chandranshu/zephyrproject/zephyr/zephyr-feature-auth_lib/samples/authentication/bluetooth/central_auth/prj.conf:55: warning: attempt to assign the value 'y' to the undefined symbol MBEDTLS_CIPHER_CBC_ENABLED

error: Aborting due to Kconfig warnings

CMake Error at /home/chandranshu/zephyrproject/zephyr/cmake/kconfig.cmake:251 (message): command failed with return code: 1 Call Stack (most recent call first): /home/chandranshu/zephyrproject/zephyr/cmake/app/boilerplate.cmake:608 (include) CMakeLists.txt:4 (include)

-- Configuring incomplete, errors occurred!

deangereaux commented 3 years ago

@Chandranshu9 Not sure why you're getting these errors. I'll take a look later this week, in the mean time if you figure out what's causing these config errors, please let me know.

Chandranshu9 commented 3 years ago

@deangereaux This is because I am not able to integrate your ZAUTH with zephyrRTOS properly, Can you tell me how to integrate them both. I downloaded ZAUTH and pasted it inside zephyr folder. Are there any changes that need to be made for running your ZAUTH library properly with zephyrOS? I think if you can tell me how to install this properly then these issues will be solved.

deangereaux commented 3 years ago

@Chandranshu9 Let's move this conversation off this RFC doc. Please enter this info here as an issue: https://github.com/GoldenBitsSoftware/zephyr/issues

Chandranshu9 commented 3 years ago

@Chandranshu9 Let's move this conversation off this RFC doc. Please enter this info here as an issue: https://github.com/GoldenBitsSoftware/zephyr/issues

@deangereaux Sure, I have moved the issue. Please reply there.

deangereaux commented 3 years ago

I'm happy to announce, a PR has been submitted for ZAUTH PR: https://github.com/zephyrproject-rtos/zephyr/pull/31136

deangereaux commented 3 years ago

Closing.