NetBSD/usr.bin/btkey/btkey.1

.\"	$NetBSD: btkey.1,v 1.4 2009/05/18 12:03:06 wiz Exp $
.\"
.\" Copyright (c) 2007 Iain Hibbert
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd November 8, 2007
.Dt BTKEY 1
.Os
.Sh NAME
.Nm btkey
.Nd Bluetooth Link Key management utility
.Sh SYNOPSIS
.Nm
.Op Fl CcRrWw
.Op Fl k Ar key
.Fl a Ar address
.Fl d Ar device
.Nm
.Fl Ll
.Op Fl d Ar device
.Sh DESCRIPTION
The
.Nm
program is used to manage Bluetooth Link Key storage.
Keys are normally handled by the
.Xr bthcid 8
daemon which caches them in the
.Pa /var/db/bthcid.keys
file and provides them as required when Bluetooth connections
need to be authenticated.
.Pp
These keys are required for connections between remote
devices and the specific controller
.Pq not the Operating System
and so for multi-boot systems where it may not always be possible to
specify the same key across all OS's it can be better to have the
Bluetooth controller provide the keys directly from its semi-permanent
memory once devices are paired.
.Nm
will read, write or clear keys in device memory or the key cache
as required.
.Pp
Note that without the
.Xr bthcid 8
daemon running users will be unable to supply PINs, and Link Keys
resulting from new pairings will not be stored.
If no new pairings are expected and the keys are stored in
the controller then
.Xr bthcid 8
is not required.
.Pp
The options are as follows:
.Bl -tag -width ".Fl a Ar address"
.It Fl a Ar address
Specify the remote device address.
May be given as a BDADDR or a name.
.It Fl C
Clear key from device.
.It Fl c
Clear key from file.
.It Fl d Ar device
Specify the local device address.
May be given as a BDADDR or a name.
.It Fl k Ar key
Supply a Link Key as a string of hexadecimal digits.
Up to 32 digits will be processed and the resulting key
will be zero padded to 16 octets.
.It Fl L
List keys stored in device.
.It Fl l
List keys stored in file.
.It Fl R
Read key from device.
.It Fl r
Read key from file.
.It Fl W
Write key to device.
.It Fl w
Write key to file.
.El
.Pp
Super-user privileges are required to read or write link keys.
.Sh EXIT STATUS
.Ex -std
.Sh FILES
.Bl -item -compact
.It
.Pa /var/db/bthcid.keys
.El
.Sh EXAMPLES
Read key for mouse at ubt0 from file and write to device
.Pp
.Dl btkey -d ubt0 -a mouse -rW
.Pp
Write new key for keyboard at ubt0 to file
.Pp
.Dl btkey -d ubt0 -a keyboard -k 92beda6cd8b8f66ebd2af270d55d70ec -w
.Pp
Clear key for phone at bt3c0 from file and device
.Pp
.Dl btkey -d bt3c0 -a phone -cC
.Sh SEE ALSO
.Xr btpin 1 ,
.Xr btconfig 8 ,
.Xr bthcid 8
.Sh AUTHORS
.An Iain Hibbert