Duo Authentication Library for ESP32 Micro Controllers

An Arduino Library to simplify the operations of performing Duo Multi-Factor Authentication within your ESP32 Micro Controller project

Overview

The Duo Authentication Library was created to abstract the Duo Auth API Authentication Requirements. These requirements, which utilizes the HMAC_SHA1 algorithm, NTP Time Source, and Duo Application details (API Host, Application/Integration Key, and Secret Key) to sign the properly formatted requests before being sent to Duo's Auth API. The library has been targeted for the Espressif ESP32 Micro Controllers, due to the built-in crypto hardware support for both the HTTPS and HMAC Signature requirements.

Duo Security extends various API Endpoints for use. In particular, this Library's focus is on Duo's Authentication API .

Features

The Duo Authentication Library enables the following features/functionality:

Duo Mobile Push Authentication
Duo Asynchronous Mobile Push Authentication
Duo Passcode Authentication
Ability to set device's IP Address for Duo Auth API Requests
Ability to set Duo's Mobile Push Notification Type (This string is displayed before the word "Request")
Various Duo Authentication API Response fields exposed with easy to use functions
Includes 4 example sketches to demonstrate the use of the library

Key Design Requirements

The library was created with the following Key Duo API Requirements in Mind:

Accurate Time Source for Signing the Authorization Signature
- Note: This variable can be declared as Global, Private 'setup();' or 'loop();', or within your own Method/Function that will interface with the Duo Auth Library! It is strongly suggested that you leverage a Global variable if you are using a primary authentication source as well!
Simple to use functions for anyone to get up and quickly as well as incorporating into your existing projects
Built-in URL Encoding as required for certain usernames or other API properties
Functions that enable granular 'Authentication' decision making based on Duo's Auth API Responses
Initial Library scope primarily targeted mainly Duo Push and Passcode functionality

Technologies & Frameworks Used

The library was built to provide a simple and easy to use interface for the Duo Auth API on Espressif's ESP32 Micro Controllers. The library is written for the use within the Arduino IDE.

Cisco Products & Services:

Duo Security

Duo Authentication API Endpoints in use:

This library abstracts most of the Duo Auth API functionality. The specific API Endpoints leveraged by this library are as follows:

GET /auth/v2/ping
GET /auth/v2/check
POST /auth/v2/auth
GET /auth/v2/auth_status

Tools & Frameworks:

Arduino IDE (Tested on v1.8.12) or PlatformIO for VSCode IDE
Arduino Core for the ESP32
ArduinoJson Library for Arduino and IoT Devices

I would like to thank all the authors & contributers on the previously mentioned Tools & Frameworks!

The Documentation and Guides available from these tools, contained the details needed to bring this Library to life. Below are links to references used for the above Tools & Frameworks:
- Arduino - Writing a Library for Arduino https://www.arduino.cc/en/Hacking/LibraryTutorial
- ArduinoJson - Deserialization Tutorial https://arduinojson.org/v6/doc/deserialization/

Hardware Required:

Espressif ESP32 WiFi Micro-controller
User Input Device
- 10 Digit Keypad
- LCD Touch Screen
- Serial/RS-232 Device
- RFID Reader/NFC Reader
- Etc..

Installation

Arduino IDE

Note: This document assumes that your Arduino IDE is already setup and configured for Espressif's ESP32 Micro Controllers (Arduino Core for the ESP32)

To install the Duo Authentication Library in your Arduino IDE, follow the instructions below:
- Browse to the Duo Authentication Library Releases GitHub Page
- Download Latest Duo Authentication Library package version (Choose ZIP Package)
- Follow the "Installing Additional Arduino Libraries" documentation at Arduino's Library Documentation Site

PlatformIO for VSCode IDE

To install the Duo Authentication Library in your PlatformIO for VSCode IDE, follow the instructions below:
- Open VSCode PlatformIO Core CLI
- Execute the following installation command
  - pio lib install https://github.com/CiscoDevNet/Arduino-DuoAuthLibrary-ESP32/archive/v1.0.0.zip

Library Usage

Example Sketches

Included as part of the Duo Authentication Library are 4 Arduino example sketches, which outline and demonstrate how to use the library. The examples included are:

Push Authentication - Provides example on a Duo Library Push Authentication
Passcode Authentication - Provides example on a Duo Library Passcode Authentication
Asynchronous Push Authentication - Provides example on an Asynchronous Duo Push Authentication
Common Functions - Provides examples on the Libraries Common Functions

Configuration Requirements

The following parameters are required inputs into the Duo Authentication Library:

NTP Server (Intranet or Internet) and other Time Variables

 const char* ntpServer = "pool.ntp.org";
 
 //Adjusting these values from '0' are not necessary
 const long  gmtOffset_sec = 0;
 const int   daylightOffset_sec = 0;

WiFi SSID & Pre-Shared Key

 const char* ssid = "MyWirelessAP";
 const char* wirelessPsk =  "MySecretWiFiPassword";

Time Info Variable Declaration & Configuration

The Time Info structure provides the necessary variable for the NTP server to update the time, which is used by the Duo Auth Library.

 //Create timeinfo variable.  Note: This can be declared globally or within the function using the Duo Auth Library
 struct tm timeinfo;
 
 //Configure the Time settings
 configTime(gmtOffset_sec, daylightOffset_sec, ntpServer);

Root Certificate Authority (CA) Public Certificate for the Duo API Host

See Root Certificate Authority Section
Duo API Hostname
```
 const char* duo_host = "";
```
Duo Application/Integration Key
```
 const char* duo_akey = "";
```
Duo Secret Key
```
 const char* duo_skey = "";
```
Username
Passcode of User, if using Duo Passcode Authentication

For a more comprehensive view into the Configuration Requirements and Library use, please view the included example sketches.

Root Certificate Authority

Duo Authentication API calls are performed over HTTPS, and as such we require a trustpoint to know that we are communicating with our trusted Duo API Host.

You will need to export the Base64 Encoded X.509 Public Key of the Root Certificate Authority for your Duo API Host (duo_host).

Once exported, you will need to format the Base64 Output similar to the example below:

const char* root_ca= \
"-----BEGIN CERTIFICATE-----\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx\n" \
"XxXxXxXxXxXx\n" \
"-----END CERTIFICATE-----\n";

Authors & Maintainers

The following people are responsible for the creation and/or maintenance of this project:

Gary Oppel gaoppel@cisco.com

License

This project is licensed to you under the terms of the Apache License, Version 2.0.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

ScaredyCat/Arduino-DuoAuthLibrary-ESP32