usr.sbin/bthcid/bthcid.8

   1 .\" $NetBSD: bthcid.8,v 1.5 2006/10/03 02:04:42 wiz 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.1.1 2007/11/20 11:56:11 griffin Exp $
  56 .\" $FreeBSD: src/usr.sbin/bluetooth/hcsecd/hcsecd.8,v 1.6 2006/02/11 15:36:37 markus Exp $
  57 .\"
  58 .Dd September 29, 2006
  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 d Ar device
  68 .Op Fl m Ar mode
  69 .Op Fl s Ar socket_name
  70 .Nm
  71 .Op Fl h
  72 .Sh DESCRIPTION
  73 The
  74 .Nm
  75 daemon manages link keys and PIN codes for Bluetooth devices.
  76 It opens a raw HCI socket and listens for the following HCI events.
  77 .Pp
  78 .Bl -tag -width XXXX -compact
  79 .It Dv Link_Key_Request
  80 .Nm
  81 scans the
  82 .Pa /var/db/bthcid.keys
  83 file for a cached link key matching the remote device BD_ADDR and, if
  84 found, the
  85 .Dv Link_Key_Request_Reply
  86 will be sent back to the device, otherwise the
  87 .Dv Link_Key_Request_Negative_Reply
  88 will be sent.
  89 .Pp
  90 .It Dv Link_Key_Notification
  91 When a new link key is created by the device, it will be cached for future
  92 use in the
  93 .Pa /var/db/bthcid.keys
  94 link keys file, which will be created if it does not already exist.
  95 .Pp
  96 .It Dv PIN_Code_Request
  97 The
  98 .Nm
  99 daemon checks its PIN cache for a matching remote device entry.
 100 If no PIN is found, the
 101 .Nm
 102 daemon will send a message to any PIN clients that have
 103 registered, with the device details and a timeout value.
 104 When no clients are available or the timeout has expired,
 105 .Nm
 106 will send a
 107 .Dv PIN_Code_Request_Negative_Reply
 108 back to the device.
 109 When a PIN is found, or if a client responds within the timeout period, a
 110 .Dv PIN_Code_Request_Reply
 111 will be sent back to the device.
 112 .Pp
 113 PINs received from clients will be cached for 5 minutes until used, and may be added
 114 to the cache prior to pairing with the
 115 .Xr btpin 1
 116 utility.
 117 .El
 118 .Pp
 119 The command line options are as follows:
 120 .Bl -tag -width XXXX
 121 .It Fl d Ar device
 122 Specify the local Bluetooth device address.
 123 The default is BDADDR_ANY.
 124 .It Fl f
 125 Run in foreground (do not detach).
 126 .It Fl h
 127 Display usage message and exit.
 128 .It Fl m
 129 Specify the file mode access bits for the PIN client socket.
 130 The default is to allow readwrite access to user and group (0660).
 131 .It Fl n
 132 Do not listen for PIN clients.
 133 .It Fl s Ar socket_name
 134 Specify the socket name to listen on for PIN clients.
 135 The default path is
 136 .Pa /var/run/bthcid .
 137 .El
 138 .Sh FILES
 139 .Bl -tag -compact -width ".Pa /var/run/bthcid.pid"
 140 .It Pa /var/db/bthcid.keys
 141 .It Pa /var/run/bthcid
 142 .It Pa /var/run/bthcid.pid
 143 .El
 144 .Sh SEE ALSO
 145 .Xr btpin 1 ,
 146 .Xr bluetooth 4 ,
 147 .Xr btconfig 8
 148 .Sh HISTORY
 149 The
 150 .Nm
 151 daemon first appeared in
 152 .Fx 5.3
 153 as
 154 .Ic hcsecd .
 155 It was ported to
 156 .Nx 4.0
 157 with its present name and extended to support PIN clients by
 158 .An Iain Hibbert
 159 under the sponsorship of Itronix, Inc.
 160 .Sh AUTHORS
 161 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 162 .An Iain Hibbert
 163 .Sh BUGS
 164 The only way to make the
 165 .Nm
 166 daemon forget a link key is to edit the
 167 .Pa /var/db/bthcid.keys
 168 file by hand.
 169 .Pp
 170 The only way to specify link keys (useful when multiple operating
 171 systems are used on the same hardware), is to edit the
 172 .Pa /var/db/bthcid.keys
 173 file by hand.