From 2fd9f1526fd6b161b3ecd4db248fc14705ca5960 Mon Sep 17 00:00:00 2001 From: Daiki Ueno Date: Sat, 30 Dec 2023 07:38:21 +0900 Subject: [PATCH] doc: Make option requirement clear for p11-kit subcommands Signed-off-by: Daiki Ueno --- doc/manual/p11-kit.xml | 114 ++++++++++++++++++++++++++++++++++------- 1 file changed, 96 insertions(+), 18 deletions(-) diff --git a/doc/manual/p11-kit.xml b/doc/manual/p11-kit.xml index bb003f46..9e452c3e 100644 --- a/doc/manual/p11-kit.xml +++ b/doc/manual/p11-kit.xml @@ -117,13 +117,20 @@ $ p11-kit list-modules List all tokens available in system configured PKCS#11 modules. -$ p11-kit list-tokens [--only-uris] pkcs11:token +$ p11-kit list-tokens pkcs11:token This retrieves all tokens and displays some of their - common attributes. If is given, - only the matching token URIs are printed. + common attributes. + This subcommand takes the following options: + + + + + Print only the matching token URIs. + + @@ -132,13 +139,21 @@ $ p11-kit list-tokens [--only-uris] pkcs11:token List objects matching given PKCS#11 URI. -$ p11-kit list-objects [--login] pkcs11:object_on_token +$ p11-kit list-objects pkcs11:object_on_token This retrieves all objects that match given PKCS#11 URI and displays some of their common attributes. Storage objects also have their PKCS#11 URI displayed. + This subcommand takes the following options: + + + + + Authenticate to the token before enumerating objects. The PIN value is read from either the pin-value attribute in the URI or from the terminal. + + @@ -147,24 +162,34 @@ $ p11-kit list-objects [--login] pkcs11:object_on_token Import object into PKCS#11 token. -$ p11-kit import-object --file=file.pem [--label=label] [--login] pkcs11:token +$ p11-kit import-object --file=file.pem [--label=label] pkcs11:token Takes either an X.509 certificate or a public key in the form of a PEM file and imports it into the first token matched by given PKCS#11 URI. + The following options are required: + File containing either an X.509 certificate - or a public key in PEM format. This option is required. + or a public key in PEM format. + + + This subcommand also accepts the following options: + + Assigns label to the imported object. + + + Authenticate to the token before enumerating objects. The PIN value is read from either the pin-value attribute in the URI or from the terminal. + - @@ -173,12 +198,20 @@ $ p11-kit import-object --file=file.pem [--label=label] [--login& Export object matching PKCS#11 URI. -$ p11-kit export-object [--login] pkcs11:object_on_token +$ p11-kit export-object pkcs11:object_on_token Displays PEM formatted contents of the first object matched by given PKCS#11 URI. The matched object has to either be an X.509 certificate or a public key. + This subcommand takes the following options: + + + + + Authenticate to the token before enumerating objects. The PIN value is read from either the pin-value attribute in the URI or from the terminal. + + @@ -187,11 +220,19 @@ $ p11-kit export-object [--login] pkcs11:object_on_token Delete object matching PKCS#11 URI. -$ p11-kit delete-object [--login] pkcs11:object_on_token +$ p11-kit delete-object pkcs11:object_on_token Destroys the first object matched by given PKCS#11 URI. + This subcommand takes the following options: + + + + + Authenticate to the token before enumerating objects. The PIN value is read from either the pin-value attribute in the URI or from the terminal. + + @@ -200,19 +241,20 @@ $ p11-kit delete-object [--login] pkcs11:object_on_token Generate key-pair on a PKCS#11 token. -$ p11-kit generate-keypair --type=algorithm {--bits=n|--curve=name} [--label=label] [--login] pkcs11:token +$ p11-kit generate-keypair --type=algorithm {--bits=n|--curve=name} [--label=label] pkcs11:token Generate private-public key-pair of given type on the first token matched by given PKCS#11 URI. This command should be used together with --type option and one of --bits or --curve options. + The following options are required: + Specify the type of keys to generate. - Supported values are rsa, ecdsa and ed25519. - This option is required. + Supported values are rsa, ecdsa and ed25519. @@ -225,12 +267,20 @@ $ p11-kit generate-keypair --type=algorithm {--bits=n|--curve=name} &l Supported values are secp256r1, secp384r1, secp521r1, ed25519 and ed448. Cannot be used together with --bits option. + + + This subcommand also accepts the following options: + + Assigns label to the generated key-pair objects. + + + Authenticate to the token before enumerating objects. The PIN value is read from either the pin-value attribute in the URI or from the terminal. + - @@ -239,12 +289,20 @@ $ p11-kit generate-keypair --type=algorithm {--bits=n|--curve=name} &l List PKCS#11 profiles supported by the token. -$ p11-kit list-profiles [--login] pkcs11:token +$ p11-kit list-profiles pkcs11:token Displays profile IDs of the first token matched by given PKCS#11 URI in human-readable form. + This subcommand takes the following options: + + + + + Authenticate to the token before enumerating objects. The PIN value is read from either the pin-value attribute in the URI or from the terminal. + + @@ -253,21 +311,31 @@ $ p11-kit list-profiles [--login] pkcs11:token Add PKCS#11 profile to a token. -$ p11-kit add-profile --profile=profile [--login] pkcs11:token +$ p11-kit add-profile --profile=profile pkcs11:token Creates new profile object with given profile ID on the first token matched by given PKCS#11 URI. This command fails if the profile ID already exists on the token. + The following options are required: + Profile ID to add. Value can either - be numerical or textual. This option is required. + be numerical or textual. + This subcommand also accepts the following options: + + + + + Authenticate to the token before enumerating objects. The PIN value is read from either the pin-value attribute in the URI or from the terminal. + + @@ -276,20 +344,30 @@ $ p11-kit add-profile --profile=profile [--login] pkcs11:token Delete PKCS#11 profile from a token. -$ p11-kit delete-profile --profile=profile [--login] pkcs11:token +$ p11-kit delete-profile --profile=profile pkcs11:token Destroys all profile objects with given profile ID from the first token matched by given PKCS#11 URI. + The following options are required: + Profile ID to delete. Value can either - be numerical or textual. This option is required. + be numerical or textual. + This subcommand also accepts the following options: + + + + + Authenticate to the token before enumerating objects. The PIN value is read from either the pin-value attribute in the URI or from the terminal. + +