usr.sbin/bthcid/bthcid.8

   1 .\" $NetBSD: bthcid.8,v 1.6 2007/11/09 21:18:24 plunky 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.7 2009/05/18 12:03:56 wiz 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 handles Link Key and PIN code requests 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 Some of the functionality of
 120 .Nm
 121 can be handled by the Bluetooth controller directly, and cached Link
 122 Keys may be examined, deleted or moved to device storage using the
 123 .Xr btkey 1
 124 program.
 125 .Pp
 126 The command line options are as follows:
 127 .Bl -tag -width XXXX
 128 .It Fl d Ar device
 129 Specify the local Bluetooth device address.
 130 The default is BDADDR_ANY.
 131 .It Fl f
 132 Run in foreground (do not detach).
 133 .It Fl h
 134 Display usage message and exit.
 135 .It Fl m
 136 Specify the file mode access bits for the PIN client socket.
 137 The default is to allow readwrite access to user and group (0660).
 138 .It Fl n
 139 Do not listen for PIN clients.
 140 .It Fl s Ar socket_name
 141 Specify the socket name to listen on for PIN clients.
 142 The default path is
 143 .Pa /var/run/bthcid .
 144 .El
 145 .Sh FILES
 146 .Bl -tag -compact
 147 .It Pa /var/db/bthcid.keys
 148 .It Pa /var/run/bthcid
 149 .It Pa /var/run/bthcid.pid
 150 .El
 151 .Sh SEE ALSO
 152 .Xr btkey 1 ,
 153 .Xr btpin 1 ,
 154 .Xr bluetooth 4 ,
 155 .Xr btconfig 8
 156 .Sh HISTORY
 157 The
 158 .Nm
 159 daemon first appeared in
 160 .Fx 5.3
 161 as
 162 .Ic hcsecd .
 163 It was ported to
 164 .Nx 4.0
 165 with its present name and extended to support PIN clients by
 166 .An Iain Hibbert
 167 under the sponsorship of Itronix, Inc.
 168 .Sh AUTHORS
 169 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 170 .An Iain Hibbert