Introduction ------------ KSM (Key and Signature Manager) is a program to implement KASP (Key and Signature Policy). It comprises a database and command-line interface (CLI). There is also an API, but that is not described in this document. Information about DNSSEC keys is entered into the database. KSM keeps track of keys and updates their states according to the current date. Upon request, it produces a list of keys that should be published in the zone. Invocation ---------- Assuming that the KSM "bin" directory is in your path, there are three ways to invoke ksm: % ksm % ksm [-d database] [-u userid] [-p password] [-h host] % ksm [-d database] [-u userid] [-p password] [-h host] [command...] The first, invoked without any switches, will start ksm and enter interactive mode (it will prompt "ksm>") but without connecting to the database. Without the connection, it can't do anything useful, so you will need to issue the "connect" command as the first thing you do. The second form allows you to specify information for the database connection on the command line. This form also enters interactive mode, but with the connection already made. In other words, the form: % ksm [-d database] [-u userid] [-p password] [-h host] ksm> ... is equivalent to: % ksm ksm> connect [-d database] [-u userid] [-p password] [-h host] ksm> The final form of the command is the non-interactive form. ksm is started, a connection is made to the database, the given command is executed, and ksm exits. i.e. % ksm [-d database] [-u userid] [-p password] [-h host] [command...] is equivalent to: % ksm ksm> connect [-d database] [-u userid] [-p password] [-h host] ksm> command... ksm> quit % KSM Commands ------------ All commands are of the form: command [switch [switch ...]] [parameter [parameter ...]] Commands are case-sensitive. However, a command can be abbreviated to the shortest unambiguous string (e.g. "connect" can be abbreviated to "co", but not to "c" as the latter conflicts with "create"). Where a switch takes an argument, if there are several options the argument can also be shortened to the shortest unambiguous string. Several commands have synonyms - these are listed below. Commands can be split across multiple lines by ending the line with the backslash. If in interactive mode, ksm will prompt "_ksm>", the leading underscore indicating a continuation line, e.g. ksm> connect \ _ksm> -d example -p secret ksm> Date and Times -------------- Several commands require the specification of a date/time combination. ksm is liberal in what it accepts, able to cope with the following formats: YYYYMMDDHHMMSS YYYY-MM-DD:HH:MM:SS DD-MMM-YYYY:HH:MM:SS DD-MM-YYYY:HH:MM:SS In the all strings, trailing time fields can be omitted and default to 00:00:00 on the current day, e.g. YYYY-MM-DD Defaults to 00:00:00 on the day specified. DD-MM-YYYY:21 Defaults to 21:00:00 on the day specified (Leading DDs can be abbreviated to a single digit if appropriate.) The date and time can also be specified as the single word: now ... which is an abbreviation for the current date and time, taken from the system clock. Key IDs ------- Within KSM, keys are identified by a unique number. Note that this is a KSM-generated number (it is the primary key of the key table in the database), and not the DNSSEC keyid. Numbers start at 1 for the first key entered and increase with each new key. add --- Adds a key to the database. The form of the add command is: add [-a algorithm] [-k type] [-s state] [-g time] [-p time] [-e time] [-c time] [-r time] [-d time] [-l location] [-t lifetime] [-v] -a algorithm Sets the key algorithm. "algorithm" can be specified as a name or as the equivalent IANA number. Allowed values are (the IANA number is in brackets after the name): rsamd5 (1) dh (2) dsasha1 (3) rsasha1 (5) indirect (252) domain (253) oid (254) If not given, rsasha1 is the default value. -k type Sets the key type. "type" is one of: ksk Key-signing key zsk Zone-signing key If not specified on the command line, zsk is assumed by default. -s state Sets the state of the key. State is one of: generate publish ready active retire dead The default value is "generate". -g datetime Generate date/time -p datetime Publish date/time. -e datetime Ready date/time -c datetime Active date/time. -r datetime Retire date/time -d datetime Dead date/time These set the date and time for the various states. If no date/time is given, all are set to NULL except the date/time corresponding to the state, which is set to the current date and time. If ANY are given, the remainder default to NULL. -l location Location of the key. This is a string that is stored in the database and is expected to be interpreted by an external program. As such, it can be anything, e.g. the location of a key file, the device specification of an HSM etc. -t siglifetime Signature lifetime. siglifetime is an integer. It is specified in seconds but this can be modified by the appropriate suffix - s, m, h, d, w (for seconds, minutes, hours, days, weeks). By default, keys are created with a lifetime of seven days. -v Verbose - print creation of key. Keys are identified in the database by a number - this flag causes the number assigned to the key to be printed when it is created. connect ------- Connects ksm to the database: connect [-d database] [-h host] [-p password] [-u user] -d database The name of the database to which to connect. -h host This name of the system on which the database is hosted. By default, this is the system on which ksm is running. -p password If the database account has a password attached to it, this is the password. -u user UserID under which the connection to the database is made. By default, this will be the UserID under which you are logged in to the current system. create ------ "create" is a synonym for "add" and has the same syntax. debug ----- Sets debug flags that allow ksm processing to be tracked. debug A bit-encoded number indicating what options are to be enabled. Currently defined bits are: 0x01 List SQL commands as they are executed 0x02 Lists additional information in scheduling calculations delete ------ Deletes keys in the database. delete [[keyid[-keyid] [keyid[-keyid] ...] [[keyid[-keyid] [keyid[-keyid] ...] Keys to be deleted. Individual key IDs may be specified (e.g. "delete 7 19 16" etc), or one or more ranges can be given. A range are two IDs separated by a hyphen (there can be no spaces between the numbers and the hyphen) and specifies all keys in that range, e.g. 15-18 indicates keys 15, 16, 17 and 18. The order of numbers in the range is not important, so 18-15 is the same as 15-18. disconnect ---------- Disconnects from the current database: disconnect list ---- Lists keys in the database. list [-f] [[keyid[-keyid] [keyid[-keyid] ...] -f Full listing. Lists all the details about the specified key(s). If this flag is omitted, a brief listing, listing the ID, type, state, and all the dates is output. [[keyid[-keyid] [keyid[-keyid] ...] Keys to be listed. Individual key IDs may be specified (e.g. "list 7 19 16" etc), or one or more ranges can be given. A range are two IDs separated by a hyphen (there can be no spaces between the numbers and the hyphen) and specifies all keys in that range, e.g. 15-18 indicates keys 15, 16, 17 and 18. The order of numbers in the range is not important, so 18-15 is the same as 15-18. modify ------ Modifies one or more keys in the database: modify [-a algorithm] [-k type] [-s state] [-g time] [-p time] [-e time] [-c time] [-r time] [-d time] [-l location] [-t lifetime] keyid[-keyid] [keyid[-keyid]...] All switches are as described in "create". Arguments are as described in "list", although at least one key must be specified. purge ----- Deletes from the database all keys in the "dead" state. purge quit ---- Exits the program and returns to the operating system prompt. quit remove ------ "remove" is a synonym for "delete" and has the same syntax. request ------- Requests keys. Asks ksm to list all keys that should be published in the zone at the specified time. request [-k type] [-r] [-t datetime] [-v] -k type "type" is one of zsk or ksk for which the calculation should be done. If not specified, the calculation is done for both. N.B. AT PRESENT, KSM DOES NOT SUPPORT KSK CALCULATIONS. -r Force a rollover. This changes the state of the active key to "retired", so forcing a rollover. -t datetime Date and time at which the calculation is being performed. This switch is really for testing. By creating a set of keys and running "request" with the date/time set to steadily increasing values, the movement of keys through the states can be seen. If not given, the current date and time is assumed. -v Verbose. Prints out some messages as the calculation proceeds. The command prints out a set of lines describing keys that should be included in the zone file. The fields on the line are: The name of the state of the key. For ZSKs, only keys in the publish, ready, active and retired states will be printed. The active key is the one that should be used to sign the zone, the rest should just be included in the DNSKEY RRset. Number of the key in the database. (This can be used in commands that take key IDs, such as list, modify, delete.) The number corresponding to the key type, i.e. 257 for ZSK and 256 for KSK. The IANA number of the algorithm used by the key. The name of one of the parameters used in the calculations. Valid names are: clockskew Clock skew parameter ksklife KSK lifetime (unused at present) nemkeys Number of emergency ZSKs propdelay Propagation delay signint Signing interval (how long to sign the zone - unused at present) soamin "minimum" value from the zone's SOA record soattl TTL of the SOA record zsklife Lifetime of the ZSK zsksiglife Lifetime of a signature record signged with a ZSK zskttl TTL of the DNSKEY record Value for this parameter. Unless a suffix is supplied, the value is specified in seconds. Use of a suffix modifies this. Valid suffixes are: s, m, h, d, w (for seconds, minutes, hours, days, weeks), e.g. 3w is three weeks. show ---- Shows the value of a parameter (or parameters). show [parameter] parameter Optional parameter name, a listed in above for the "set" command. If omitted, all parameters are shown. source ------ Executes a list of ksm commands held in an external file: source Name of an external file holding ksm commands. "@" is a synonym for "source".