294 lines
7.0 KiB
Groff
294 lines
7.0 KiB
Groff
.\" $OpenBSD: keynote.1,v 1.38 2022/02/18 10:24:32 jsg 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: February 18 2022 $
|
|
.Dt KEYNOTE 1
|
|
.\" .TH keynote 1 local
|
|
.Os
|
|
.Sh NAME
|
|
.Nm keynote
|
|
.Nd command line tool for keynote operations
|
|
.Sh SYNOPSIS
|
|
.Nm keynote
|
|
.Cm keygen
|
|
.Ar AlgorithmName
|
|
.Ar KeySize
|
|
.Ar PublicKeyFile
|
|
.Ar PrivateKeyFile
|
|
.Op Ar print-offset
|
|
.Op Ar print-length
|
|
.Pp
|
|
.Nm
|
|
.Cm sign
|
|
.Op Fl v
|
|
.Ar AlgorithmName
|
|
.Ar AssertionFile
|
|
.Ar PrivateKeyFile
|
|
.Op Ar print-offset
|
|
.Op Ar print-length
|
|
.Pp
|
|
.Nm
|
|
.Cm sigver
|
|
.Op Ar AssertionFile
|
|
.Pp
|
|
.Nm
|
|
.Cm 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
|
|
.Cm 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
|
|
.Cm 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
|
|
.Cm 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
|
|
.Cm 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
|
|
.Cm 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
|
|
.Cm 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
|
|
.Cm verify
|
|
prints the usage message and exits with error code \-1.
|
|
.Pp
|
|
.Nm
|
|
.Cm 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 Mt angelos@cs.columbia.edu
|
|
.Sh WEB PAGE
|
|
.Lk https://www1.cs.columbia.edu/~angelos/keynote.html
|