tls-session-tags

package: ktls-utils

title: tls-session-tags(7)

summary: TLS session tags

text:
# tls-session-tags(7)

## NAME
tls-session-tags - TLS session tags

## SYNOPSIS
/etc/tlshd/tags.d/

## DESCRIPTION
The tlshd program implements a user agent that services TLS handshake requests on behalf of kernel TLS consumers. Its configuration files, found under the /etc/tlshd directory, contain information that the tlshd program reads when it starts up. The configuration files direct the tlshd program to information about which trust store and signing and encryption algorithms are to be used. The configuration files are considered a trusted source of information.

When a peer presents an X.509 certificate during a TLS handshake, the tlshd program is responsible for verifying that the certificate was issued by a certificate authority that the receiver recognizes and trusts. Once that verification is successful, the receiver can trust the content of that certificate, including information about the peer identity presented in that certificate (e.g., a DNS hostname or IP address, and so on).

Once a peer's certificate is trusted, the tlshd program can be configured to scan the fields in the peer's certificate. Based on the scan, the tlshd program can assign tags to the new TLS session that indicate that the server recognizes the peer's identity. For example, the tlshd program can be configured to look for a specific string in subject fields, and assign tags to TLS sessions where the peer presented a certificate with matching content in that field. Kernel consumers can use those tags to authorize or deny access to resources based on the identity presented in peer certificates.

The following sections describe how to configure this facility.

## FORMAT
TLS session tag definitions are YAML documents stored in files in the /etc/tlshd/tags.d directory. When it launches, the tlshd program reads all files in that directory with either the .yml or .yaml extension. Modifications to the content of these files take effect only when the tlshd program is restarted.

The tlshd program populates two dictionaries from the contents of these files:

filters

Each filter defined in this dictionary specifies the name of a field in an X.509 certificate, and the conditions under which the contents of that field are to be considered a match.

tags

Each tag is a list of one or more filters (defined in the filters dictionary) that all must be matched in order for the tag to be assigned to a new TLS session.

### Filter types
A filter's type determines the part of the incoming authentication material that the tlshd program examines to determine if there is a match. For example, for the x509.tbs.subject filter type, a string argument specifies a simple wildcard pattern that is matched against an incoming X.509 certificate's subject field. A complete list of filter types appears in the FILTER TYPE REFERENCE section below.

## FILTER TYPE REFERENCE
The tlshd program currently implements the following filter types:

x509.cert.signatureAlgorithm

Filters of this type examine an incoming X.509 certificate's signatureAlgorithm field, as defined in RFC 5280, Section 4.1.1.2. The filter takes an additional string wildcard pattern that can be an algorithm name or an algorithm OID.

x509.tbs.version

Filters of this type examine an incoming X.509 certificate's version field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.1. The filter takes an additional numeric value that is matched against the certificate's version.

x509.tbs.serialNumber

Filters of this type examine an incoming X.509 certificate's serialNumber field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.2. The filter takes an additional string wildcard pattern that matches a hexadecimal number.

x509.tbs.issuer

Filters of this type examine an incoming X.509 certificate's issuer field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.4. The filter takes an additional string wildcard pattern that matches the distinguished name part of the certificate's issuer field.

x509.tbs.validity.notBefore

Filters of this type examine an incoming X.509 certificate's activation time field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.5. The filter takes a date and time string. The filter matches when the certificate's activation time is equal to or later than the specified threshold. Use this filter to accept only certificates issued on or after a particular date.

x509.tbs.validity.notAfter

Filters of this type examine an incoming X.509 certificate's expiration time field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.5. The filter takes a date and time string. The filter matches when the certificate's expiration time is equal to or earlier than the specified threshold. Use this filter to accept only certificates that expire on or before a particular date.

x509.tbs.subject

Filters of this type examine an incoming X.509 certificate's subject field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.6. The filter takes an additional string wildcard pattern that matches the distinguished name part of the certificate's subject field.

x509.extension.keyUsage

Filters of this type examine an incoming X.509 certificate's keyUsage field, one of the standard certificate extensions. The filter takes a list of bit names that must be set in the field in order for the filter to match. This list contains zero or more of the following bit names: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, or decipherOnly.

x509.extension.extendedKeyUsage

Filters of this type examine an incoming X.509 certificate's extendedKeyUsage field, one of the standard certificate extensions. This filter type is not yet implemented.

x509.derived.fingerprint

Filters of this type locally compute an incoming X.509 certificate's SHA1 and SHA256 fingerprint. The filter takes an additional string wildcard pattern that matches the hexadecimal value of either the derived SHA1 or derived SHA256 fingerprint.

x509.derived.selfSigned

Filters of this type match when an incoming X.509 certificate's issuer and subject distinguished names are exactly equal.

### Filters
The definition of each filter is YAML mapping that specifies the unique name of the filter, its filter type, and zero or more specific match arguments to be used. For example:

```
filters:

  ...

  monsters-university:

    type: "x509.tbs.issuer"

    pattern: "*,O=Monsters University,*"

  ...
```

This example defines a filter named "monsters-university". The filter performs a wildcard match for "O=Monsters University" in the issuer field of each incoming X.509 certificate.

### Tags
The definition of each tag is a YAML mapping that specifies the unique name of the tag and a list of filters, as defined in the Filters mapping, that all must match for the tag to be assigned to a TLS session.

A filter name can be prefixed with "not " to invert its matching behavior. When a filter is negated, the tag matches only if that filter does not match. A tag matches when all non-negated filters match and all negated filters do not match.

For example:

```
tags:

  ...

  ror-mu-chapter:

    filter:

      - monsters-university

      - not fear-tech

      - fraternity-ror

  ...
```

This example defines a tag named "ror-mu-chapter". The peer's certificate must satisfy both the "monsters-university" and "fraternity-ror" filter conditions, and must fail to satisfy the "fear-tech" filter condition, in order for the tlshd program to assign the ror-mu-chapter tag to an incoming TLS session.

### Handshake completion
Once a TLS handshake is successful, the tlshd program scans the peer's certificate using the configured filter and tag definitions. For each tag whose filter conditions the certificate satisfies, the tlshd program attaches that tag's name to the new TLS session. The kernel consumer receives only the list of matching tag names; the session's authentication material, filter types, and filter names remain private to the tlshd program.

## STANDARDS
X.509

RFC 5280, RFC 6125

## SEE ALSO
tlshd(8), tlshd.conf(5)

## AUTHOR
Chuck Lever


hci

package: libbluez-devel

title: hci(7)

summary: Bluetooth HCI protocol

text:
# hci(7)

## Name
hci - Bluetooth HCI protocol

## SYNOPSIS

```
#include <sys/socket.h>
#include <bluetooth/bluetooth.h>
#include <bluetooth/hci.h>
hci_socket = socket(PF_BLUETOOTH, SOCK_RAW, BTPROTO_HCI);
```

## DESCRIPTION
Bluetooth Host Controller Interface (HCI) is the standard protocol to communicate with Bluetooth adapters. HCI protocol provides a uniform command method for the Host to access Controller capabilities and to control connections to other Controllers.

## SOCKET ADDRESS

```
struct sockaddr_hci {

    sa_family_t    hci_family;

    unsigned short hci_dev;

    unsigned short hci_channel;
};
```

Possible values for hci_channel:

Define

Value

Description

HCI_CHANNEL_RAW

0x00

Raw channel - Used for raw HCI communication

HCI_CHANNEL_USER

0x01

User channel - Used for userspace HCI communication (disables kernel processing)

HCI_CHANNEL_MONITOR

0x02

Monitor channel - Used for monitoring HCI traffic (btmon(1))

HCI_CHANNEL_CONTROL

0x03

Control channel - Used to manage local adapters (bluetoothd(7))

HCI_CHANNEL_LOGGING

0x04

Logging channel - Used to inject logging messages (bluetoothd(7))

Example:

```
struct sockaddr_hci addr;
memset(&addr, 0, sizeof(addr));
addr.hci_family = AF_BLUETOOTH;
addr.hci_dev = HCI_DEV_NONE;
addr.hci_channel = HCI_CHANNEL_CONTROL;
```

## SOCKET OPTIONS
The socket options listed below can be set by using setsockopt(2) and read with getsockopt(2) with the socket level set to SOL_BLUETOOTH or SOL_HCI (HCI_FILTER).

### HCI_FILTER (since Linux 2.6)
Filter by HCI events, requires hci_channel to be set to HCI_CHANNEL_RAW, possible values:

```
struct hci_filter {

    uint32_t type_mask;

    uint32_t event_mask[2];

    uint16_t opcode;
};
```

Example:

```
struct hci_filter flt;
memset(&flt, 0, sizeof(flt));
flt.type_mask = 1 << BT_H4_EVT_PKT;
flt.event_mask[0] = 0xffffffff;
flt.event_mask[1] = 0xffffffff;
setsockopt(fd, SOL_HCI, HCI_FILTER, &flt, sizeof(flt));
```

### BT_SNDBUF (since Linux 5.16)
Set send buffer size, requires hci_channel to be set to HCI_CHANNEL_MONITOR, HCI_CHANNEL_CONTROL or HCI_CHANNEL_LOGGING.

Default value is 1028.

Example:

```
uint16_t mtu = UINT16_MAX;
int err;
err = setsockopt(fd, SOL_BLUETOOTH, BT_SNDMTU, &mtu, sizeof(mtu));
```

### BT_RCVBUF (since Linux 5.16)
Set receive buffer size, requires hci_channel to be set to HCI_CHANNEL_MONITOR, HCI_CHANNEL_CONTROL or HCI_CHANNEL_LOGGING.

Default value is 1028.

Example:

```
uint16_t mtu;
socklen_t len;
int err;
len = sizeof(mtu);
err = getsockopt(sock, SOL_BLUETOOTH, BT_RCVMTU, mtu, &len);
```

## RESOURCES
<http://www.bluez.org>

## REPORTING BUGS
<linux-bluetooth@vger.kernel.org>

## SEE ALSO
socket(7)

## Copyright
Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).

branch: sisyphus


iso

title: iso(7)

summary: ISO transport

text:
# iso(7)

## Name
iso - ISO transport

## SYNOPSIS (since Linux 6.0 [experimental])

```
#include <sys/socket.h>
#include <bluetooth/bluetooth.h>
#include <bluetooth/iso.h>
iso_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
```

## DESCRIPTION
Bluetooth Isochronous Channels is a feature introduced in Bluetooth 5.2 that allow for the transmission of multiple, synchronized audio streams between devices.

For unicast/multi-stream audio, connected isochronous group (CIG), and connected isochronous stream (CIS) are used. A CIG is created by the central and it can include one or more CISs. A CIS is a point-to-point data transportation stream between a central and a certain peripheral, and is a bidirectional communication protocol with acknowledgment.

For broadcast audio, broadcast isochronous group (BIG) and broadcast isochronous stream (BIS) are used. There are two types of devices: isochronous broadcaster and synchronized receiver. A BIG is created by an isochronous broadcaster, and it can include one or more BISs. A BIS is a one-to-many data transportation stream.

## SOCKET ADDRESS

```
struct sockaddr_iso_bc {

    bdaddr_t        bc_bdaddr;

    uint8_t         bc_bdaddr_type;

    uint8_t         bc_sid;

    uint8_t         bc_num_bis;

    uint8_t         bc_bis[ISO_MAX_NUM_BIS];
};
struct sockaddr_iso {

    sa_family_t     iso_family;

    bdaddr_t        iso_bdaddr;

    uint8_t         iso_bdaddr_type;

    struct sockaddr_iso_bc iso_bc[];
};
```

Unicast example:

```
struct sockaddr_iso addr;
memset(&addr, 0, sizeof(addr));
addr.iso_family = AF_BLUETOOTH;
bacpy(&addr.iso_bdaddr, bdaddr);
addr.iso_bdaddr_type = BDADDR_LE_PUBLIC;
```

Broadcast example:

```
struct sockaddr_iso *addr;
size_t addr_len;
addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
memset(addr, 0, addr_len);
addr->iso_family = AF_BLUETOOTH;
bacpy(&addr->iso_bdaddr, bdaddr);
addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
```

Broadcast Source (Broadcaster) example:

```
struct sockaddr_iso *addr;
size_t addr_len;
addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
memset(addr, 0, addr_len);
addr->iso_family = AF_BLUETOOTH;
/* Set address to BDADR_ANY(00:00:00:00:00:00) */
bacpy(&addr->iso_bdaddr, BADDR_ANY);
addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
/* Connect to Broadcast address */
connect(iso_socket, (struct sockaddr *)addr, addr_len);
```

Broadcast Sink (Receiver) example:

```
struct sockaddr_iso *addr;
size_t addr_len;
addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
memset(addr, 0, addr_len);
addr->iso_family = AF_BLUETOOTH;
/* Set destination to Broadcaster address */
bacpy(&addr->iso_bdaddr, bdaddr);
addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
/* Bind to Broadcaster address */
bind(iso_socket, (struct sockaddr *)addr, addr_len);
```

Broadcast Source (Broadcaster) or Broadcast Sink (Receiver) Periodic Advertising Sync Transfer (PAST):

```
struct sockaddr_iso *addr;
size_t addr_len;
addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
memset(addr, 0, addr_len);
addr->iso_family = AF_BLUETOOTH;
/* Set destination address to PAST destination address */
bacpy(&addr->iso_bc->bc_bdaddr, (void *) bdaddr);
addr->iso_bc->bc_bdaddr_type = bdaddr_type;
/* Rebind already connected socket to PAST address */
bind(iso_socket, (struct sockaddr *)addr, addr_len);
```

## SOCKET OPTIONS (SOL_BLUETOOTH)
The socket options listed below can be set by using setsockopt(2) and read with getsockopt(2) with the socket level set to SOL_BLUETOOTH.

### BT_SECURITY
Channel security level, possible values:

Value

Security Level

Link Key Type

Encryption

BT_SECURITY_SDP

0 (SDP Only)

None

Not required

BT_SECURITY_LOW

1 (Low)

Unauthenticated

Not required

BT_SECURITY_MEDIUM

2 (Medium - default)

Unauthenticated

Desired

BT_SECURITY_HIGH

3 (High)

Authenticated

Required

BT_SECURITY_FIPS (since Linux 3.15)

4 (Secure Only)

Authenticated (P-256 based Secure Simple Pairing and Secure Authentication)

Required

Example:

```
int level = BT_SECURITY_HIGH;
int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_SECURITY, &level,

                     sizeof(level));
if (err == -1) {

    perror("setsockopt");

    return 1;
}
```

### BT_DEFER_SETUP
Channel defer connection setup, this control if the connection procedure needs to be authorized by userspace before responding which allows authorization at profile level, possible values:

Value

Description

Authorization

0

Disable (default)

Not required

1

Enable

Required

Example:

```
int defer_setup = 1;
int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,

                     &defer_setup, sizeof(defer_setup));
if (err == -1) {

    perror("setsockopt");

    return err;
}
err = listen(iso_socket, 5);
if (err) {

    perror("listen");

    return err;
}
struct sockaddr_iso remote_addr = {0};
socklen_t addr_len = sizeof(remote_addr);
int new_socket = accept(iso_socket, (struct sockaddr*)&remote_addr,

                        &addr_len);
if (new_socket < 0) {

    perror("accept");

    return new_socket;
}
/* To complete the connection setup of new_socket read 1 byte */
char c;
struct pollfd pfd;
memset(&pfd, 0, sizeof(pfd));
pfd.fd = new_socket;
pfd.events = POLLOUT;
err = poll(&pfd, 1, 0);
if (err) {

    perror("poll");

    return err;
}
if (!(pfd.revents & POLLOUT)) {

    err = read(sk, &c, 1);

    if (err < 0) {

        perror("read");

        return err;

    }
}
```

### BT_PKT_STATUS
Enable reporting packet status via BT_SCM_PKT_STATUS CMSG on received packets. Possible values:

Value

Description

0

Disable (default)

1

Enable

BT_SCM_PKT_STATUS

Level SOL_BLUETOOTH CMSG with data:

```
uint8_t pkt_status;
```

The values are equal to the "Packet_Status_Flag" defined in Core Specification v6.1, 5.4.5. HCI ISO Data packets:

<https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-61/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-9b5fb085-278b-5084-ac33-bee2839abe6b>

pkt_status

Description

0x0

Valid data. The complete SDU was received correctly.

0x1

Possibly invalid data. The contents of the ISO_SDU_Fragment, may contain errors or part of the SDU may be missing. This is reported as 'data with possible errors'.

0x2

Part(s) of the SDU were not received correctly. This is reported as 'lost data'.

### BT_PKT_SEQNUM (since Linux 6.17-rc1)
Enable reporting packet ISO sequence number via BT_SCM_PKT_SEQNUM CMSG on received packets. Possible values:

Value

Description

0

Disable (default)

1

Enable

BT_SCM_PKT_SEQNUM

Level SOL_BLUETOOTH CMSG with data:

```
uint16_t pkt_seqnum;
```

The values are equal to the "Packet_Sequence_Number" defined in Core Specification v6.1, 5.4.5. HCI ISO Data packets:

<https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-61/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-9b5fb085-278b-5084-ac33-bee2839abe6b>

Example (Enable sequence numbers):

```
uint32_t opt = 1;
if (setsockopt(fd, SOL_BLUETOOTH, BT_PKT_SEQNUM, &opt, sizeof(opt)) < 0)

    goto error;
```

Example (Read packet and its sequence number):

```
char data_buf[256];
uint16_t seqnum;
union {

    char buf[CMSG_SPACE(sizeof(uint16_t))];

    struct cmsghdr align;
} control;
struct iovec data = {

    .iov_base = data_buf,

    .iov_len = sizeof(data_buf),
};
struct msghdr msg = {

    .msg_iov = &data,

    .msg_iovlen = 1,

    .msg_control = control.buf,

    .msg_controllen = sizeof(control.buf),
};
struct scm_timestamping tss;
res = recvmsg(fd, &msg, 0);
if (res < 0)

    goto error;
for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {

    if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_PKT_SEQNUM)

        memcpy(&seqnum, CMSG_DATA(cmsg), sizeof(seqnum));
}
```

## SOCKET OPTIONS (SOL_SOCKET)
SOL_SOCKET level socket options that modify generic socket features (SO_SNDBUF, SO_RCVBUF, etc.) have their usual meaning, see socket(7).

The SOL_SOCKET level ISO socket options that have Bluetooth-specific handling in kernel are listed below.

### SO_TIMESTAMPING, SO_TIMESTAMP, SO_TIMESTAMPNS
See <https://docs.kernel.org/networking/timestamping.html>

For ISO sockets, software RX timestamps are supported. Software TX timestamps (SOF_TIMESTAMPING_TX_SOFTWARE) are supported since Linux 6.15.

The software RX timestamp is the time when the kernel received the packet from the controller driver.

The SCM_TSTAMP_SND timestamp is emitted when packet is sent to the controller driver.

The SCM_TSTAMP_COMPLETION timestamp is emitted when controller reports the packet completed. Completion timestamps are only supported on controllers that have ISO flow control. Other TX timestamp types are not supported.

You can use SIOCETHTOOL to query supported flags.

The timestamps are in CLOCK_REALTIME time.

Example (Enable RX timestamping):

```
int flags = SOF_TIMESTAMPING_SOFTWARE |

    SOF_TIMESTAMPING_RX_SOFTWARE;
setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
```

Example (Read packet and its RX timestamp):

```
char data_buf[256];
union {

    char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];

    struct cmsghdr align;
} control;
struct iovec data = {

    .iov_base = data_buf,

    .iov_len = sizeof(data_buf),
};
struct msghdr msg = {

    .msg_iov = &data,

    .msg_iovlen = 1,

    .msg_control = control.buf,

    .msg_controllen = sizeof(control.buf),
};
struct scm_timestamping tss;
res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
if (res < 0)

    goto error;
for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {

    if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)

        memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
}
tstamp_clock_realtime = tss.ts[0];
```

Example (Enable TX timestamping):

```
int flags = SOF_TIMESTAMPING_SOFTWARE |

    SOF_TIMESTAMPING_TX_SOFTWARE |

    SOF_TIMESTAMPING_OPT_ID;
setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
```

Example (Read TX timestamps):

```
union {

    char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];

    struct cmsghdr align;
} control;
struct iovec data = {

    .iov_base = NULL,

    .iov_len = 0
};
struct msghdr msg = {

    .msg_iov = &data,

    .msg_iovlen = 1,

    .msg_control = control.buf,

    .msg_controllen = sizeof(control.buf),
};
struct cmsghdr *cmsg;
struct scm_timestamping tss;
struct sock_extended_err serr;
int res;
res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
if (res < 0)

    goto error;
for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {

    if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)

        memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));

    else if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_SCM_ERROR)

        memcpy(&serr, CMSG_DATA(cmsg), sizeof(serr));
}
tstamp_clock_realtime = tss.ts[0];
tstamp_type = serr->ee_info;      /* SCM_TSTAMP_SND or SCM_TSTAMP_COMPLETION */
tstamp_seqnum = serr->ee_data;
```

## IOCTLS
The following ioctls with operation specific for ISO sockets are available.

### SIOCETHTOOL (since Linux 6.16-rc1)
Supports only command ETHTOOL_GET_TS_INFO, which may be used to query supported SOF_TIMESTAMPING_* flags. The SOF_TIMESTAMPING_OPT_* flags are always available as applicable.

Example:

```
#include <linux/ethtool.h>
#include <linux/sockios.h>
#include <net/if.h>
#include <sys/socket.h>
#include <sys/ioctl.h>
...
struct ifreq ifr = {};
struct ethtool_ts_info cmd = {};
int sk;
snprintf(ifr.ifr_name, sizeof(ifr.ifr_name), "hci0");
ifr.ifr_data = (void *)&cmd;
cmd.cmd = ETHTOOL_GET_TS_INFO;
sk = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
if (sk < 0)

    goto error;
if (ioctl(sk, SIOCETHTOOL, &ifr))

    goto error;
sof_available = cmd.so_timestamping;
```

## RESOURCES
<http://www.bluez.org>

## REPORTING BUGS
<linux-bluetooth@vger.kernel.org>

## SEE ALSO
socket(7), isotest(1)

## Copyright
Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).


title: l2cap(7)

summary: L2CAP protocol

text:
# l2cap(7)

## Name
l2cap - L2CAP protocol

## SYNOPSIS

```
#include <sys/socket.h>
#include <bluetooth/bluetooth.h>
#include <bluetooth/l2cap.h>
l2cap_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_L2CAP);
```

## DESCRIPTION
L2CAP is a protocol that provides an interface for higher-level protocols to send and receive data over a Bluetooth connection. L2CAP sits on top of the Bluetooth Host Controller Interface (HCI) and provides a set of channels that can be used by higher-level protocols to transmit data.

L2CAP provides a number of services to higher-level protocols, including segmentation and reassembly of large data packets and flow control to prevent overloading of the receiver. L2CAP also supports multiple channels per connection, allowing for concurrent data transmission using different protocols.

## SOCKET ADDRESS

```
struct sockaddr_l2 {

    sa_family_t     l2_family;

    unsigned short  l2_psm;

    bdaddr_t        l2_bdaddr;

    unsigned short  l2_cid;

    uint8_t         l2_bdaddr_type;
};
```

Example:

```
struct sockaddr_l2 addr;
memset(&addr, 0, sizeof(addr));
addr.l2_family = AF_BLUETOOTH;
bacpy(&addr.l2_bdaddr, bdaddr);
if (cid)

    addr.l2_cid = htobs(cid);
else

    addr.l2_psm = htobs(psm);
addr.l2_bdaddr_type = bdaddr_type;
```

## SOCKET OPTIONS (SOL_BLUETOOTH)
The socket options listed below can be set by using setsockopt(2) and read with getsockopt(2) with the socket level set to SOL_BLUETOOTH.

### BT_SECURITY (since Linux 2.6.30)
Channel security level, possible values:

Value

Security Level

Link Key Type

Encryption

BT_SECURITY_SDP

0 (SDP Only)

None

Not required

BT_SECURITY_LOW

1 (Low)

Unauthenticated

Not required

BT_SECURITY_MEDIUM

2 (Medium - default)

Unauthenticated

Desired

BT_SECURITY_HIGH

3 (High)

Authenticated

Required

BT_SECURITY_FIPS (since Linux 3.15)

4 (Secure Only)

Authenticated (P-256 based Secure Simple Pairing and Secure Authentication)

Required

Example:

```
int level = BT_SECURITY_HIGH;
int err = setsockopt(l2cap_socket, SOL_BLUETOOTH, BT_SECURITY, &level,

                     sizeof(level));
if (err == -1) {

    perror("setsockopt");

    return 1;
}
```

### BT_DEFER_SETUP (since Linux 2.6.30)
Channel defer connection setup, this control if the connection procedure needs to be authorized by userspace before responding which allows authorization at profile level, possible values:

Value

Description

Authorization

0

Disable (default)

Not required

1

Enable

Required

Example:

```
int defer_setup = 1;
int err = setsockopt(l2cap_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,

                     &defer_setup, sizeof(defer_setup));
if (err == -1) {

    perror("setsockopt");

    return err;
}
err = listen(l2cap_socket, 5);
if (err) {

    perror("listen");

    return err;
}
struct sockaddr_l2 remote_addr = {0};
socklen_t addr_len = sizeof(remote_addr);
int new_socket = accept(l2cap_socket, (struct sockaddr*)&remote_addr,

                        &addr_len);
if (new_socket < 0) {

    perror("accept");

    return new_socket;
}
/* To complete the connection setup of new_socket read 1 byte */
char c;
struct pollfd pfd;
memset(&pfd, 0, sizeof(pfd));
pfd.fd = new_socket;
pfd.events = POLLOUT;
err = poll(&pfd, 1, 0);
if (err) {

    perror("poll");

    return err;
}
if (!(pfd.revents & POLLOUT)) {

    err = read(sk, &c, 1);

    if (err < 0) {

        perror("read");

        return err;

    }
}
```

### BT_FLUSHABLE (since Linux 2.6.39)
Channel flushable flag, this control if the channel data can be flushed or not, possible values:

Define

Value

Description

BT_FLUSHABLE_OFF

0x00 (default)

Do not flush data

BT_FLUSHABLE_ON

0x01

Flush data

### BT_POWER (since Linux 3.1)
Channel power policy, this control if the channel shall force exit of sniff mode or not, possible values:

Define

Value

Description

BT_POWER_FORCE_ACTIVE_OFF

0x00

Don't force exit of sniff mode

BT_POWER_FORCE_ACTIVE_ON

0x01 (default)

Force exit of sniff mode

### BT_CHANNEL_POLICY (since Linux 3.10)
High-speed (AMP) channel policy, possible values:

Define

Value

Description

BT_CHANNEL_POLICY_BREDR_ONLY

0 (default)

BR/EDR only

BT_CHANNEL_POLICY_BREDR_PREFERRED

1

BR/EDR Preferred

BT_CHANNEL_POLICY_BREDR_PREFERRED

2

AMP Preferred

### BT_PHY (since Linux 5.10)
Channel supported PHY(s), possible values:

Define

Value

Description

BT_PHY_BR_1M_1SLOT

BIT 0

BR 1Mbps 1SLOT

BT_PHY_BR_1M_3SLOT

BIT 1

BR 1Mbps 3SLOT

BT_PHY_BR_1M_5SLOT

BIT 2

BR 1Mbps 5SLOT

BT_PHY_BR_2M_1SLOT

BIT 3

EDR 2Mbps 1SLOT

BT_PHY_BR_2M_3SLOT

BIT 4

EDR 2Mbps 3SLOT

BT_PHY_BR_2M_5SLOT

BIT 5

EDR 2Mbps 5SLOT

BT_PHY_BR_3M_1SLOT

BIT 6

EDR 3Mbps 1SLOT

BT_PHY_BR_3M_3SLOT

BIT 7

EDR 3Mbps 3SLOT

BT_PHY_BR_3M_5SLOT

BIT 8

EDR 3Mbps 5SLOT

BT_PHY_LE_1M_TX

BIT 9

LE 1Mbps TX

BT_PHY_LE_1M_RX

BIT 10

LE 1Mbps RX

BT_PHY_LE_2M_TX

BIT 11

LE 2Mbps TX

BT_PHY_LE_2M_RX

BIT 12

LE 2Mbps RX

BT_PHY_LE_CODED_TX

BIT 13

LE Coded TX

BT_PHY_LE_CODED_RX

BIT 14

LE Coded RX

### BT_MODE (since Linux 5.10)
Channel Mode, possible values:

Define

Value

Description

Link

BT_MODE_BASIC

0x00 (default)

Basic mode

Any

BT_MODE_ERTM

0x01

Enhanced Retransmission mode

BR/EDR

BT_MODE_STREAM

0x02

Stream mode

BR/EDR

BT_MODE_LE_FLOWCTL

0x03

Credit based flow control mode

LE

BT_MODE_EXT_FLOWCTL

0x04

Extended Credit based flow control mode

Any

## SOCKET OPTIONS (SOL_SOCKET)
SOL_SOCKET level socket options that modify generic socket features (SO_SNDBUF, SO_RCVBUF, etc.) have their usual meaning, see socket(7).

The SOL_SOCKET level L2CAP socket options that have Bluetooth-specific handling in kernel are listed below.

### SO_TIMESTAMPING, SO_TIMESTAMP, SO_TIMESTAMPNS
See <https://docs.kernel.org/networking/timestamping.html>

For L2CAP sockets, software RX timestamps are supported. Software TX timestamps (SOF_TIMESTAMPING_TX_SOFTWARE, SOF_TIMESTAMPING_TX_COMPLETION) are supported since Linux 6.15.

The software RX timestamp is the time when the kernel received the packet from the controller driver.

The SCM_TSTAMP_SND timestamp is emitted when packet is sent to the controller driver. The SCM_TSTAMP_COMPLETION timestamp is emitted when controller reports the packet completed. Other TX timestamp types are not supported.

You can use SIOCETHTOOL to query supported flags.

The timestamps are in CLOCK_REALTIME time.

Example (Enable RX timestamping):

```
int flags = SOF_TIMESTAMPING_SOFTWARE |

    SOF_TIMESTAMPING_RX_SOFTWARE;
setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
```

Example (Read packet and its RX timestamp):

```
char data_buf[256];
union {

    char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];

    struct cmsghdr align;
} control;
struct iovec data = {

    .iov_base = data_buf,

    .iov_len = sizeof(data_buf),
};
struct msghdr msg = {

    .msg_iov = &data,

    .msg_iovlen = 1,

    .msg_control = control.buf,

    .msg_controllen = sizeof(control.buf),
};
struct scm_timestamping tss;
res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
if (res < 0)

    goto error;
for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {

    if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)

        memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
}
tstamp_clock_realtime = tss.ts[0];
```

Example (Enable TX timestamping):

```
int flags = SOF_TIMESTAMPING_SOFTWARE |

    SOF_TIMESTAMPING_TX_SOFTWARE |

    SOF_TIMESTAMPING_TX_COMPLETION |

    SOF_TIMESTAMPING_OPT_ID;
setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
```

Example (Read TX timestamps):

```
union {

    char buf[2 * CMSG_SPACE(sizeof(struct scm_timestamping))];

    struct cmsghdr align;
} control;
struct iovec data = {

    .iov_base = NULL,

    .iov_len = 0
};
struct msghdr msg = {

    .msg_iov = &data,

    .msg_iovlen = 1,

    .msg_control = control.buf,

    .msg_controllen = sizeof(control.buf),
};
struct cmsghdr *cmsg;
struct scm_timestamping tss;
struct sock_extended_err serr;
int res;
res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
if (res < 0)

    goto error;
for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {

    if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)

        memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));

    else if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_SCM_ERROR)

        memcpy(&serr, CMSG_DATA(cmsg), sizeof(serr));
}
tstamp_clock_realtime = tss.ts[0];
tstamp_type = serr->ee_info;      /* SCM_TSTAMP_SND or SCM_TSTAMP_COMPLETION */
tstamp_seqnum = serr->ee_data;
```

## IOCTLS
The following ioctls with operation specific for L2CAP sockets are available.

### SIOCETHTOOL (since Linux 6.16-rc1)
Supports only command ETHTOOL_GET_TS_INFO, which may be used to query supported SOF_TIMESTAMPING_* flags. The SOF_TIMESTAMPING_OPT_* flags are always available as applicable.

Example:

```
#include <linux/ethtool.h>
#include <linux/sockios.h>
#include <net/if.h>
#include <sys/socket.h>
#include <sys/ioctl.h>
...
struct ifreq ifr = {};
struct ethtool_ts_info cmd = {};
int sk;
snprintf(ifr.ifr_name, sizeof(ifr.ifr_name), "hci0");
ifr.ifr_data = (void *)&cmd;
cmd.cmd = ETHTOOL_GET_TS_INFO;
sk = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_L2CAP);
if (sk < 0)

    goto error;
if (ioctl(sk, SIOCETHTOOL, &ifr))

    goto error;
sof_available = cmd.so_timestamping;
```

## RESOURCES
<http://www.bluez.org>

## REPORTING BUGS
<linux-bluetooth@vger.kernel.org>

## SEE ALSO
socket(7), l2test(1)

## Copyright
Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).