1.\" $OpenBSD: keynote.1,v 1.35 2013/07/16 15:21:11 schwarze Exp $ 2.\" 3.\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) 4.\" 5.\" This code was written by Angelos D. Keromytis in Philadelphia, PA, USA, 6.\" in April-May 1998 7.\" 8.\" Copyright (C) 1998, 1999 by Angelos D. Keromytis. 9.\" 10.\" Permission to use, copy, and modify this software with or without fee 11.\" is hereby granted, provided that this entire notice is included in 12.\" all copies of any software which is or includes a copy or 13.\" modification of this software. 14.\" You may use this code under the GNU public license if you so wish. Please 15.\" contribute changes back to the author. 16.\" 17.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR 18.\" IMPLIED WARRANTY. IN PARTICULAR, THE AUTHORS MAKES NO 19.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE 20.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR 21.\" PURPOSE. 22.\" 23.Dd $Mdocdate: July 16 2013 $ 24.Dt KEYNOTE 1 25.\" .TH keynote 1 local 26.Os 27.Sh NAME 28.Nm keynote 29.Nd command line tool for keynote operations 30.Sh SYNOPSIS 31.Nm keynote keygen 32.Ar AlgorithmName 33.Ar KeySize 34.Ar PublicKeyFile 35.Ar PrivateKeyFile 36.Op Ar print-offset 37.Op Ar print-length 38.Pp 39.Nm keynote sign 40.Op Fl v 41.Ar AlgorithmName 42.Ar AssertionFile 43.Ar PrivateKeyFile 44.Op Ar print-offset 45.Op Ar print-length 46.Pp 47.Nm keynote sigver 48.Op Ar AssertionFile 49.Pp 50.Nm keynote verify 51.Op Fl h 52.Op Fl e Ar file 53.Op Fl k Ar file 54.Op Fl l Ar file 55.Fl r Ar retlist 56.Op Ar file ... 57.Sh DESCRIPTION 58For more details on 59.Nm KeyNote , 60see RFC 2704. 61.Sh KEY GENERATION 62.Nm keynote keygen 63creates a public/private key of size 64.Ar KeySize 65(in bits), for the algorithm specified by 66.Ar AlgorithmName . 67Typical keysizes are 512, 1024, or 2048 (bits). 68The minimum key size for DSA keys is 512 (bits). 69Supported 70.Ar AlgorithmName 71identifiers are: 72.Pp 73.Bl -tag -width Ds -offset indent -compact 74.It dsa-hex: 75.It dsa-base64: 76.It rsa-hex: 77.It rsa-base64: 78.El 79.Pp 80Notice that the trailing colon is required. 81The resulting public key is stored in file 82.Ar PublicKeyFile . 83Similarly, the resulting private key is stored in file 84.Ar PrivateKeyFile . 85Either of the filenames can be specified to be 86.Sq - , 87in which case the corresponding key(s) will be printed to standard output. 88.Pp 89The optional parameters 90.Ar print-offset 91and 92.Ar print-length 93specify the offset from the beginning of the line where the key 94will be printed, and the number of characters of the key that will 95be printed per line. 96.Ar print-length 97includes 98.Ar AlgorithmName 99for the first line and has to be longer (by at least 2) than 100.Ar AlgorithmName . 101.Ar print-length 102also accounts for the line-continuation character (backslash) at 103the end of each line, and the double quotes at the beginning and end 104of the key encoding. 105Default values are 12 and 50 respectively. 106.Sh ASSERTION SIGNING 107.Nm keynote sign 108reads the assertion contained in 109.Ar AssertionFile 110and generates a signature specified by 111.Ar AlgorithmName 112using the private key stored in 113.Ar PrivateKeyFile . 114The private key is expected to be of the form output by 115.Nm keynote keygen . 116The private key algorithm and the 117.Ar AlgorithmName 118specified as an argument are expected to match. 119There is no requirement for the internal or ASCII encodings to match. 120Valid 121.Ar AlgorithmName 122identifiers are: 123.Pp 124.Bl -tag -width Ds -offset indent -compact 125.It sig-dsa-sha1-hex: 126.It sig-dsa-sha1-base64: 127.It sig-rsa-sha1-hex: 128.It sig-rsa-sha1-base64: 129.It sig-rsa-md5-hex: 130.It sig-rsa-md5-base64: 131.It sig-x509-sha1-hex: 132.It sig-x509-sha1-base64: 133.El 134.Pp 135Notice that the trailing colon is required. 136The resulting signature is printed to standard output. 137This can then be added (via cut-and-paste or some script) at the end of the 138assertion, in the 139.Ar Signature 140field. 141.Pp 142The public key corresponding to the private key in 143.Ar PrivateKeyFile 144is expected to already be included in the 145.Ar Authorizer 146field of the assertion, either directly or indirectly (i.e., through 147use of a 148.Ar Local-Constants 149attribute). 150Furthermore, the assertion must have a 151.Ar Signature 152field (even if it is empty), as the signature is computed on 153everything between the 154.Ar KeyNote-Version 155and 156.Ar Signature 157keywords (inclusive), and the 158.Ar AlgorithmName 159string. 160.Pp 161If the 162.Fl v 163flag is provided, 164.Nm keynote sign 165will also verify the newly-created signature using the 166.Ar Authorizer 167field key. 168.Pp 169The optional parameters 170.Ar print-offset 171and 172.Ar print-length 173specify the offset from the beginning of the line where the signature 174will be printed, and the number of characters of the signature that will 175be printed per line. 176.Ar print-length 177includes 178.Ar AlgorithmName 179for the first line and has to be longer (by at least 2) than 180.Ar AlgorithmName . 181.Ar print-length 182also accounts for the line-continuation character (backslash) at 183the end of each line, and the double quotes at the beginning and end 184of the signature encoding. 185Default values are 12 and 50 respectively. 186.Sh SIGNATURE VERIFICATION 187.Nm keynote sigver 188reads the assertions contained in 189.Ar AssertionFile 190and verifies the public-key signatures on all of them. 191.Sh QUERY TOOL 192For each operand that names a 193.Ar file , 194.Nm keynote verify 195reads the file and parses the assertions contained therein (one assertion 196per file). 197.Pp 198The options are as follows: 199.Bl -tag -width "retlist" 200.It Fl e Ar file 201Specify a file containing environment variables and their values, 202in the following format: 203.Pp 204.Dl varname = \&"value\&" 205.Pp 206.Ar varname 207can begin with any letter (upper or lower case) or number, 208and can contain underscores. 209.Ar value 210is a quoted string, and can contain any character, and escape 211(backslash) processing is performed, as specified in the KeyNote 212RFC. 213.It Fl h 214Print a usage message and exit. 215.It Fl k Ar file 216Add a key from 217.Ar file 218in the action authorizers. 219.It Fl l Ar file 220Specify a file containing trusted assertions (no signature 221verification is performed), and the 222.Ar Authorizer 223field can contain non-key principals. 224There should be at least one assertion with the 225.Ar POLICY 226keyword in the 227.Ar Authorizer 228field. 229.It Fl r Ar retlist 230Specify a comma-separated list of return values, in 231increasing order of compliance from left to right. 232.El 233.Pp 234Exactly one 235.Fl r 236and at least one each of the 237.Fl e , 238.Fl l , 239and 240.Fl k 241flags should be given per invocation. 242If no flags are given, 243.Nm keynote verify 244prints the usage message and exits with error code \-1. 245.Pp 246.Nm keynote verify 247exits with code \-1 if there was an error, and 0 on success. 248.Sh SEE ALSO 249.Xr keynote 3 , 250.Xr keynote 4 , 251.Xr keynote 5 252.Rs 253.%A M. Blaze 254.%A J. Feigenbaum 255.%A J. Lacy 256.%D 1996 257.%J IEEE Symposium on Security and Privacy 258.%T Decentralized Trust Management 259.Re 260.Rs 261.%A M. Blaze 262.%A J. Feigenbaum 263.%A M. Strauss 264.%D 1998 265.%J Financial Crypto Conference 266.%T Compliance-Checking in the PolicyMaker Trust Management System 267.Re 268.Sh STANDARDS 269.Rs 270.%A M. Blaze 271.%A J. Feigenbaum 272.%A J. Ioannidis 273.%A A. Keromytis 274.%D September 1999 275.%R RFC 2704 276.%T The KeyNote Trust-Management System Version 2 277.Re 278.Sh AUTHORS 279.An Angelos D. Keromytis Aq Mt angelos@cs.columbia.edu 280.Sh WEB PAGE 281.Lk http://www1.cs.columbia.edu/~angelos/keynote.html 282.Sh BUGS 283None that we know of. 284If you find any, please report them at 285.Aq Mt keynote@research.att.com . 286