diff options
Diffstat (limited to 'doc/man/keymgr.8in')
| -rw-r--r-- | doc/man/keymgr.8in | 389 |
1 files changed, 0 insertions, 389 deletions
diff --git a/doc/man/keymgr.8in b/doc/man/keymgr.8in deleted file mode 100644 index 020d854..0000000 --- a/doc/man/keymgr.8in +++ /dev/null @@ -1,389 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KEYMGR" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -keymgr \- Knot DNS key management utility -.SH SYNOPSIS -.sp -\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP \fIcommand\fP -.sp -\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIkeystore_id\fP \fIcommand\fP -.sp -\fBkeymgr\fP [\fIconfig_option\fP] [\-j] \fB\-l\fP -.sp -\fBkeymgr\fP \fB\-t\fP \fIparameter\fP\&... -.SH DESCRIPTION -.sp -The \fBkeymgr\fP utility serves for manual key management in Knot DNS server. -.sp -Functions for DNSSEC keys and KASP (Key And Signature Policy) -management are provided. -.sp -The DNSSEC and KASP configuration is stored in a so called KASP database. -The database is backed by LMDB. -.SS Parameters -.INDENT 0.0 -.TP -\fIzone_name\fP -Name of the zone the command is executed for. -.UNINDENT -.SS Config options -.INDENT 0.0 -.TP -\fB\-c\fP, \fB\-\-config\fP \fIfile\fP -Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). -.TP -\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP -Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). -The default configuration database, if exists, has a preference to the default -configuration file. -.TP -\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP -Use specified KASP database path and default configuration. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-t\fP, \fB\-\-tsig\fP \fItsig_name\fP [\fItsig_algorithm\fP [\fItsig_bits\fP]] -Generates a TSIG key for the given name. Optionally the key algorithm can -be specified by its \fI\%name\fP (default: hmac\-sha256) and -a bit length of the key (default: optimal length given by algorithm). -The generated TSIG key is only displayed on \fIstdout\fP: -the command does not create a file, nor include the key in a keystore. -.TP -\fB\-e\fP, \fB\-\-extended\fP -Extended output (listing of keys with full description). -.TP -\fB\-j\fP, \fB\-\-json\fP -Print the zones or keys in JSON format. -.TP -\fB\-l\fP, \fB\-\-list\fP -Print the list of zones that have at least one key stored in the configured KASP -database. -.TP -\fB\-x\fP, \fB\-\-mono\fP -Don\(aqt generate colorized output. -.TP -\fB\-X\fP, \fB\-\-color\fP -Force colorized output in the normal mode. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Keymgr runs with the same user privileges as configured for \fI\%knotd\fP\&. -For example, if keymgr is run as \fBroot\fP, but the configured \fI\%user\fP -is \fBknot\fP, it won\(aqt be able to read files (PEM files, KASP database, ...) readable -only by \fBroot\fP\&. -.UNINDENT -.UNINDENT -.SS Commands -.INDENT 0.0 -.TP -\fBlist\fP [\fItimestamp_format\fP] -Prints the list of key IDs and parameters of keys belonging to the zone. -.TP -\fBgenerate\fP [\fIarguments\fP\&...] -Generates new DNSSEC key and stores it in KASP database. Prints the key ID. -This action takes some number of arguments (see below). Values for unspecified arguments are taken -from corresponding policy (if \fI\-c\fP or \fI\-C\fP options used) or from Knot policy defaults. -.TP -\fBimport\-bind\fP \fIBIND_key_file\fP -Imports a BIND\-style key into KASP database (converting it to PEM format). -Takes one argument: path to BIND key file (private or public, but both MUST exist). -.TP -\fBimport\-pub\fP \fIBIND_pubkey_file\fP -Imports a public key into KASP database. This key won\(aqt be rolled over nor used for signing. -Takes one argument: path to BIND public key file. -.TP -\fBimport\-pem\fP \fIPEM_file\fP [\fIarguments\fP\&...] -Imports a DNSSEC key from PEM file. The key parameters (same as for the generate action) need to be -specified (mainly algorithm, timers...) because they are not contained in the PEM format. -.TP -\fBimport\-pkcs11\fP \fIkey_id\fP [\fIarguments\fP\&...] -Imports a DNSSEC key from PKCS #11 storage. The key parameters (same as for the generate action) need to be -specified (mainly algorithm, timers...) because they are not available. In fact, no key -data is imported, only KASP database metadata is created. -.TP -\fBnsec3\-salt\fP [\fInew_salt\fP] -Prints the current NSEC3 salt used for signing. If \fInew_salt\fP is specified, the salt is overwritten. -The salt is printed and expected in hexadecimal, or dash if empty. -.TP -\fBlocal\-serial\fP [\fInew_serial\fP] -Print SOA serial stored in KASP database when using on\-secondary DNSSEC signing. -If \fInew_serial\fP is specified, the serial is overwritten. After updating the serial, expire the zone -(\fBzone\-purge +expire +zonefile +journal\fP) if the server is running, or remove corresponding zone file -and journal contents if the server is stopped. -.TP -\fBmaster\-serial\fP [\fInew_serial\fP] -Print SOA serial of the remote master stored in KASP database when using on\-secondary DNSSEC signing. -If \fInew_serial\fP is specified, the serial is overwritten (not recommended). -.TP -\fBset\fP \fIkey_spec\fP [\fIarguments\fP\&...] -Changes a timing argument (or ksk/zsk) of an existing key to a new value. \fIKey_spec\fP is either the -key tag or a prefix of the key ID, with an optional \fI[id=|keytag=]\fP prefix; \fIarguments\fP -are like for \fBgenerate\fP, but just the related ones. -.TP -\fBds\fP [\fIkey_spec\fP] -Generate DS record (all digest algorithms together) for specified key. \fIKey_spec\fP -is like for \fBset\fP, if unspecified, all KSKs are used. -.TP -\fBdnskey\fP [\fIkey_spec\fP] -Generate DNSKEY record for specified key. \fIKey_spec\fP -is like for \fBds\fP, if unspecified, all KSKs are used. -.TP -\fBdelete\fP \fIkey_spec\fP -Remove the specified key from zone. If the key was not shared, it is also deleted from keystore. -.TP -\fBshare\fP \fIkey_ID\fP \fIzone_from\fP -Import a key (specified by full key ID) from another zone as shared. After this, the key is -owned by both zones equally. -.UNINDENT -.SS Keystore commands -.INDENT 0.0 -.TP -\fBkeystore\-test\fP -Conduct some tests on the specified keystore. For each algorithm, key generation, -import, removal, and use (signing and verification) are tested. -Use a configured \fIkeystore_id\fP or \fB\-\fP for the default. -.TP -\fBkeystore\-bench\fP [\fInum_threads\fP] -Conduct a signing benchmark on the specified keystore. -Random blocks of data are signed by the selected number of threads -(default is 1) in a loop, and the average number of signing operations per -second for each algorithm is returned. -Use a configured \fIkeystore_id\fP or \fB\-\fP for the default. -.UNINDENT -.SS Commands related to Offline KSK feature -.INDENT 0.0 -.TP -\fBpregenerate\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP -Pre\-generate ZSKs for use with offline KSK, for the specified period starting from now or specified time. -This function also applies to non\-offline KSK keys. -.TP -\fBshow\-offline\fP [\fItimestamp\-from\fP] [\fItimestamp\-to\fP] -Print pre\-generated offline key\-related records for specified time interval. If \fItimestamp_to\fP -is omitted, it will be to infinity. If \fItimestamp\-from\fP is omitted, it will start from the -beginning. -.TP -\fBdel\-offline\fP \fItimestamp\-from\fP \fItimestamp\-to\fP -Delete pre\-generated offline key\-related records in specified time interval. -.TP -\fBdel\-all\-old\fP -Delete old keys that are in state \(aqremoved\(aq. This function also applies to -non\-offline KSK keys. -.TP -\fBgenerate\-ksr\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP -Print to stdout KeySigningRequest based on pre\-generated ZSKs for specified time period. -If \fItimestamp\-from\fP is omitted, timestamp of the last offline records set is used -or now if no records available. -.TP -\fBsign\-ksr\fP \fIksr_file\fP -Read KeySigningRequest from a text file, sign it using local keyset and print SignedKeyResponse to stdout. -.TP -\fBvalidate\-skr\fP \fIskr_file\fP -Read SignedKeyResponse from a text file and validate the RRSIGs in it if not corrupt. -.TP -\fBimport\-skr\fP \fIskr_file\fP -Read SignedKeyResponse from a text file and import the signatures for later use in zone. If some -signatures have already been imported, they will be deleted for the period from beginning of the SKR -to infinity. -.UNINDENT -.SS Generate arguments -.sp -Arguments are separated by space, each of them is in format \(aqname=value\(aq. -.INDENT 0.0 -.TP -\fBalgorithm\fP -Either an algorithm number (e.g. 14) or \fI\%algorithm name\fP -without dashes (e.g. ECDSAP384SHA384). -.TP -\fBsize\fP -Key length in bits. -.TP -\fBksk\fP -If set to \fByes\fP, the key will be used for signing DNSKEY rrset. The generated key will also -have the Secure Entry Point flag set to 1. -.TP -\fBzsk\fP -If set to \fByes\fP, the key will be used for signing zone (except DNSKEY rrset). This flag can -be set concurrently with the \fBksk\fP flag. -.TP -\fBsep\fP -Overrides the standard setting of the Secure Entry Point flag. -.UNINDENT -.sp -The following arguments are timestamps of key lifetime (see \fI\%DNSSEC key states\fP): -.INDENT 0.0 -.TP -\fBpre_active\fP -Key started to be used for signing, not published (only for algorithm rollover). -.TP -\fBpublish\fP -Key published. -.TP -\fBready\fP -Key is waiting for submission (only for KSK). -.TP -\fBactive\fP -Key used for signing. -.TP -\fBretire_active\fP -Key still used for signing, but another key is active (only for KSK or algorithm rollover). -.TP -\fBretire\fP -Key still published, but no longer used for signing. -.TP -\fBpost_active\fP -Key no longer published, but still used for signing (only for algorithm rollover). -.TP -\fBrevoke\fP -Key revoked according to \fI\%RFC 5011\fP trust anchor roll\-over. -.TP -\fBremove\fP -Key deleted. -.UNINDENT -.SS Timestamps -.INDENT 0.0 -.TP -0 -Zero timestamp means infinite future. -.TP -\fIUNIX_time\fP -Positive number of seconds since 1970 UTC. -.TP -\fIYYYYMMDDHHMMSS\fP -Date and time in this format without any punctuation. -.TP -\fIrelative_timestamp\fP -A sign character (\fB+\fP, \fB\-\fP), a number, and an optional time unit -(\fBy\fP, \fBmo\fP, \fBd\fP, \fBh\fP, \fBmi\fP, \fBs\fP). The default unit is one second. -E.g. +1mi, \-2mo. -.UNINDENT -.SS Output timestamp formats -.INDENT 0.0 -.TP -(none) -The timestamps are printed as UNIX timestamp. -.TP -\fBhuman\fP -The timestamps are printed relatively to now using time units (e.g. \-2y5mo, +1h13s). -.TP -\fBiso\fP -The timestamps are printed in the ISO8601 format (e.g. 2016\-12\-31T23:59:00). -.UNINDENT -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.INDENT 0.0 -.IP 1. 3 -Generate new TSIG key: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr \-t my_name hmac\-sha384 -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 2. 3 -Generate new DNSSEC key: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \e - ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 3. 3 -Import a DNSSEC key from BIND: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr example.com. import\-bind ~/bind/Kharbinge4d5.+007+63089.key -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 4. 3 -Configure key timing: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 5. 3 -Share a KSK from another zone: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another\-zone.com. -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fI\%RFC 6781\fP \- DNSSEC Operational Practices. -\fI\%RFC 7583\fP \- DNSSEC Key Rollover Timing Considerations. -.sp -\fBknot.conf(5)\fP, -\fBknotc(8)\fP, -\fBknotd(8)\fP\&. -.SH AUTHOR -CZ.NIC Labs <https://www.knot-dns.cz> -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. |