1.\" $NetBSD: bthcid.8,v 1.1 2006/06/19 15:44:56 gdamore Exp $ 2.\" 3.\" Copyright (c) 2006 Itronix Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of Itronix Inc. may not be used to endorse 15.\" or promote products derived from this software without specific 16.\" prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY 22.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 23.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 25.\" ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" 31.\" Copyright (c) 2001-2002 Maksim Yevmenkin <m_evmenkin@yahoo.com> 32.\" All rights reserved. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 43.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 44.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 45.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 46.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 47.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 48.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 49.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 51.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 52.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 53.\" SUCH DAMAGE. 54.\" 55.\" $Id: bthcid.8,v 1.1 2006/06/19 15:44:56 gdamore Exp $ 56.\" $FreeBSD: src/usr.sbin/bluetooth/hcsecd/hcsecd.8,v 1.6 2006/02/11 15:36:37 markus Exp $ 57.\" 58.Dd November 16, 2002 59.Dt BTHCID 8 60.Os 61.Sh NAME 62.Nm bthcid 63.Nd Bluetooth Link Key/PIN Code Manager 64.Sh SYNOPSIS 65.Nm 66.Op Fl fn 67.Op Fl c Ar config_file 68.Op Fl d Ar device 69.Op Fl m Ar mode 70.Op Fl s Ar socket_name 71.Nm 72.Op Fl h 73.Sh DESCRIPTION 74The 75.Nm 76daemon manages link keys and PIN codes for Bluetooth devices. 77It opens a raw HCI socket and listens for the following HCI events at the 78.Ar device 79address given, if any. 80.Pp 81.Bl -tag -width XXXX -compact 82.It Dv Link_Key_Request 83.Nm 84scans first the 85.Pa /var/db/bthcid.keys 86file for a cached link key matching the remote device BD_ADDR and, if 87none is found, further scans the configuration file. When a link key 88has been found, the 89.Dv Link_Key_Request_Reply 90will be sent back to the device, otherwise the 91.Dv Link_Key_Request_Negative_Reply 92will be sent. 93.Pp 94.It Dv Link_Key_Notification 95When a new link key is created by the device, it will be cached for future 96use in the 97.Pa /var/db/bthcid.keys 98link keys file, which will be created if it does not already exist. 99.Pp 100.It Dv PIN_Code_Request 101The 102.Nm 103daemon first checks its cached PINs, then the configuration file 104for a matching remote device entry. 105When no PIN is found, the 106.Nm 107daemon will send a message to any PIN clients that have 108registered, with the device details and a timeout value. 109When no clients are available or the timeout has expired, 110.Nm 111will send a 112.Dv PIN_Code_Request_Negative_Reply 113back to the device. 114When a PIN is found, or if a client responds within the timeout period, a 115.Dv PIN_Code_Request_Reply 116will be sent back to the device. 117.Pp 118PINs received from clients will be cached for 5 minutes, and may be added 119to the cache prior to pairing with the 120.Xr btpin 1 121utility. 122.El 123.Pp 124The command line options are as follows: 125.Bl -tag -width XXXX 126.It Fl c Ar config_file 127Specify the name of the configuration file. 128The default is 129.Pa /etc/bluetooth/bluetooth.conf . 130.It Fl d Ar device 131Specify the local Bluetooth device address. The default is BDADDR_ANY. 132.It Fl f 133Run in foreground (do not detach). 134.It Fl h 135Display usage message and exit. 136.It Fl m 137Specify the file mode access bits for the PIN client socket. The 138default is to allow readwrite access to user and group (0660). 139.It Fl n 140Do not listen for PIN clients. 141.It Fl s Ar socket_name 142Specify the socket name to listen on for PIN clients. The default path is 143.Pa /var/run/bthcid . 144.El 145.Sh FILES 146.Bl -tag -compact 147.It Pa /etc/bluetooth/bluetooth.conf 148.It Pa /var/db/bthcid.keys 149.It Pa /var/run/bthcid 150.It Pa /var/run/bthcid.pid 151.El 152.Sh SEE ALSO 153.Xr bluetooth 4 , 154.Xr bluetooth.conf 5 , 155.Xr btconfig 8 , 156.Xr btpin 1 157.Sh AUTHORS 158.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com , 159.An Iain Hibbert 160.Sh HISTORY 161The 162.Nm 163daemon first appeared in 164.Fx 5.3 165as 166.Ic hcsecd . 167It was ported to 168.Nx 4.0 169with its present name and extended to support PIN clients by 170.An Iain Hibbert 171under the sponsorship of 172.An Itronix, Inc. 173.Sh BUGS 174Currently there is no way to select the link key based on 175which local device received the request. 176.Pp 177Everything is based on the remote device BD_ADDR. 178.Pp 179Currently the only way to make the 180.Nm 181daemon forget a link key is to edit the 182.Pa /var/db/bthcid.keys 183file by hand. 184