Linux Configfs Gadgets

[David Bateman]

By default the USB Armory uses the legacy g_ether module. This modules is not recognized by Windows since the release of Windows 10. The reason is that the new RNDIS v6 driver file rndiscmp.inf does not include a matching regexp for the g_ether gadget. There are no options to the g_ether module allow the RNDIS v6 Windows driver to accept it.

There are many proposed solutions if you search the net, for example using an old RNDIS v5.1 driver, or an unsigned *.INF. However, the best solution is to no longer use the legacy g_ether driver but to convert the USB Armory to use the new Linux ConfigFS Gadget interface.

I've written a boot script, that is attached to do exactly this, which I'd like to share. To use it do the following

1. Install the script in /etc/init.d/armorygadget
2. Modify the variables lun0, lun1 at the top of the script (if using "mass" or "multi" mode). You'll have to create the backing store files yourself
   
3. Select the gadget mode "ether", "mass" or "multi"
   
4. ln -s /etc/init.d/armorygadget /etc/rc5.d/S01armorygadget
5. sed -i -e "/^g_ether/d" /etc/modules
6.  grep -qPzo "start\)\n.*sleep" /etc/init.d/isc_dhcp-server || sed -i -e "s/\(^.*\)start)/\1start)\n\1\tsleep 30/" /etc/init.d/isc-dhcp-server

The last action is needed to allow the ether gadget the time to start up before starting the dhcpd on this gadget.. I've been using this script for the last week without issues. Feel free to use this code however you like, as ideally I'd like to see something like this used by default on all USB Armory devices ;-)

D.

[David Bateman]

With the script this time

[Andrej Rosano]

Hello David,

thank you for the contribution. The refrence to this thread has been
added to the Host communication wiki page [1].

We will consider adding it to the default Debian image.

Thanks
Andrej

[1] https://github.com/usbarmory/usbarmory/wiki/Host-communication

On 2023-02-17 Fri, David Bateman wrote:
> With the script this time
>
> Le vendredi 17 février 2023 à 12:11:05 UTC+1, David Bateman a écrit :
>
> > By default the USB Armory uses the legacy g_ether module. This modules is
> > not recognized by Windows since the release of Windows 10. The reason is
> > that the new RNDIS v6 driver file rndiscmp.inf does not include a matching
> > regexp for the g_ether gadget. There are no options to the g_ether module
> > allow the RNDIS v6 Windows driver to accept it.
> >
> > There are many proposed solutions if you search the net, for example using
> > an old RNDIS v5.1 driver, or an unsigned *.INF. However, the best solution
> > is to no longer use the legacy g_ether driver but to convert the USB Armory
> > to use the new Linux ConfigFS Gadget interface.
> >
> > I've written a boot script, that is attached to do exactly this, which I'd
> > like to share. To use it do the following
> >

> > 1. Install the script in /etc/init.d/armorygadget
> > 2. Modify the variables lun0, lun1 at the top of the script (if using

> > "mass" or "multi" mode). You'll have to create the backing store files
> > yourself

> > 3. Select the gadget mode "ether", "mass" or "multi"
> > 4. ln -s /etc/init.d/armorygadget /etc/rc5.d/S01armorygadget
> > 5. sed -i -e "/^g_ether/d" /etc/modules
> > 6. grep -qPzo "start\)\n.*sleep" /etc/init.d/isc_dhcp-server || sed

> > -i -e "s/\(^.*\)start)/\1start)\n\1\tsleep 30/" /etc/init.d/isc-dhcp-server
> >
> > The last action is needed to allow the ether gadget the time to start up
> > before starting the dhcpd on this gadget.. I've been using this script for
> > the last week without issues. Feel free to use this code however you like,
> > as ideally I'd like to see something like this used by default on all USB
> > Armory devices ;-)
> >
> > D.
> >
>

> --
> You received this message because you are subscribed to the Google Groups "USB armory" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to usbarmory+...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/usbarmory/f0214101-b278-466b-994b-4ee4af8092d5n%40googlegroups.com.



--
Andrej Rosano | Hardware Security | WithSecure
www.withsecure.com - foundry.withsecure.com
BDE1 62F4 7020 1588 8046 AE02 EA17 8C32 AB56 54CE

[SemanticBeeng]

Hi,

Also having the issue the usb armory is not properly detected as Ethernet over USB (RNDIS) device on Windows 10 pro.

Using the usb armory with the Debian image so far but planning to experiment with the unikernels as well.  

Done a lot of research and think the above is best way to handle it.

But not familiar enough with the concepts to make sense of the script.

For example: what are these for the various modes? 

"You'll have to create the backing store files yourself" makes little sense to me at this time.

```

# A list of file backed storage devices for "mass" ou "multi"
# Upto 8 possible.. Adapt these for your use case
lun0="/mnt/disk1.img"
lun1="/mnt/disk2.iso"
```

Is there any official solution or work in progress at this time?

Any further guidance?

Many thanks

[David Bateman]

Your questions are quite general and so a bit difficult to give simple answers.. First a linux "usb gadget" is a kernel module that presents the USB armory as a USB device to a host computer. The default drivers used by the usb armory for this are "g_ether", "g_mass_storage" and "g_mutli". "g_ether" is the "gadget" to present the usb armory to the host computer as a usb ethernet device. "g_mass_storage" as a mass strorage device (either a USB key or CDRom) and "g_multi" does both.

Now these drivers are now obsolete, and are replaced with drivers controlled by ConfigFS (https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt). The "g_ether" driver identifies itself as a devices whose identity was remove from the Windows "*.INF" in Windows 10. So the "g_ether" drivers needs an unsigned *.INF file to be added to WIndows to allow it to be recognized. This is why I supplied the script I did, as it uses the new ConfigFS drivers to identify the USB ethernet gadget seen by the host as a device recognized by the W10 et W11 RNDIS 6.0 driver directly without modification of Windows.

The three modes "mass", "ether" and "multi" for my script correspond to the three default drivers of the usb armory. For the "backing stores" you need to understand that the mass_strorage_gagdet presents a "file" to the hosts system as if it is a filesystem. It presents upto 8 files as seperate LUNs to the hosts. These files can be ISO files which will be presented as if they are CD Roms (Not DVD Roms so limited in size to roughly 2GBytes), Or any other filesystem you want. I personally

prepare these files on the USB armory by installling the NTFS-3g package and doing

file="/mnt/disk1.img"

# Create 1GByte sparse file to accept filesystem (1024 blocks of 1M)

dd if=/dev/zero of="$file" bs=1M seek="1024" count=0 2> /dev/null

# Partition the sparse file so that windows sees it correctly

cat << EOF | /sbin/sfdisk -uS "$file"

,,7

EOF

# Get the information for the formatting from the partition

start=$(/sbin/fdisk -l "$file" | tail -1 | xargs | cut -d' ' -f2)

start=$((start * 512))

ldev=$(losetup -f) 

losetup -o $start "$ldev" "$file"

mkntfs -q -L "Name Of The Disk" -f "$ldev" > /dev/null 2> /dev/null

losetup -d "$ldev"

Though a much simplier means of formatting the disk is probably possible, the above formats the file in exactly the same manner as windows itself formats a USB key. So windows can't tell the difference from this and something it formatted itself.

PS: A great site to understand the ConfigFS gadget interface is https://wiki.tizen.org/USB/Linux_USB_Layers/Configfs_Composite_Gadget

[SemanticBeeng]

"these drivers are now obsolete, and are replaced with drivers controlled by ConfigFS"

Was wondering if these considerations and code should be a in the main code base(s) of usb armory instead of having to hack the built images.
Or at least documented with articles to bridge gaps to users who did not develop drivers but are exposed to such matters.

Asking only to better understand fit with current code.

Many thanks for details, David.
Will study further and try to make it work for the various builds / unikernels.

[Sam McGreedy]

Hello,

first of all I want to say thank you... your script makes my hole project working...

I am just wondiering if there is an option while building a custom debian image, to install the neccessary drivers, so you dont have to install the script into the running armory?

[Joerg Koenning]

Hi Andrej Rosano, could you, please, add this fix to the Debian package.

It would help us a lot with a Windows solution.

Kind regards, Joerg