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