DTLS on SAM R21 Xplained Pro: Guide/Demo - Revision history

BVogler: removed a wrong line

2024-06-18T16:16:05Z

removed a wrong line

← Older revision		Revision as of 16:16, 18 June 2024
Line 1:		Line 1:
	~~Title: DTLS on SAM R21 Xplained Pro: Guide/Demo~~

	== Summary ==		== Summary ==
	This article supplies the instructions to setup a DTLS connection by using RIOT-OS and the WolfSSL DTLS example provided by RIOT-OS. The first part guides the user in setting up two SAM R21 Xplained Pro microcontrollers using the example application and establish a connection between them using DTLS and RIOTs generic networking stack. The second part guides the user in setting up virtual native boards in RIOT and establish a DTLS-based connection between them. This is done to make capturing the DTLS packets possible via Wireshark.		This article supplies the instructions to setup a DTLS connection by using RIOT-OS and the WolfSSL DTLS example provided by RIOT-OS. The first part guides the user in setting up two SAM R21 Xplained Pro microcontrollers using the example application and establish a connection between them using DTLS and RIOTs generic networking stack. The second part guides the user in setting up virtual native boards in RIOT and establish a DTLS-based connection between them. This is done to make capturing the DTLS packets possible via Wireshark.

BVogler: minor corrections

2024-06-18T16:14:59Z

minor corrections

← Older revision		Revision as of 16:14, 18 June 2024
Line 1:		Line 1:
			Title: DTLS on SAM R21 Xplained Pro: Guide/Demo

	== Summary ==		== Summary ==
	This article supplies the instructions to setup a DTLS connection ~~demonstration~~ by using RIOT-OS and the WolfSSL DTLS example provided by RIOT-OS. The first part guides the user in setting up two SAM R21 Xplained Pro microcontrollers using the example application ~~to connect~~ using DTLS. The second part guides the user in setting up virtual boards in RIOT. This is done to make capturing the DTLS packets possible.		This article supplies the instructions to setup a DTLS connection by using RIOT-OS and the WolfSSL DTLS example provided by RIOT-OS. The first part guides the user in setting up two SAM R21 Xplained Pro microcontrollers using the example application and establish a connection between them using DTLS and RIOTs generic networking stack. The second part guides the user in setting up virtual native boards in RIOT and establish a DTLS-based connection between them. This is done to make capturing the DTLS packets possible via Wireshark.

	== Requirements ==		== Requirements ==
Line 6:		Line 8:
	You must have followed the [[Riot-OS Setup]] step 1, 2 and 3 before using this guide. It is assumed that RIOT-OS is installed to ~/RIOT/.		You must have followed the [[Riot-OS Setup]] step 1, 2 and 3 before using this guide. It is assumed that RIOT-OS is installed to ~/RIOT/.

	* Operating system: Ubuntu 24.04 (~~Guide~~ was created running a VM on Oracle VirtualBox 6.1)		* Operating system: Ubuntu 24.04 (Note: This guide was created running Ubuntu as a Virtual Machine on Oracle VirtualBox 6.1)
	* Packages: git python3		* Packages: git python3

Line 14:		Line 16:
	This step is an addition to the [[Riot-OS Setup]].		This step is an addition to the [[Riot-OS Setup]].

	* Update your packages if you have not already done ~~this~~.		* Update your packages if you have not already done so.
	sudo apt-get update		sudo apt-get update
	* Install the pyudev package		* Install the pyudev package
Line 20:		Line 22:
	* Find out the serial numbers of your SAM R21 XPro devices and note them for later use		* Find out the serial numbers of your SAM R21 XPro devices and note them for later use
	make list-ttys		make list-ttys
	* Open two additional terminals and connect to both devices by using their ttys. (Adjust the code if your ttys differ)		* Open two additional terminals and connect to both devices by using their ttys. Adjust the code if your ttys differ.
	cd RIOT/dist/tools/pyterm		cd RIOT/dist/tools/pyterm
	./pyterm -p /dev/ttyACM0		./pyterm -p /dev/ttyACM0
Line 26:		Line 28:

	=== Step 2 ===		=== Step 2 ===
	Build the application and flash it on both devices.		Build the application and flash it onto both devices.

	* Navigate to the folder containing the WolfSSL DTLS example in RIOT and build the application		* Navigate to the folder containing the WolfSSL DTLS example in RIOT and build the application
Line 47:		Line 49:
	dtlsc IPv6-server-address		dtlsc IPv6-server-address

	[[File:WolfDTLS-Connection.png\|thumb\|none\|750px\|WolfSSL DTLS Example ~~successful~~ Connection]]		[[File:WolfDTLS-Connection.png\|thumb\|none\|750px\|WolfSSL DTLS Example Connection]]

	== Capturing DTLS Traffic ==		== Capturing DTLS Traffic ==
	If you want to capture and analyze the DTLS the packets using a packet sniffer, e.g. Wireshark, you have to use RIOT native boards. SAM R21 XPro devices are not powerful enough to support packet capture with Wireshark on their own.		If you want to capture and analyze the DTLS the packets using a packet sniffer, e.g. Wireshark, you have to use RIOT native boards, since SAM R21 XPro devices are not powerful enough to support packet capture with Wireshark on their own.

	=== Wireshark Setup ===		=== Wireshark Setup ===
Line 57:		Line 59:
	sudo apt install wireshark		sudo apt install wireshark
	* When asked if non-superusers should be able to catpure packets answer "Yes".		* When asked if non-superusers should be able to catpure packets answer "Yes".
	* Add user to the wireshark group to make capture possible		* Add your user to the wireshark group to make capture possible
	sudo usermod -a -G wireshark "$USER"		sudo usermod -a -G wireshark "$USER"
	* Check if the wireshark group is present for your user		* Check if the wireshark group is present for your user
	groups $USER		groups $USER
			* Log out and log in or restart your system to apply the change.

	=== Step 1 ===		=== Step 1 ===
	Setup a virtual network for RIOT instances by using the Tapsetup tool.		Setup a virtual network for RIOT instances by using the ''Tapsetup''-tool.
	* Navigate to the Tapsetup tool and create two virtual network taps and a virtual bridge		* Navigate to the ''Tapsetup''-tool and create two virtual network taps and a virtual bridge
	cd ~		cd ~
	cd RIOT/dist/tools/tapsetup		cd RIOT/dist/tools/tapsetup
Line 79:		Line 82:

	=== Step 2 ===		=== Step 2 ===
	Configure Wireshark to capture packets on either tap0, tap1 or tapbr0 (Bridge). This depends on which view is more interesting to you. In the following steps tap1 is used for capturing packets.		Configure Wireshark to capture packets on either tap0, tap1 or tapbr0 (Bridge). This depends on which view is more interesting to you. In the following steps tap1 is used for capturing packets since the DTLS server is run on this Tap.
	* Start Wireshark and set it to capture packets on interface tap1		* Start Wireshark and set it to capture packets on the interface tap1
	* Use the applications to setup a DTLS connection. First use ''ifconfig'' ~~and note~~ the IPv6 address ~~of the designated server application. Then~~ use the following ~~commands~~ to ~~setup~~ the ~~connection~~:		* Use the applications to setup a DTLS connection. First use ''ifconfig'' on one of the native boards. Note the IPv6 address and then use the following command to start the DTLS server:
	dtlss		dtlss
			* Use this command on the other native board using the address noted previously:
	dtlsc IPv6-server-address		dtlsc IPv6-server-address
			* You should receive confirmation of a successful connection.

	=== Step 3 ===		=== Step 3 ===

BVogler: first version

2024-06-18T14:21:12Z

first version

← Older revision		Revision as of 14:21, 18 June 2024
Line 1:		Line 1:
	== Summary ==		== Summary ==
			This article supplies the instructions to setup a DTLS connection demonstration by using RIOT-OS and the WolfSSL DTLS example provided by RIOT-OS. The first part guides the user in setting up two SAM R21 Xplained Pro microcontrollers using the example application to connect using DTLS. The second part guides the user in setting up virtual boards in RIOT. This is done to make capturing the DTLS packets possible.
	~~Description what this documentation~~ is ~~about~~.

	== Requirements ==		== Requirements ==

	* Operating system: Ubuntu 18.~~04 bionic amd64~~		You must have followed the [[Riot-OS Setup]] step 1, 2 and 3 before using this guide. It is assumed that RIOT-OS is installed to ~/RIOT/.
	* Packages: git emacs

	~~In order to complete these steps, you must have followed [[Some Other Documentation]] before~~.		* Operating system: Ubuntu 24.04 (Guide was created running a VM on Oracle VirtualBox 6.1)
			* Packages: git python3

	== Description ==		== Description ==

	=== Step 1 ===		=== Step 1 ===
			This step is an addition to the [[Riot-OS Setup]].

			* Update your packages if you have not already done this.
			sudo apt-get update
			* Install the pyudev package
			sudo apt-get install python3-pyudev
			* Find out the serial numbers of your SAM R21 XPro devices and note them for later use
			make list-ttys
			* Open two additional terminals and connect to both devices by using their ttys. (Adjust the code if your ttys differ)
			cd RIOT/dist/tools/pyterm
			./pyterm -p /dev/ttyACM0
			./pyterm -p /dev/ttyACM1

			=== Step 2 ===
			Build the application and flash it on both devices.

	~~Enter these commands~~ in the ~~shell~~		* Navigate to the folder containing the WolfSSL DTLS example in RIOT and build the application
			cd RIOT/examples/dtls-wolfssl
			make BOARD=samr21-xpro
			* Flash the newly built application onto both devices using their serial numbers
			make BOARD=samr21-xpro SERIAL="ATML21270318xxxxxxx" flash
			make BOARD=samr21-xpro SERIAL="ATML21270318xxxxxxx" flash
			* The example application is now running on both devices. Use command ''help'' to show the available options

	~~echo foo~~		[[File:DTLS-WolfSSL-Help.png\|thumb\|none\|750px\|WolfSSL DTLS Example Help Menu]]
	~~echo bar~~
			=== Step 3 ===
			Use the applications to setup a DTLS connection

			* Use ''ifconfig'' on the device that is designated as the server and note the IPv6 address
			* Start the DTLS Server
			dtlss
			* Use the DTLS Client to start the connection test
			dtlsc IPv6-server-address

			[[File:WolfDTLS-Connection.png\|thumb\|none\|750px\|WolfSSL DTLS Example successful Connection]]

			== Capturing DTLS Traffic ==
			If you want to capture and analyze the DTLS the packets using a packet sniffer, e.g. Wireshark, you have to use RIOT native boards. SAM R21 XPro devices are not powerful enough to support packet capture with Wireshark on their own.

			=== Wireshark Setup ===
			Follow the steps to install Wireshark on Ubuntu 24.04, if necessary:
			* Install Wireshark
			sudo apt install wireshark
			* When asked if non-superusers should be able to catpure packets answer "Yes".
			* Add user to the wireshark group to make capture possible
			sudo usermod -a -G wireshark "$USER"
			* Check if the wireshark group is present for your user
			groups $USER

			=== Step 1 ===
			Setup a virtual network for RIOT instances by using the Tapsetup tool.
			* Navigate to the Tapsetup tool and create two virtual network taps and a virtual bridge
			cd ~
			cd RIOT/dist/tools/tapsetup
			sudo ./tapsetup --create 2
			* Build dtls-wolfdtls for RIOT native boards
			cd ~
			cd RIOT/examples/dtls-wolfssl
			make all
			* Setup the first virtual RIOT board
			PORT=tap0 make term
			* Setup the second virtual RIOT board using a second terminal
			cd RIOT/examples/dtls-wolfssl
			PORT=tap1 make term

	=== Step 2 ===		=== Step 2 ===
			Configure Wireshark to capture packets on either tap0, tap1 or tapbr0 (Bridge). This depends on which view is more interesting to you. In the following steps tap1 is used for capturing packets.
			* Start Wireshark and set it to capture packets on interface tap1
			* Use the applications to setup a DTLS connection. First use ''ifconfig'' and note the IPv6 address of the designated server application. Then use the following commands to setup the connection:
			dtlss
			dtlsc IPv6-server-address

	~~Make sure to read~~		=== Step 3 ===
			Analyze the captured traffic in Wireshark
	* War and Peace
	* Lord of the ~~Rings~~
	* The Baroque Cycle

			[[File:WolfDTLS-Wireshark-Capture.png\|thumb\|none\|750px\|WolfSSL DTLS Example Wireshark Capture]]

	== Used Hardware ==		== Used Hardware ==

	[[~~Device to be used with this documentation~~]]		* 2x [[Atmel SAM R21 Xplained Pro]]
	~~[[Maybe another device to be used with this documentation]]~~		* Connective cables (Micro USB B)

	== Courses ==		== Courses ==

	* [[~~A course where this documentation was used~~]] ~~(2017, 2018)~~		* [[Riot-OS Setup]]
	* [[Another one]] (2018)

	== References ==		== References ==

	* https://~~wikipedia~~.org		* https://www.riot-os.org/
	* https://~~google~~.com		* https://www.wolfssl.com/

	[[Category:Documentation]]		[[Category:Documentation]]

BVogler: init

2024-06-18T11:46:37Z

init

New page

== Summary ==

Description what this documentation is about.

== Requirements ==

* Operating system: Ubuntu 18.04 bionic amd64
* Packages: git emacs

In order to complete these steps, you must have followed [[Some Other Documentation]] before.

== Description ==

=== Step 1 ===

Enter these commands in the shell

echo foo
echo bar

=== Step 2 ===

Make sure to read

* War and Peace
* Lord of the Rings
* The Baroque Cycle

== Used Hardware ==

[[Device to be used with this documentation]]
[[Maybe another device to be used with this documentation]]

== Courses ==

* [[A course where this documentation was used]] (2017, 2018)
* [[Another one]] (2018)

== References ==

* https://wikipedia.org
* https://google.com

[[Category:Documentation]]