usr.sbin/bthcid/bthcid.8

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