.\" $OpenBSD: keynote.1,v 1.34 2012/09/27 11:31:58 jmc Exp $
.\"
.\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu)
.\"
.\" This code was written by Angelos D. Keromytis in Philadelphia, PA, USA,
.\" in April-May 1998
.\"
.\" Copyright (C) 1998, 1999 by Angelos D. Keromytis.
.\"
.\" Permission to use, copy, and modify this software with or without fee
.\" is hereby granted, provided that this entire notice is included in
.\" all copies of any software which is or includes a copy or
.\" modification of this software.
.\" You may use this code under the GNU public license if you so wish. Please
.\" contribute changes back to the author.
.\"
.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTY. IN PARTICULAR, THE AUTHORS MAKES NO
.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
.\" PURPOSE.
.\"
.Dd $Mdocdate: September 27 2012 $
.Dt KEYNOTE 1
.\" .TH keynote 1 local
.Os
.Sh NAME
.Nm keynote
.Nd command line tool for keynote operations
.Sh SYNOPSIS
.Nm keynote keygen
.Ar AlgorithmName
.Ar KeySize
.Ar PublicKeyFile
.Ar PrivateKeyFile
.Op Ar print-offset
.Op Ar print-length
.Pp
.Nm keynote sign
.Op Fl v
.Ar AlgorithmName
.Ar AssertionFile
.Ar PrivateKeyFile
.Op Ar print-offset
.Op Ar print-length
.Pp
.Nm keynote sigver
.Op Ar AssertionFile
.Pp
.Nm keynote verify
.Op Fl h
.Op Fl e Ar file
.Op Fl k Ar file
.Op Fl l Ar file
.Fl r Ar retlist
.Op Ar file ...
.Sh DESCRIPTION
For more details on
.Nm KeyNote ,
see RFC 2704.
.Sh KEY GENERATION
.Nm keynote keygen
creates a public/private key of size
.Ar KeySize
(in bits), for the algorithm specified by
.Ar AlgorithmName .
Typical keysizes are 512, 1024, or 2048 (bits).
The minimum key size for DSA keys is 512 (bits).
Supported
.Ar AlgorithmName
identifiers are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It dsa-hex:
.It dsa-base64:
.It rsa-hex:
.It rsa-base64:
.El
.Pp
Notice that the trailing colon is required.
The resulting public key is stored in file
.Ar PublicKeyFile .
Similarly, the resulting private key is stored in file
.Ar PrivateKeyFile .
Either of the filenames can be specified to be
.Sq - ,
in which case the corresponding key(s) will be printed to standard output.
.Pp
The optional parameters
.Ar print-offset
and
.Ar print-length
specify the offset from the beginning of the line where the key
will be printed, and the number of characters of the key that will
be printed per line.
.Ar print-length
includes
.Ar AlgorithmName
for the first line and has to be longer (by at least 2) than
.Ar AlgorithmName .
.Ar print-length
also accounts for the line-continuation character (backslash) at
the end of each line, and the double quotes at the beginning and end
of the key encoding.
Default values are 12 and 50 respectively.
.Sh ASSERTION SIGNING
.Nm keynote sign
reads the assertion contained in
.Ar AssertionFile
and generates a signature specified by
.Ar AlgorithmName
using the private key stored in
.Ar PrivateKeyFile .
The private key is expected to be of the form output by
.Nm keynote keygen .
The private key algorithm and the
.Ar AlgorithmName
specified as an argument are expected to match.
There is no requirement for the internal or ASCII encodings to match.
Valid
.Ar AlgorithmName
identifiers are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It sig-dsa-sha1-hex:
.It sig-dsa-sha1-base64:
.It sig-rsa-sha1-hex:
.It sig-rsa-sha1-base64:
.It sig-rsa-md5-hex:
.It sig-rsa-md5-base64:
.It sig-x509-sha1-hex:
.It sig-x509-sha1-base64:
.El
.Pp
Notice that the trailing colon is required.
The resulting signature is printed to standard output.
This can then be added (via cut-and-paste or some script) at the end of the
assertion, in the
.Ar Signature
field.
.Pp
The public key corresponding to the private key in
.Ar PrivateKeyFile
is expected to already be included in the
.Ar Authorizer
field of the assertion, either directly or indirectly (i.e., through
use of a
.Ar Local-Constants
attribute).
Furthermore, the assertion must have a
.Ar Signature
field (even if it is empty), as the signature is computed on
everything between the
.Ar KeyNote-Version
and
.Ar Signature
keywords (inclusive), and the
.Ar AlgorithmName
string.
.Pp
If the
.Fl v
flag is provided,
.Nm keynote sign
will also verify the newly-created signature using the
.Ar Authorizer
field key.
.Pp
The optional parameters
.Ar print-offset
and
.Ar print-length
specify the offset from the beginning of the line where the signature
will be printed, and the number of characters of the signature that will
be printed per line.
.Ar print-length
includes
.Ar AlgorithmName
for the first line and has to be longer (by at least 2) than
.Ar AlgorithmName .
.Ar print-length
also accounts for the line-continuation character (backslash) at
the end of each line, and the double quotes at the beginning and end
of the signature encoding.
Default values are 12 and 50 respectively.
.Sh SIGNATURE VERIFICATION
.Nm keynote sigver
reads the assertions contained in
.Ar AssertionFile
and verifies the public-key signatures on all of them.
.Sh QUERY TOOL
For each operand that names a
.Ar file ,
.Nm keynote verify
reads the file and parses the assertions contained therein (one assertion
per file).
.Pp
The options are as follows:
.Bl -tag -width "retlist"
.It Fl e Ar file
Specify a file containing environment variables and their values,
in the following format:
.Pp
.Dl varname = \&"value\&"
.Pp
.Ar varname
can begin with any letter (upper or lower case) or number,
and can contain underscores.
.Ar value
is a quoted string, and can contain any character, and escape
(backslash) processing is performed, as specified in the KeyNote
RFC.
.It Fl h
Print a usage message and exit.
.It Fl k Ar file
Add a key from
.Ar file
in the action authorizers.
.It Fl l Ar file
Specify a file containing trusted assertions (no signature
verification is performed), and the
.Ar Authorizer
field can contain non-key principals.
There should be at least one assertion with the
.Ar POLICY
keyword in the
.Ar Authorizer
field.
.It Fl r Ar retlist
Specify a comma-separated list of return values, in
increasing order of compliance from left to right.
.El
.Pp
Exactly one
.Fl r
and at least one each of the
.Fl e ,
.Fl l ,
and
.Fl k
flags should be given per invocation.
If no flags are given,
.Nm keynote verify
prints the usage message and exits with error code \-1.
.Pp
.Nm keynote verify
exits with code \-1 if there was an error, and 0 on success.
.Sh SEE ALSO
.Xr keynote 3 ,
.Xr keynote 4 ,
.Xr keynote 5
.Rs
.%A M. Blaze
.%A J. Feigenbaum
.%A J. Lacy
.%D 1996
.%J IEEE Symposium on Security and Privacy
.%T Decentralized Trust Management
.Re
.Rs
.%A M. Blaze
.%A J. Feigenbaum
.%A M. Strauss
.%D 1998
.%J Financial Crypto Conference
.%T Compliance-Checking in the PolicyMaker Trust Management System
.Re
.Sh STANDARDS
.Rs
.%A M. Blaze
.%A J. Feigenbaum
.%A J. Ioannidis
.%A A. Keromytis
.%D September 1999
.%R RFC 2704
.%T The KeyNote Trust-Management System Version 2
.Re
.Sh AUTHORS
.An Angelos D. Keromytis Aq angelos@cs.columbia.edu
.Sh WEB PAGE
.Lk http://www1.cs.columbia.edu/~angelos/keynote.html
.Sh BUGS
None that we know of.
If you find any, please report them at
.Aq keynote@research.att.com .