usr.sbin/bluetooth/hcsecd/hcsecd.8

   1 .\" Copyright (c) 2001-2002 Maksim Yevmenkin <m_evmenkin@yahoo.com>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $Id: hcsecd.8,v 1.8 2003/09/08 18:54:20 max Exp $
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd November 16, 2002
  29 .Dt HCSECD 8
  30 .Os
  31 .Sh NAME
  32 .Nm hcsecd
  33 .Nd control link keys and PIN codes for Bluetooth devices
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl dh
  37 .Fl f Ar configfile
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 daemon controls link keys and PIN codes for Bluetooth devices.
  42 It opens a raw HCI socket and listens for
  43 .Dv Link_Key_Request ,
  44 .Dv PIN_Code_Request
  45 and
  46 .Dv Link_Key_Notification
  47 HCI events.
  48 .Pp
  49 Once a
  50 .Dv Link_Key_Request
  51 or
  52 .Dv PIN_Code_Request
  53 HCI event is received, the daemon scans the configuration file for a
  54 matching entry.
  55 The remote device BD_ADDR is used as a key.
  56 If no matching entry was found, the default entry will be used.
  57 If no default entry was found then it is assumed that no link key and no
  58 PIN code exists.
  59 For any given entry, the link key takes precedence over the PIN code.
  60 If a link key was not specified, the device must generate the link key from
  61 the PIN code.
  62 If an entry was found and the link key (or PIN code) exists, the
  63 .Dv Link_Key_Request_Reply
  64 (or
  65 .Dv PIN_Code_Request_Reply )
  66 command will be sent back to the device.
  67 Otherwise, the
  68 .Dv Link_Key_Request_Negative_Reply
  69 (or
  70 .Dv PIN_Code_Request_Negative_Reply )
  71 command will be sent back to the device.
  72 .Pp
  73 The
  74 .Nm
  75 daemon also handles HCI
  76 .Dv Link_Key_Notification
  77 events and caches link keys created from the PIN codes in memory.
  78 To preserve link keys between restarts the
  79 .Nm
  80 daemon dumps link keys for all entries in the
  81 .Pa /var/db/hcsecd.keys
  82 link keys file.
  83 If it exists, the link keys file gets processed by the
  84 .Nm
  85 daemon after it processes its main configuration file.
  86 The link keys file gets written every time the
  87 .Nm
  88 daemon shuts down gracefully.
  89 It is possible to force the
  90 .Nm
  91 daemon to re-read its main configuration file and dump the link keys file by
  92 sending the
  93 .Dv HUP
  94 signal to the
  95 .Nm
  96 process.
  97 The user is expected to not modify the link keys file by hand.
  98 .Pp
  99 The command line options are as follows:
 100 .Bl -tag -width indent
 101 .It Fl d
 102 Do not detach from the controlling terminal.
 103 .It Fl f Ar configfile
 104 Specify the name of the configuration file.
 105 The default is
 106 .Pa /etc/bluetooth/hcsecd.conf .
 107 .It Fl h
 108 Display usage message and exit.
 109 .El
 110 .Sh FILES
 111 .Bl -tag -width ".Pa /etc/bluetooth/hcsecd.conf" -compact
 112 .It Pa /etc/bluetooth/hcsecd.conf
 113 .It Pa /var/db/hcsecd.keys
 114 .It Pa /var/run/hcsecd.pid
 115 .El
 116 .Sh SEE ALSO
 117 .Xr ng_btsocket 4 ,
 118 .Xr ng_hci 4 ,
 119 .Xr hcsecd.conf 5 ,
 120 .Xr hccontrol 8 ,
 121 .Xr hcseriald 8
 122 .Sh AUTHORS
 123 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 124 .Sh BUGS
 125 Currently there is no way to select the link key or the PIN code based on
 126 which local device received the request.
 127 Everything is based on the remote device BD_ADDR.
 128 An interface for external helpers to obtain link keys and PIN codes is missing.