From 102f0570ec4810a60dbd0e590fccd6aeb3751c0a Mon Sep 17 00:00:00 2001 From: Davide Pesavento Date: Sat, 22 Jun 2024 15:00:06 -0400 Subject: [PATCH] docs: ndnsec man pages improvements * Add a "See Also" section to most pages * Streamline/clarify some sentences * Refresh a few examples Change-Id: I3e0b62ad01c06faac632a120cde22a8da472426e --- docs/manpages/ndnsec-cert-dump.rst | 30 ++++++++--- docs/manpages/ndnsec-cert-gen.rst | 36 ++++++++----- docs/manpages/ndnsec-cert-install.rst | 24 +++++---- docs/manpages/ndnsec-delete.rst | 23 ++++---- docs/manpages/ndnsec-export.rst | 36 ++++++++----- docs/manpages/ndnsec-get-default.rst | 28 ++++++---- docs/manpages/ndnsec-import.rst | 24 +++++---- docs/manpages/ndnsec-key-gen.rst | 54 +++++++++---------- docs/manpages/ndnsec-list.rst | 65 ++++++++++++++-------- docs/manpages/ndnsec-set-default.rst | 29 +++++----- docs/manpages/ndnsec-sign-req.rst | 78 +++++++++++---------------- docs/manpages/ndnsec-unlock-tpm.rst | 6 +-- docs/manpages/ndnsec.rst | 15 ++++-- 13 files changed, 260 insertions(+), 188 deletions(-) diff --git a/docs/manpages/ndnsec-cert-dump.rst b/docs/manpages/ndnsec-cert-dump.rst index c5ca0d9d3..2acab6ee6 100644 --- a/docs/manpages/ndnsec-cert-dump.rst +++ b/docs/manpages/ndnsec-cert-dump.rst @@ -4,14 +4,15 @@ ndnsec-cert-dump Synopsis -------- -**ndnsec-cert-dump** [**-h**] [**-p**] [**-r** [**-H** *host*] [**-P** *port*]] +**ndnsec cert-dump** [**-h**] [**-p**] [**-r** [**-H** *host*] [**-P** *port*]] [**-i**\|\ **-k**\|\ **-f**] *name* Description ----------- -:program:`ndnsec-cert-dump` reads a certificate from the **Public Info Base (PIB)** -or from a file, and prints it on the standard output in Base64 encoding. +This command reads an NDN certificate, either from the **Public Information Base (PIB)** +or from the specified file, and prints it on the standard output, either in Base64 encoding +or in a human-readable format. By default, *name* is interpreted as a certificate name. @@ -37,16 +38,23 @@ Options Print the certificate in a human-readable format. -Example -------- +Examples +-------- -Dump a certificate from PIB to standard output:: +Export a certificate from the local PIB to the standard output with Base64 encoding:: - $ ndnsec-cert-dump /ndn/test/david/KEY/ksk-1396913058196/ID-CERT/%00%00%01E%3E%9D%A0%DE + $ ndnsec cert-dump /ndn/test/david/KEY/%7FE%1C%18%D2%03%BD%3F/self/v=1719080300644 + Bv0BOAcxCANuZG4IBHRlc3QIBWRhdmlkCANLRVkICH9FHBjSA70/CARzZWxmNggA + AAGQQSuwZBQJGAECGQQANu6AFVswWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQ8 + 7QbdgubF3IznydpZ8PuppHgVRufGsUMDvHpS8Rw93rAAsw+8aVcNmw94wzpALWzD + 3femcs+qHaWoIOBOn26SFlIbAQMcIwchCANuZG4IBHRlc3QIBWRhdmlkCANLRVkI + CH9FHBjSA70//QD9Jv0A/g8yMDI0MDYyMlQxODE4MjD9AP8PMjA0NDA2MTdUMTgx + ODIwF0cwRQIhAPqG+GtIQlbcgB9ZFAGCKcO7DBMK+K3RinEAbzqKpFTcAiAp+D8L + z/S6nPNtSTGBBxr4cdUecjIHxKN6DoP3K1o2yg== Print the NDN testbed root certificate in human-readable format:: - $ curl -A ndnsec -fsLS https://named-data.net/ndnsec/ndn-testbed-root.ndncert.x3.base64 | ndnsec-cert-dump -fp - + $ curl -A ndnsec -fsLS https://named-data.net/ndnsec/ndn-testbed-root.ndncert.x3.base64 | ndnsec cert-dump -fp - Certificate Name: /ndn/KEY/%EC%F1L%8EQ%23%15%E0/ndn/%FD%00%00%01u%E6%7F2%10 Additional Description: @@ -62,3 +70,9 @@ Print the NDN testbed root certificate in human-readable format:: Signature Type: SignatureSha256WithEcdsa Key Locator: Name=/ndn/KEY/%EC%F1L%8EQ%23%15%E0 Self-Signed: yes + +See Also +-------- + +:manpage:`ndnsec-cert-install(1)`, +:manpage:`ndnsec-export(1)` diff --git a/docs/manpages/ndnsec-cert-gen.rst b/docs/manpages/ndnsec-cert-gen.rst index db4f03cf7..b51b338af 100644 --- a/docs/manpages/ndnsec-cert-gen.rst +++ b/docs/manpages/ndnsec-cert-gen.rst @@ -4,23 +4,23 @@ ndnsec-cert-gen Synopsis -------- -**ndnsec-cert-gen** [**-h**] [**-S** *timestamp*] [**-E** *timestamp*] +**ndnsec cert-gen** [**-h**] [**-S** *timestamp*] [**-E** *timestamp*] [**-I** *info*]... [**-s** *signer*] [**-i** *issuer*] *file* Description ----------- -:program:`ndnsec-cert-gen` takes a signing request as input and issues an -identity certificate for the key in the signing request. The signing request -can be created with :program:`ndnsec-key-gen` and can be re-generated with -:program:`ndnsec-sign-req`. +This command takes a signing request as input and issues an identity certificate for +the key contained in the signing request. +A signing request is generated automatically by :program:`ndnsec-key-gen` for any new +key, or it can be manually created for an existing key with :program:`ndnsec-sign-req`. -By default, the default key is used to sign the issued certificate. +Unless specified otherwise, the default key is used to sign the issued certificate. -*file* is the name of a file that contains the signing request. If *file* is -"-", the signing request is read from the standard input. +*file* is the name of a file that contains the signing request. +If *file* is "-", the signing request is read from the standard input. -The generated certificate is written to the standard output in base64 encoding. +The generated certificate is written to the standard output in Base64 encoding. Options ------- @@ -33,7 +33,7 @@ Options .. option:: -E , --not-after Date and time when the certificate expires, in "YYYYMMDDhhmmss" format. - The default value is 365 days after the **--not-before** timestamp. + The default value is 365 days after the :option:`--not-before` timestamp. .. option:: -I , --info @@ -57,12 +57,12 @@ Options Issuer's ID to be included in the issued certificate name. The default value is "NA". -Example -------- +Examples +-------- :: - $ ndnsec-cert-gen -S 20200501000000 -E 20210101000000 -I "affiliation Some Organization" -I "foobar Foo Bar" -i "Universe" -s /ndn/test request.cert > signed.cert + $ ndnsec cert-gen -S 20200501000000 -E 20210101000000 -I "affiliation Some Organization" -I "foobar Foo Bar" -i "Universe" -s /ndn/test request.cert > signed.cert $ cat signed.cert Bv0BcgctCAdleGFtcGxlCANLRVkICOQUmX8oloLrCAhVbml2ZXJzZQgJ/QAAAXHR @@ -74,7 +74,7 @@ Example YXL9AgIHRm9vIEJhchdHMEUCIQDPT9Hq1kvkE0r9W1aYSBVTnHlTEzgtz+v1DwkC ug/vLAIgY3xJITCwf55sqey33q5GIQSk1TRCkNNl58ojvPs5sNU= - $ ndnsec-cert-dump -p -f signed.cert + $ ndnsec cert-dump -p -f signed.cert Certificate Name: /example/KEY/%E4%14%99%7F%28%96%82%EB/Universe/%FD%00%00%01q%D1%02N%82 Additional Description: @@ -90,3 +90,11 @@ Example Signature Information: Signature Type: SignatureSha256WithEcdsa Key Locator: Name=/ndn/test/KEY/I%3FS%9A%28%BB%9A%95 + +See Also +-------- + +:manpage:`ndnsec-cert-dump(1)`, +:manpage:`ndnsec-cert-install(1)`, +:manpage:`ndnsec-key-gen(1)`, +:manpage:`ndnsec-sign-req(1)` diff --git a/docs/manpages/ndnsec-cert-install.rst b/docs/manpages/ndnsec-cert-install.rst index 1f83d1125..3dcc9489a 100644 --- a/docs/manpages/ndnsec-cert-install.rst +++ b/docs/manpages/ndnsec-cert-install.rst @@ -4,15 +4,14 @@ ndnsec-cert-install Synopsis -------- -**ndnsec-cert-install** [**-h**] [**-I**\|\ **-K**\|\ **-N**] *file* +**ndnsec cert-install** [**-h**] [**-I**\|\ **-K**\|\ **-N**] *file* Description ----------- -:program:`ndnsec-cert-install` allows importing a certificate into the -**Public Information Base (PIB)**. By default, the installed certificate -will be set as the default certificate for the corresponding identity and -the identity will be set as the user's default identity. +This command allows importing a certificate into the **Public Information Base (PIB)**. +By default, the installed certificate will be set as the default certificate for the +corresponding identity and the identity will be set as the user's default identity. *file* is a path to a file that contains the certificate to install. If *file* is "-", the certificate will be read from the standard input. @@ -35,13 +34,20 @@ Options Install the certificate but do not change any default settings. -Example -------- +Examples +-------- Install a certificate and set it as the default certificate:: - $ ndnsec-cert-install cert_file.cert + $ ndnsec cert-install cert_file.cert Install a certificate but do not change any default settings:: - $ ndnsec-cert-install -N cert_file.cert + $ ndnsec cert-install -N cert_file.cert + +See Also +-------- + +:manpage:`ndnsec-cert-dump(1)`, +:manpage:`ndnsec-cert-gen(1)`, +:manpage:`ndnsec-import(1)` diff --git a/docs/manpages/ndnsec-delete.rst b/docs/manpages/ndnsec-delete.rst index 141aa0c81..fc47169a7 100644 --- a/docs/manpages/ndnsec-delete.rst +++ b/docs/manpages/ndnsec-delete.rst @@ -4,15 +4,15 @@ ndnsec-delete Synopsis -------- -**ndnsec-delete** [**-h**] [**-k**\|\ **-c**] *name* +**ndnsec delete** [**-h**] [**-k**\|\ **-c**] *name* Description ----------- -:program:`ndnsec-delete` allows to delete security data from both the -**Public Info Base (PIB)** and the **Trusted Platform Module (TPM)**. +This command allows deleting security data from both the +**Public Information Base (PIB)** and the **Trusted Platform Module (TPM)**. -By default, :program:`ndnsec-delete` will interpret *name* as an identity name. +By default, *name* is interpreted as an identity name. If an identity is deleted, all keys and certificates belonging to that identity will be deleted as well. If a key is deleted, all certificates associated with that key will be deleted as well. @@ -33,11 +33,16 @@ Exit Status Normally, the exit status is 0 if the requested entity is deleted successfully. If the entity to be deleted does not exist, the exit status is 1. -For other errors, the exit status is 2. +For any other errors, the exit status is 2. -Example -------- +Examples +-------- + +Delete all data related to the identity ``/ndn/test/david``:: -Delete all data related to an identity:: + $ ndnsec delete /ndn/test/david + +See Also +-------- - $ ndnsec-delete /ndn/test/david +:manpage:`ndnsec-list(1)` diff --git a/docs/manpages/ndnsec-export.rst b/docs/manpages/ndnsec-export.rst index de232a6d6..86b62d023 100644 --- a/docs/manpages/ndnsec-export.rst +++ b/docs/manpages/ndnsec-export.rst @@ -4,27 +4,31 @@ ndnsec-export Synopsis -------- -**ndnsec-export** [**-h**] [**-o** *file*] [**-P** *passphrase*] +**ndnsec export** [**-h**] [**-o** *file*] [**-P** *passphrase*] [**-i**\|\ **-k**\|\ **-c**] *name* Description ----------- -:program:`ndnsec-export` exports a certificate from the **Public Info Base (PIB)** and -its private key to a file. It will ask for a passphrase to encrypt the private key. -The resulting file can be imported again using :program:`ndnsec-import`. +Export a certificate from the local **Public Information Base (PIB)** and its private key to +a file in **SafeBag** format. +The command will interactively ask for a passphrase to be used for encrypting the private key. + +The resulting file can be later imported using :program:`ndnsec-import`. Options ------- .. option:: -i, --identity - Interpret *name* as an identity name. The default certificate of the identity will be exported. - This is the default unless **-k** or **-c** is specified. + Interpret *name* as an identity name. + The default certificate of the identity will be exported. + This is the default unless :option:`-k` or :option:`-c` is specified. .. option:: -k, --key - Interpret *name* as a key name. The default certificate of the key will be exported. + Interpret *name* as a key name. + The default certificate of the key will be exported. .. option:: -c, --cert @@ -36,18 +40,24 @@ Options .. option:: -P , --password - Passphrase to use for the export. If empty or not specified, the user is + Passphrase to use for encryption. If empty or not specified, the user is interactively asked to type the passphrase on the terminal. Note that specifying the passphrase via this option is insecure, as it can potentially end up in the shell's history, be visible in :command:`ps` output, and so on. -Example -------- +Examples +-------- -Export an identity's default certificate and private key into a file:: +Export an identity's default certificate and private key to a file:: - $ ndnsec-export -o alice.ndnkey /ndn/test/alice + $ ndnsec export -o alice.ndnkey /ndn/test/alice Export a specific certificate and its private key to the standard output:: - $ ndnsec-export -c /ndn/edu/ucla/alice/KEY/1%5D%A7g%90%B2%CF%AA/self/%FD%00%00%01r-%D3%DC%2A + $ ndnsec export -c /ndn/edu/ucla/alice/KEY/1%5D%A7g%90%B2%CF%AA/self/%FD%00%00%01r-%D3%DC%2A + +See Also +-------- + +:manpage:`ndnsec-cert-dump(1)`, +:manpage:`ndnsec-import(1)` diff --git a/docs/manpages/ndnsec-get-default.rst b/docs/manpages/ndnsec-get-default.rst index 0a27dee72..aa9e7d901 100644 --- a/docs/manpages/ndnsec-get-default.rst +++ b/docs/manpages/ndnsec-get-default.rst @@ -4,15 +4,17 @@ ndnsec-get-default Synopsis -------- -**ndnsec-get-default** [**-h**] [**-k**\|\ **-c**] [**-i** *identity*\|\ **-K** *key*] [**-q**] +**ndnsec get-default** [**-h**] [**-k**\|\ **-c**] [**-i** *identity*\|\ **-K** *key*] +[**-q**] Description ----------- -Given a particular entity, :program:`ndnsec-get-default` shows its default settings -according to the command-line options. By default, if neither **-i** nor **-K** is -given, the command displays the default identity or the default key/certificate of -the default identity. +This command shows the default settings of the local **Public Information Base (PIB)** +or those of a specific PIB identity or key. + +By default, if neither :option:`-i` nor :option:`-K` is given, the command displays +the default identity or the default key/certificate of the default identity. Options ------- @@ -37,20 +39,26 @@ Options Disable printing the trailing newline character. -Example -------- +Examples +-------- Display an identity's default key name:: - $ ndnsec-get-default -k -i /ndn/test/alice + $ ndnsec get-default -k -i /ndn/test/alice /ndn/test/alice/ksk-1394129695025 Display an identity's default certificate name:: - $ ndnsec-get-default -c -i /ndn/test/alice + $ ndnsec get-default -c -i /ndn/test/alice /ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F Display a key's default certificate name:: - $ ndnsec-get-default -c -K /ndn/test/alice/ksk-1394129695025 + $ ndnsec get-default -c -K /ndn/test/alice/ksk-1394129695025 /ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F + +See Also +-------- + +:manpage:`ndnsec-list(1)`, +:manpage:`ndnsec-set-default(1)` diff --git a/docs/manpages/ndnsec-import.rst b/docs/manpages/ndnsec-import.rst index 7c25a6aeb..19394aff9 100644 --- a/docs/manpages/ndnsec-import.rst +++ b/docs/manpages/ndnsec-import.rst @@ -4,30 +4,36 @@ ndnsec-import Synopsis -------- -**ndnsec-import** [**-h**] [**-P** *passphrase*] *file* +**ndnsec import** [**-h**] [**-P** *passphrase*] *file* Description ----------- -:program:`ndnsec-import` imports a certificate and its private key from a file -created by :program:`ndnsec-export`. It will ask for the passphrase used to -encrypt the private key. +Import a certificate and its private key from a file in **SafeBag** format. +The command will interactively ask for a passphrase to be used for decrypting the private key. +If *file* is "-", the **SafeBag** data will be read from the standard input. -If *file* is "-", read from the standard input. +:program:`ndnsec-export` can be used to create a file in the expected format. Options ------- .. option:: -P , --password - Passphrase to use for the export. If empty or not specified, the user is + Passphrase to use for decryption. If empty or not specified, the user is interactively asked to type the passphrase on the terminal. Note that specifying the passphrase via this option is insecure, as it can potentially end up in the shell's history, be visible in :command:`ps` output, and so on. -Example -------- +Examples +-------- Import a certificate and private key from a file:: - $ ndnsec-import alice.ndnkey + $ ndnsec import alice.ndnkey + +See Also +-------- + +:manpage:`ndnsec-cert-install(1)`, +:manpage:`ndnsec-export(1)` diff --git a/docs/manpages/ndnsec-key-gen.rst b/docs/manpages/ndnsec-key-gen.rst index 2df523787..49ef7772e 100644 --- a/docs/manpages/ndnsec-key-gen.rst +++ b/docs/manpages/ndnsec-key-gen.rst @@ -4,18 +4,18 @@ ndnsec-key-gen Synopsis -------- -**ndnsec-key-gen** [**-h**] [**-n**] [**-t** *type*] +**ndnsec key-gen** [**-h**] [**-n**] [**-t** *type*] [**-k** *keyidtype*\|\ **--keyid** *keyid*] *identity* Description ----------- -:program:`ndnsec-key-gen` generates a key pair for the specified *identity* and -sets the generated public key as the identity's default key. -:program:`ndnsec-key-gen` will also create a signing request for the generated key. -The signing request will be written to the standard output in base64 encoding. +Generate a public/private key pair for the specified *identity* and set the newly generated +public key as the identity's default key. +Unless :option:`-n` is specified, the identity is also set as the user's default identity. -By default, it will also set the identity as the user's default identity. +This command will automatically create a signing request for the generated key. +The signing request will be written to the standard output in Base64 encoding. Options ------- @@ -34,32 +34,28 @@ Options .. option:: -k , --keyid-type Type of KeyId for the generated key. "r" for a 64-bit random number (the default - unless **--keyid** is specified), "h" for the SHA-256 of the public key. + unless :option:`--keyid` is specified), "h" for the SHA-256 of the public key. .. option:: --keyid User-specified KeyId. Must be a non-empty generic name component. -Example -------- +Examples +-------- + +Generate a new default key for the identity ``/ndn/test/david``:: + + $ ndnsec key-gen /ndn/test/david + Bv0BNwcxCANuZG4IBHRlc3QIBWRhdmlkCANLRVkICLe4LjaLILlwCARzZWxmNggA + AAGQQSVMERQJGAECGQQANu6AFVswWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASc + RppJ1qQzCpTyjvsX33fW9/WxopTdoEwfMZENOC960YB7g/LMhWx10ws4benYxIO2 + ELirW0NZ6Wu5VUuzfyjfFlIbAQMcIwchCANuZG4IBHRlc3QIBWRhdmlkCANLRVkI + CLe4LjaLILlw/QD9Jv0A/g8yMDI0MDYyMlQxODExMjH9AP8PMjA0NDA2MTdUMTgx + MTIxF0YwRAIgLJWFpcWrmaOuXW5W+im9al+7TinaEqodve+vrJ2VE5sCIHyrWB+5 + g2bl11aVNycEnMvG8KRSJoHRvNkx7+6RV33s + +See Also +-------- -:: - - $ ndnsec-key-gen /ndn/test/david - Bv0DAAc9CANuZG4IBHRlc3QIBWRhdmlkCANLRVkIEWtzay0xMzk2OTEzMDU4MTk2 - CAdJRC1DRVJUCAgAAAFFPoG0ohQDGAECFf0BeDCCAXQwIhgPMjAxNDA0MDcyMzI0 - MThaGA8yMDM0MDQwMjIzMjQxOFowKjAoBgNVBCkTIS9uZG4vdGVzdC9kYXZpZC9r - c2stMTM5NjkxMzA1ODE5NjCCASAwDQYJKoZIhvcNAQEBBQADggENADCCAQgCggEB - ALS6udLacpydecxMRIfZeo74fxzpsITqaa/4UxD2FJ9lU4dtfiSSIOaRwAB/w0K/ - AauQRq3Q1AiEocUsW2h8LmtcuF4Cj9TGAUD/1s3CISMwf9zwQ3ZhNIzN0IOsrpPA - TsHrbdwtOxrcFvXX4GnMLWgtvcSB52Cn68h/4AUiA1CG9/DOyCyA4EHiIkHBxh6B - TvAmw7SmNjr1ZBTYMaMAEV5/oLZCHzHRO+2fKdEttaWH3bz7iKVVS8u5ZxXcBs8g - ot55m7Xf6/TUk3qQXM1kM8wW04U+8n3jch1i7tD2T3c/OFKTT7AWndwcfbU99Z6C - FZ7fMsgRHxFNY8hCFZJvFFUCAREWOhsBARw1BzMIA25kbggEdGVzdAgFZGF2aWQI - A0tFWQgRa3NrLTEzOTY5MTMwNTgxOTYIB0lELUNFUlQX/QEAW2yfF8JTgu5okR+n - dRlXc3UR/b1REegrpQb3xVzs7fYiiHwFYzQE9RzOuGh/9GSMvQcfejsPw021tJnj - oxNx6spGTOK5Bc0QZGeC6YyNoVSaJr9Obc5Uh8eRqxw76r0pCUHP+l38UgUGeBg/ - aHurtcu5zK0zFYX++SAfUGLUZlG4CqKBUNZC+6w9OGUXlcW411zMzfqQ7V9Gxg+p - 1IMNJQ6trTFdIwT/4YWHsxR+16r2TRWCNHtJey2GEG84YoqRh8y37jnu7oPhAtTN - TgG9O7O39dZLiFg+UP3LpW1LY64fJXsNfZQmnZWcNo5lX6MXfeiPxWFjOQqnno82 - 1hgqgA== +:manpage:`ndnsec-cert-gen(1)`, +:manpage:`ndnsec-sign-req(1)` diff --git a/docs/manpages/ndnsec-list.rst b/docs/manpages/ndnsec-list.rst index e0fde91f0..5c3e8f9ba 100644 --- a/docs/manpages/ndnsec-list.rst +++ b/docs/manpages/ndnsec-list.rst @@ -4,43 +4,54 @@ ndnsec-list Synopsis -------- -**ndnsec-list** [**-h**] [**-k**\|\ **-c**] +**ndnsec list** [**-h**] [**-k**] [**-c**] [**-v**\|\ **-vv**\|\ **-vvv**] Description ----------- -:program:`ndnsec-list` prints the names of all the entities stored in the -**Public Information Base (PIB)**, such as identities, keys, and certificates, -up to the given granularity level. By default, only the identity names are -shown. The default entities will be marked with a "*" in front of their names. +Print the names of all the entities stored in the **Public Information Base (PIB)**, +such as identities, keys, and certificates, up to the given granularity level. -For example:: - - $ ndnsec list - * /ndn/edu/ucla/cs/yingdi - /ndn/test/cathy - /ndn/test/bob - /ndn/test/alice +By default, only the identity names are shown. In the output, the default entities +are marked with an asterisk ("*") in front of their names. Options ------- .. option:: -k, --key - Display key names for each identity. The key name with a "*" in front is - the default key name of the corresponding identity. + Also list the key names for each identity. + An asterisk ("*") in front of a key name indicates the default key of the corresponding + identity. .. option:: -c, --cert - Display certificate names for each key. The certificate name with a "*" - in front is the default certificate name of the corresponding key. + Also list the certificate names for each key. Implies :option:`-k`. + An asterisk ("*") in front of a certificate name indicates the default certificate of + the corresponding key. -Example -------- +.. option:: -v, -vv, -vvv, --verbose + + Verbose output mode. + This option can be repeated up to three times to increase the level of verbosity: + :option:`-v` is equivalent to :option:`-k`; + :option:`-vv` is equivalent to :option:`-c`; + :option:`-vvv` prints detailed information for each certificate. + +Examples +-------- -Display all the key names in PIB:: +Display all identity names in the PIB:: - $ ndnsec-list -k + $ ndnsec list + * /ndn/edu/ucla/cs/yingdi + /ndn/test/cathy + /ndn/test/bob + /ndn/test/alice + +Display all key names in the PIB:: + + $ ndnsec list -k * /ndn/edu/ucla/cs/yingdi +->* /ndn/edu/ucla/cs/yingdi/ksk-1397247318867 +-> /ndn/edu/ucla/cs/yingdi/ksk-1393811874052 @@ -54,9 +65,9 @@ Display all the key names in PIB:: /ndn/test/alice +->* /ndn/test/alice/ksk-1394129695025 -Display all the certificate names in PIB:: +Display all certificate names in the PIB:: - $ ndnsec-list -c + $ ndnsec list -c * /ndn/edu/ucla/cs/yingdi +->* /ndn/edu/ucla/cs/yingdi/ksk-1397247318867 +->* /ndn/edu/ucla/cs/yingdi/KEY/ksk-1397247318867/ID-CERT/%00%00%01ERn%1B%BE @@ -74,3 +85,13 @@ Display all the certificate names in PIB:: /ndn/test/alice +->* /ndn/test/alice/ksk-1394129695025 +->* /ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F + +See Also +-------- + +:manpage:`ndnsec-cert-dump(1)`, +:manpage:`ndnsec-cert-install(1)`, +:manpage:`ndnsec-delete(1)`, +:manpage:`ndnsec-get-default(1)`, +:manpage:`ndnsec-key-gen(1)`, +:manpage:`ndnsec-set-default(1)` diff --git a/docs/manpages/ndnsec-set-default.rst b/docs/manpages/ndnsec-set-default.rst index 05c66777f..3f6b981d4 100644 --- a/docs/manpages/ndnsec-set-default.rst +++ b/docs/manpages/ndnsec-set-default.rst @@ -4,14 +4,14 @@ ndnsec-set-default Synopsis -------- -**ndnsec-set-default** [**-h**] [**-k**\|\ **-c**] *name* +**ndnsec set-default** [**-h**] [**-k**\|\ **-c**] *name* Description ----------- -:program:`ndnsec-set-default` allows changing the default security settings. +This command allows changing the default security settings. -Without any options, *name*, which must be an identity name, is set as the +Without any options, *name*, which must refer to an existing NDN identity, is set as the default identity for the current user. Options @@ -19,25 +19,30 @@ Options .. option:: -k, --default-key - Set *name*, which must be a key name, as the default key for the - corresponding identity. + Set *name*, which must be a key name, as the default key for the corresponding identity. .. option:: -c, --default-cert - Set *name*, which must be a certificate name, as the default certificate - for the corresponding key. + Set *name*, which must be a certificate name, as the default certificate for the + corresponding key. -Example -------- +Examples +-------- Set a key's default certificate:: - $ ndnsec-set-default -c /ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F + $ ndnsec set-default -c /ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F Set an identity's default key:: - $ ndnsec-set-default -k /ndn/test/alice/ksk-1394129695025 + $ ndnsec set-default -k /ndn/test/alice/ksk-1394129695025 Set the user's default identity:: - $ ndnsec-set-default /ndn/test/alice + $ ndnsec set-default /ndn/test/alice + +See Also +-------- + +:manpage:`ndnsec-get-default(1)`, +:manpage:`ndnsec-list(1)` diff --git a/docs/manpages/ndnsec-sign-req.rst b/docs/manpages/ndnsec-sign-req.rst index d17ff3cc7..c2a4b0336 100644 --- a/docs/manpages/ndnsec-sign-req.rst +++ b/docs/manpages/ndnsec-sign-req.rst @@ -4,20 +4,16 @@ ndnsec-sign-req Synopsis -------- -**ndnsec-sign-req** [**-h**] [**-k**] *name* +**ndnsec sign-req** [**-h**] [**-k**] *name* Description ----------- -:program:`ndnsec-sign-req` generates a signing request for a key. +Generate a signing request for a key and print it to the standard output in Base64 +encoding. Note that a signing request is essentially just a self-signed certificate. -The signing request of a key is actually a self-signed certificate. Given the -key's information, :program:`ndnsec-sign-req` looks up the key in the PIB. -If such a key exists, a self-signed certificate for the key, i.e. its signing -request, is written to the standard output in base64 encoding. - -By default, *name* is interpreted as an identity name, and the signing request -will be generated for that identity's default key. +By default, *name* is interpreted as an identity name, and the signing request is +generated for that identity's default key. Options ------- @@ -26,47 +22,35 @@ Options Interpret *name* as a key name, instead of an identity name. -Example -------- +Examples +-------- Create a signing request for an identity's default key:: - $ ndnsec-sign-req /ndn/test/david - Bv0DAAc9CANuZG4IBHRlc3QIBWRhdmlkCANLRVkIEWtzay0xMzk2OTk4Mzg5MjU3 - CAdJRC1DRVJUCAgAAAFFZ+ibohQDGAECFf0BeDCCAXQwIhgPMjAxNDA0MTYwMDIx - MDhaGA8yMDM0MDQxMTAwMjEwOFowKjAoBgNVBCkTIS9uZG4vdGVzdC9kYXZpZC9r - c2stMTM5Njk5ODM4OTI1NzCCASAwDQYJKoZIhvcNAQEBBQADggENADCCAQgCggEB - AKOhGgpUZXiUkaqgfcIvBKSw4wFcSMhBdXr45Tzh8hi8dv1plXKAV4YQLkjHhJqi - VTj8qGWkvaP0Kv/mkynaa2rPzUQ77wE1ydRIBUik62bXQa8SanJsV9ux99t9LBKq - MY4mtWgal48wFqwqRPNH4xq0yFACh28eaMCMpNvZd2Fh4gmDvQ5xU7sJTyRLt/Mc - mfYppDFGfzUP2nP8eQW5I9+L0DXMAAb4z8w1nXHs21xyPv0SSaJXgBH0ZdBwB++D - Eo5RLmcDdhFqN0f9Rlz06LVq+gLUC2M+N54jD5qUhPEdW5erY6pyYhq4Zv2B4lbK - Zgf2FWIB2iw0of4snf2SxDcCAREWOhsBARw1BzMIA25kbggEdGVzdAgFZGF2aWQI - A0tFWQgRa3NrLTEzOTY5OTgzODkyNTcIB0lELUNFUlQX/QEABe8tCY99uFTPyiNX - u/hUY96FGnfQx4usA2rCd+M4bkvsAwKQVlbBx1sDXsakvoHhLaCi+MTwHw17o+oG - mtPqklLjM8XS+gF+Lh+OyivJQixb8KR8tAtlGeLDoLU/kpgYv/xVhp8Q5ma0/T47 - faI4Sn6bQP7YoWj+BdO3oZYthtq3MZPw2hl7wuTRMHNm5i3efnZyZdoPNMR2K43x - gH6ew1JbEQG7G6l5Q/jjnfT/oTtUeQzqWf2SSylAX+9xFZ9KG4+S6K7mYieBoqiA - 0wHjvDS1cuIH2j6XveoUYapRjZXaEZqB/YoBwRqEYq2KVn/ol5knLM6FIISXXjxn - cIh62A== + $ ndnsec sign-req /ndn/test/david + Bv0BUAc5CANuZG4IBHRlc3QIBWRhdmlkCANLRVkICLe4LjaLILlwCAxjZXJ0LXJl + cXVlc3Q2CAAAAZBBKKWTFAkYAQIZBAA27oAVWzBZMBMGByqGSM49AgEGCCqGSM49 + AwEHA0IABJxGmknWpDMKlPKO+xffd9b39bGilN2gTB8xkQ04L3rRgHuD8syFbHXT + Czht6djEg7YQuKtbQ1npa7lVS7N/KN8WYhsBAxwzBzEIA25kbggEdGVzdAgFZGF2 + aWQIA0tFWQgIt7guNosguXAIBHNlbGY2CAAAAZBBJUwR/QD9Jv0A/g8yMDI0MDYy + MlQxODE1MDH9AP8PMjAyNDA3MDJUMTgxNTAxF0cwRQIgGewzD5ZXsu49hnB/pJ+V + RR8JJZf9v29T/cqoEpYbf7sCIQCMySY9yqs2NybIQMVJQsJceEbOFPSjWIc9bwye + 7Ecuyw== Create a signing request for a particular key:: - $ ndnsec-sign-req -k /ndn/test/david/ksk-1396913058196 - Bv0DAAc9CANuZG4IBHRlc3QIBWRhdmlkCANLRVkIEWtzay0xMzk2OTEzMDU4MTk2 - CAdJRC1DRVJUCAgAAAFFZ+mbhRQDGAECFf0BeDCCAXQwIhgPMjAxNDA0MTYwMDIy - MTRaGA8yMDM0MDQxMTAwMjIxNFowKjAoBgNVBCkTIS9uZG4vdGVzdC9kYXZpZC9r - c2stMTM5NjkxMzA1ODE5NjCCASAwDQYJKoZIhvcNAQEBBQADggENADCCAQgCggEB - ALS6udLacpydecxMRIfZeo74fxzpsITqaa/4UxD2FJ9lU4dtfiSSIOaRwAB/w0K/ - AauQRq3Q1AiEocUsW2h8LmtcuF4Cj9TGAUD/1s3CISMwf9zwQ3ZhNIzN0IOsrpPA - TsHrbdwtOxrcFvXX4GnMLWgtvcSB52Cn68h/4AUiA1CG9/DOyCyA4EHiIkHBxh6B - TvAmw7SmNjr1ZBTYMaMAEV5/oLZCHzHRO+2fKdEttaWH3bz7iKVVS8u5ZxXcBs8g - ot55m7Xf6/TUk3qQXM1kM8wW04U+8n3jch1i7tD2T3c/OFKTT7AWndwcfbU99Z6C - FZ7fMsgRHxFNY8hCFZJvFFUCAREWOhsBARw1BzMIA25kbggEdGVzdAgFZGF2aWQI - A0tFWQgRa3NrLTEzOTY5MTMwNTgxOTYIB0lELUNFUlQX/QEAkA2DjqDq8pcAD579 - PaGz3sybCMo2zyjAJvLCRRDPrjQfkublIvN3wGykfsYRKTPW/aDlZcgOtqn8+Qdo - tpL9PixqB7hPAZzelADB7Rrqw41p5VNJTzBuIzC6bCssMa8xb2VTGkw1oEtWb1vl - Dn+WWvmTNE/yTnSTjNXnTdLinBSA1HH4edkjvH9hTn5+DVyZlpZrTX2qRYcNZqdC - kgESIroeoFnp95NVmO+jtL/pKaJ53jh7pvpv7y8wOu28Qk6HuhwDUR186Y/TNNt4 - hIc0NNDfvvyGgbDEGCMJ7/qOSt0qpJ2BxvPCb9S/bQD1odjGfP2F4ZA2S/JN2SYm - 5gldDQ== + $ ndnsec sign-req -k /ndn/test/david/KEY/%BDA%0F%EE%F55%D8%F4 + Bv0BUQc5CANuZG4IBHRlc3QIBWRhdmlkCANLRVkICL1BD+71Ndj0CAxjZXJ0LXJl + cXVlc3Q2CAAAAZBBLUzJFAkYAQIZBAA27oAVWzBZMBMGByqGSM49AgEGCCqGSM49 + AwEHA0IABO99nylhohJt0WnKNiVj6G1XNYxEgM7ESNXcpwgWB7gyeNywzG5JMfDs + GBlPZ4C4kshOzzw8uu4qmwexNUROWBgWYhsBAxwzBzEIA25kbggEdGVzdAgFZGF2 + aWQIA0tFWQgIvUEP7vU12PQIBHNlbGY2CAAAAZBBLCFq/QD9Jv0A/g8yMDI0MDYy + MlQxODIwMDb9AP8PMjAyNDA3MDJUMTgyMDA2F0gwRgIhANjJjB3OkFY1idr83rgc + jqusnrWe9kFs4Fai/GmteqDlAiEA3z0LYmLG0+k0Q1jLNzrZwKuVk+MUxtChXTUg + NKXukzg= + +See Also +-------- + +:manpage:`ndnsec-cert-gen(1)`, +:manpage:`ndnsec-key-gen(1)` diff --git a/docs/manpages/ndnsec-unlock-tpm.rst b/docs/manpages/ndnsec-unlock-tpm.rst index f5a8d9281..5e1810887 100644 --- a/docs/manpages/ndnsec-unlock-tpm.rst +++ b/docs/manpages/ndnsec-unlock-tpm.rst @@ -4,10 +4,10 @@ ndnsec-unlock-tpm Synopsis -------- -ndnsec-unlock-tpm [**-h**] +**ndnsec unlock-tpm** [**-h**] Description ----------- -:program:`ndnsec-unlock-tpm` can be used to (temporarily) unlock the -**Trusted Platform Module (TPM)** that manages private keys. +This command can be used to (temporarily) unlock the local +**Trusted Platform Module (TPM)** that manages the private keys. diff --git a/docs/manpages/ndnsec.rst b/docs/manpages/ndnsec.rst index d65c3a719..edf948afc 100644 --- a/docs/manpages/ndnsec.rst +++ b/docs/manpages/ndnsec.rst @@ -1,9 +1,6 @@ ndnsec ====== -:program:`ndnsec` is a command-line toolkit to perform various NDN security -management operations. - Synopsis -------- @@ -14,6 +11,9 @@ Synopsis Description ----------- +:program:`ndnsec` is a command-line toolkit to perform various NDN security +management operations. + The NDN security data are stored in two places: **Public Information Base** (PIB) and **Trusted Platform Module** (TPM). The :program:`ndnsec` toolkit provides a command-line interface for managing and using the NDN security data. @@ -58,3 +58,12 @@ The following commands are understood: :doc:`unlock-tpm ` Unlock the TPM. + +Exit Status +----------- + +Generally, :program:`ndnsec` commands exit with status 0 if the requested +operation was completed successfully. On error, a nonzero status is returned. +Individual commands may use certain nonzero exit codes to indicate that a +more specific error has occurred. Please consult the respective man pages +for more information.