path: root/host/doc/man/ubertooth-btle.1

.TH UBERTOOTH\-BTLE 1 "July 2018" "Project Ubertooth" "User Commands"
.SH NAME
.PP
ubertooth\-btle \-\- Bluetooth Low Energy (BLE) sniffing and more
.SH SYNOPSIS
.PP
.RS
.nf
ubertooth\-btle \-f [\-A 37|38|39] [\-r output.pcapng]
.fi
.RE
.SH DESCRIPTION
.PP
\fB\fCubertooth\-btle\fR is a tool for doing Fun 
.BR Stuff (TM) 
with BLE. It can do
the following things:
.RS
.IP \(bu 2
Sniff connections
.IP \(bu 2
Interfere with connections
.IP \(bu 2
Send advertising packets (experimental)
.RE
.PP
Sniffing connections is the most robust feature supported by
\fB\fCubertooth\-btle\fR\&. It has two primary modes of operation: follow mode and
promiscuous mode.
.PP
Follow mode is the preferred mode for general use. In this mode,
Ubertooth will listen on one of three advertising channels waiting for a
BLE connection to be established. When a connection is established,
Ubertooth will hop along the data channels, passively capturing the data
sent between the central and peripheral. After the connection
terminates, Ubertooth will return to the advertising channel and wait
for another connection.
.PP
No\-follow mode is similar to follow mode, but it only logs advertising
packets and will not follow connections as they are established.
.PP
Promiscuous mode is an experimental mode for sniffing connections after
they have already been established. This mode can be used to sniff
long\-lived connections.
.PP
When sniffing, Ubertooth can only operate in either follow mode or
promiscuous mode, but not both at the same time. If you are unsure which
mode to use, use follow mode.
.PP
By default, Ubertooth will follow any connection it observes. You can
limit this to following a specific Bluetooth Address (BD ADDR) using the
\fB\fC\-t\fR command line flag. For example, the following command will only
sniff connections where the central or peripheral's BD ADDR is
\fB\fC22:44:66:88:AA:CC\fR:
.PP
.RS
.nf
ubertooth\-btle \-f \-t22:44:66:88:AA:CC
.fi
.RE
.PP
\fB\fC\-t\fR can also take a mask length in CIDR\-like notation. Masks can be
between 1 and 48 bits long, with a 48 bit mask matching the entire
address. Using a /24 mask will filter on just the OUI. For example, to
limit sniffing to just TI devices with the OUI 00:1A:7D, use the
following:
.PP
.RS
.nf
ubertooth\-btle \-t 00:1A:7D:00:00:00/24
.fi
.RE
.PP
Filters persist until they are explicitly cleared or the system restarts
(either via \fB\fCubertooth\-util \-r\fR or unplug/replug). To clear a filter,
use the special filter \fB\fCnone\fR\&. Example:
.PP
.RS
.nf
ubertooth\-btle \-t none
.fi
.RE
.PP
When filtering, previous versions of the firmware would still log all
advertising packets but only follow connections based on the filter
parameters. As of 2018\-06\-R1, advertising packets that do not match the
filter are dropped.
.PP
In all sniffing modes, Ubertooth can log data to PCAP or PcapNG with a
variety of pseudoheaders. The recommended logging format is PcapNG
(\fB\fC\-r\fR) or PCAP with LE Pseudoheader (\fB\fC\-q\fR). For compatibility with
crackle (see [USING WITH CRACKLE][]), use PCAP with PPI (\fB\fC\-c\fR).
.PP
Interfering with connections is a feature for causing intentional
interference with newly established or long\-lived connections. When this
attack succeeds, the BLE connection between the central and peripheral
will be terminated. Pair the \fB\fC\-i\fR or \fB\fC\-I\fR flag with \fB\fC\-f\fR to interfere
with new connections or \fB\fC\-p\fR to interfere with long\-lived connections.
Note that causing intentional interference may be illegal in your
jurisdiction. Check your local laws before using this feature.
.PP
Finally, \fB\fCubertooth\-btle\fR supports transmitting advertising packets with
a specified BD ADDR. This feature, referred to as faux slave mode, is
experimental and may not function as intended. Use at your own risk.
.SH EXAMPLES
.PP
Sniff all connections on advertising channel 38, logging all data to
PcapNG:
.PP
.RS
.nf
ubertooth\-btle \-f \-A 38 \-r log.pcapng
.fi
.RE
.PP
Log advertising packets without following connections:
.PP
.RS
.nf
ubertooth\-btle \-n
.fi
.RE
.PP
Interfere with connections recovered with promiscuous mode:
.PP
.RS
.nf
ubertooth\-btle \-p \-I
.fi
.RE
.PP
Send advertising packets using BD ADDR \fB\fC22:44:66:88:AA:CC\fR:
.PP
.RS
.nf
ubertooth\-btle \-s22:44:66:88:AA:CC
.fi
.RE
.SH OPTIONS
.RS
.IP \(bu 2
\fB\fC\-h\fR :
Displays help message
.RE
.PP
Major modes:
.RS
.IP \(bu 2
\fB\fC\-f\fR :
Follow mode: sniff connections as they are established
.IP \(bu 2
\fB\fC\-n\fR :
No\-follow mode: log advertising packets but don't follow connections
.IP \(bu 2
\fB\fC\-p\fR :
Promiscuous mode: sniff already\-established connections
.IP \(bu 2
\fB\fC\-s<BD ADDR>\fR : 
Inject advertising packets using specified BD ADDR
.RE
.PP
Interference (pair with \fB\fC\-f\fR or \fB\fC\-p\fR):
.RS
.IP \(bu 2
\fB\fC\-i\fR :
Interfere with one connection and return to idle
.IP \(bu 2
\fB\fC\-I\fR :
Interfere continuously with many connections
.RE
.PP
Filtering:
.RS
.IP \(bu 2
\fB\fC\-t<BD ADDR>\fR :
Limit connection following and interference in follow mode to the
specified BD ADDR
.RE
.PP
Logging:
.RS
.IP \(bu 2
\fB\fC\-r <output.pcapng>\fR :
Log to PcapNG (preferred)
.IP \(bu 2
\fB\fC\-q <output.pcap>\fR :
Log to PCAP with \fB\fCDLT_BLUETOOTH_LE_LL_WITH_PHDR\fR
.IP \(bu 2
\fB\fC\-c <output.pcap>\fR :
Log to PCAP with PPI (for compatibility with 
.BR crackle (1))
.RE
.PP
Miscellaneous:
.RS
.IP \(bu 2
\fB\fC\-A <37|38|39>\fR :
Which advertising channel to use in follow mode (default: 37)
.IP \(bu 2
\fB\fC\-a[address]\fR :
Get or set access address in promiscuous mode
.IP \(bu 2
\fB\fC\-v[01]\fR :
Get or set CRC verification (default: 0)
.IP \(bu 2
\fB\fC\-x<0\-32>\fR :
Allow n access address violations (default: 32). Filtering occurs on
host.
.RE
.PP
Data source:
.RS
.IP \(bu 2
\fB\fC\-U<0\-7>\fR :
Which Ubertooth to use
.RE
.SH USING WITH CRACKLE
.PP
\fB\fCcrackle\fR is a tool for cracking the BLE key exchange and decrypting
encrypted data. To capture data for use with \fB\fCcrackle\fR, sniff
connections in follow mode using \fB\fC\-f\fR and log data to PCAP/PPI using
\fB\fC\-c\fR\&. Example:
.PP
.RS
.nf
ubertooth\-btle \-f \-c crack.pcap
.fi
.RE
.PP
Refer to \fB\fCcrackle\fR documentation for further details.
.SH SEE ALSO
.PP
.BR crackle (1): 
\[la]https://github.com/mikeryan/crackle\[ra]
.SH COPYRIGHT
.PP
\fB\fCubertooth\-btle\fR is Copyright (C) 2012\-2018 Mike Ryan. This tool is
released under the GPLv2. Refer to COPYING for futher details.