MAKE DIGEST API WITH ARDUINO

Arduino IP Device API

This sketch connects to an IP device with digest authentication using an Arduino WIZnet Ethernet shield, and sends API requests to it.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Detailed Function Explanation
   • getHttpRequest
   • postHttpRequest
   • getCNonce
   • getDigestAuth
   • getContentAfterContentLength
5. Roadmap
6. Contributing
7. Hardware Compatibility and Future Versions
8. License
9. Contact
10. Acknowledgments

About The Project

Digest authentication is a method utilized by web servers to authenticate users. It offers a more secure alternative to basic authentication by sending hashed passwords instead of plaintext ones over the network. Here's a brief overview of how digest authentication works:

1. Client Request: The client sends a request to access a protected resource on the server.

2. Server Challenge: The server responds with a 401 Unauthorized status code along with a challenge that includes a nonce (a unique value), realm (authentication domain), and other parameters.

3. Client Authentication: The client computes a hash of the username, password, and other parameters along with the server challenge. This hash is sent back to the server as part of the Authorization header in subsequent requests.

4. Server Verification: Upon receiving the hash from the client, the server verifies it by recomputing the hash using the same parameters and comparing it with the received hash. If they match, the server grants access to the requested resource.

This project implements digest authentication to establish a secure connection between the Arduino microcontroller and the IP device. It follows the RFC 2617 standard to generate and verify the necessary authentication credentials.

(back to top)

Built With

• SPI Library
• Ethernet Library
• MD5 Library

(back to top)

Usage

This sketch is designed to connect to an IP device with digest authentication and send API requests to it. It can be used with any microcontroller equipped with an Ethernet shield.

To use this sketch with your specific setup, you'll need to modify certain parts of the code to adapt it to your situation. Specifically, you'll need to update the string fields found in the config.h file. Here's a brief explanation of each field:

1. username: Replace <USERNAME> with the username required for authentication with your IP device.

2. password: Replace <PASSWORD> with the password required for authentication with your IP device.

3. server_pointer: Replace http://192.168.1.200 with the address of your IP device. Make sure to include the appropriate protocol (use http://, Unlike the https:// because it has not been tested) and the IP address or domain name of your device.

4. uri: You have uncomment the uri field and replace /cgi-bin/example with the specific API endpoint of your IP device if needed.

Once you have updated these fields in the config.h file, upload the sketch to your Arduino board and open the serial monitor to observe the output.

(back to top)

Roadmap

• Implementing error handling mechanisms
• Enhancing API request functionality
• Adding support for additional authentication methods

See the open issues for a full list of proposed features (and known issues).

(back to top)

Getting Started

Prerequisites & Installation

1. Connect the Ethernet shield to the Arduino board.
2. Clone the repository and open the sketch in the Arduino IDE.
3. Set the appropriate IP address, MAC address, DNS, gateway, and subnet mask for your network.
4. Upload the sketch to your Arduino board.
5. Open the serial monitor to view the output.

(back to top)

Detailed Function Explanation

In this section, we provide a detailed explanation of the various functions implemented in the code. While the code could be further optimized, it has been designed with educational purposes in mind.

getHttpRequest(EthernetClient& client, const String& uri)

This function performs a GET request to the server specified by uri using the provided EthernetClient. It establishes a connection with the server, sends the request, and waits for the response. Once the response is received, it returns it as a string.

postHttpRequest(EthernetClient& client, const String& uri, const String& content)

Similar to getHttpRequest, this function performs a POST request to the server specified by uri using the provided EthernetClient. It includes the content in the request body. It establishes a connection with the server, sends the request, and waits for the response. Once the response is received, it returns it as a string.

getCNonce(const int len)

This function generates a random string of alphanumeric characters of length len. It is primarily used in generating the client nonce (cnonce) for digest authentication.

getDigestAuth(String& responseString, const String& username, const String& password, const String& uri, unsigned int counter)

This function generates the digest authentication header required for authenticating with the server. It parses the server's challenge response (responseString) to extract the realm, nonce, and other parameters required for digest authentication. It then computes the MD5 hash of the username, password, and other parameters according to RFC 2617 specifications and constructs the authorization header.

getContentAfterContentLength(const String& httpResponse)

This function extracts the content of the HTTP response after the Content-Length header. It is used to retrieve the actual API response from the server's HTTP response.

These functions together facilitate the communication between the Arduino microcontroller and the IP device, enabling secure authentication and data exchange over the network.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Hardware Compatibility and Future Versions

It's important to note that this code is designed to work specifically with Arduino boards equipped with an Ethernet connection. This includes boards like the Arduino Uno with an Ethernet shield or the Arduino Mega with built-in Ethernet support. The code utilizes the Ethernet library for network communication.

If you're using a different type of board, such as the ESP32 or ESP8266, which are commonly used for WiFi connectivity, this code won't be directly compatible. However, if this project receives positive feedback and demand for support on WiFi-enabled boards, a separate version of the code could be developed to accommodate these platforms.

In a potential future version for WiFi-enabled boards, the code would likely utilize libraries such as WiFiClient for communication over WiFi networks. This would enable compatibility with a broader range of microcontroller boards, expanding the reach of the project to a wider audience.

For now, this project serves as a functional demonstration of digest authentication implementation on Arduino boards with Ethernet connectivity, with potential future iterations to support additional hardware platforms. If yu like it! Leave a star ⭐️

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Giuseppe Tururro - WHOAMI? - @turturrogiuseppe - info.g.turturro@gmail.com

Project Link: https://github.com/zEhmsy/Arduino-Digest-Api

(back to top)

Acknowledgments

• RFC 2617
• Arduino Forum

(back to top)