Skip to content

Commit

Permalink
Revise documentation of the object and profile sub-commands
Browse files Browse the repository at this point in the history 
Signed-off-by: Zoltan Fridrich <[email protected]>
  • Loading branch information
@ZoltanFridrich
ZoltanFridrich committed Oct 25, 2023
1 parent bd75edd commit 96a8b14
Showing 1 changed file with 65 additions and 34 deletions.
99 changes: 65 additions & 34 deletions doc/manual/p11-kit.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,8 +117,7 @@ $ p11-kit list-modules
<para>List all tokens available in system configured PKCS#11 modules.</para>

<programlisting>
$ p11-kit list-tokens pkcs11:token
$ p11-kit list-tokens --only-uris pkcs11:token
$ p11-kit list-tokens &lsqb;--only-uris&rsqb; pkcs11:token
</programlisting>

<para>This retrieves all tokens and displays some of their
Expand All @@ -130,28 +129,41 @@ $ p11-kit list-tokens --only-uris pkcs11:token
<refsect1 id="p11-kit-list-objects">
<title>List Objects</title>

<para>List objects of a token.</para>
<para>List objects matching given PKCS#11 URI.</para>

<programlisting>
$ p11-kit list-objects pkcs11:token
$ p11-kit list-objects &lsqb;--login&rsqb; pkcs11:object_on_token
</programlisting>

<para>This retrieves all objects of the given token and displays
some of their common attributes.</para>
<para>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.</para>

</refsect1>

<refsect1 id="p11-kit-import-object">
<title>Import Object</title>

<para>Import object into a PKCS#11 token.</para>
<para>Import object into PKCS#11 token.</para>

<programlisting>
$ p11-kit import-object --file=file.pem &lsqb;--label=label&rsqb; &lsqb;--login&rsqb; pkcs11:token
</programlisting>

<para>This takes either a X.509 certificate or a public key in form of a PEM file
and imports it into PKCS#11 token that matches given URI.</para>
<para>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.</para>

<variablelist>
<varlistentry>
<term><option>--file=&lt;file.pem&gt;</option></term>
<listitem><para>File containing either an X.509 certificate
or a public key in PEM format. This option is required.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--label=&lt;label&gt;</option></term>
<listitem><para>Assigns label to the imported object.</para></listitem>
</varlistentry>
</variablelist>

</refsect1>

Expand All @@ -161,24 +173,24 @@ $ p11-kit import-object --file=file.pem &lsqb;--label=label&rsqb; &lsqb;--login&
<para>Export object matching PKCS#11 URI.</para>

<programlisting>
$ p11-kit export-object pkcs11:token
$ p11-kit export-object &lsqb;--login&rsqb; pkcs11:object_on_token
</programlisting>

<para>If a given URI references a storage object that is a X.509 certificate,
it displays the concents of the certificate in PEM format.</para>
<para>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.</para>

</refsect1>

<refsect1 id="p11-kit-delete-object">
<title>Delete Object</title>

<para>Delete objects matching PKCS#11 URI.</para>
<para>Delete object matching PKCS#11 URI.</para>

<programlisting>
$ p11-kit delete-object pkcs11:token
$ p11-kit delete-object &lsqb;--login&rsqb; pkcs11:object_on_token
</programlisting>

<para>This destroys every storage object matching given PKCS#11 URI.</para>
<para>Destroys the first object matched by given PKCS#11 URI.</para>

</refsect1>

Expand All @@ -188,21 +200,18 @@ $ p11-kit delete-object pkcs11:token
<para>Generate key-pair on a PKCS#11 token.</para>

<programlisting>
$ p11-kit generate-keypair &lsqb;--label=label&rsqb; --type=algorithm &lcub;--bits=n|--curve=name&rcub; pkcs11:token
$ p11-kit generate-keypair --type=algorithm &lcub;--bits=n|--curve=name&rcub; &lsqb;--label=label&rsqb; &lsqb;--login&rsqb; pkcs11:token
</programlisting>

<para>Generate private-public key-pair of given type on specified PKCS#11 token.
Should be used together with --type option and one of --bits or --curve options.</para>
<para>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.</para>

<variablelist>
<varlistentry>
<term><option>--label=&lt;label&gt;</option></term>
<listitem><para>Assigns label to the generated key-pair objects.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--type=&lt;algorithm&gt;</option></term>
<listitem><para>Specify the type of keys to generate.
Supported values are rsa, ecdsa, ed25519.
Supported values are rsa, ecdsa and ed25519.
This option is required.</para></listitem>
</varlistentry>
<varlistentry>
Expand All @@ -213,9 +222,13 @@ $ p11-kit generate-keypair &lsqb;--label=label&rsqb; --type=algorithm &lcub;--bi
<varlistentry>
<term><option>--curve=&lt;name&gt;</option></term>
<listitem><para>Specify an elliptic curve for the key-pair generation.
Supported values are secp256r1, secp384r1, secp521r1.
Supported values are secp256r1, secp384r1, secp521r1, ed25519 and ed448.
Cannot be used together with --bits option.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--label=&lt;label&gt;</option></term>
<listitem><para>Assigns label to the generated key-pair objects.</para></listitem>
</varlistentry>
</variablelist>

</refsect1>
Expand All @@ -226,38 +239,56 @@ $ p11-kit generate-keypair &lsqb;--label=label&rsqb; --type=algorithm &lcub;--bi
<para>List PKCS#11 profiles supported by the token.</para>

<programlisting>
$ p11-kit list-profiles pkcs11:token
$ p11-kit list-profiles &lsqb;--login&rsqb; pkcs11:token
</programlisting>

<para>This searches the given token for profile objects that contain profile IDs
which are then displayed in human-readable form.</para>
<para>Displays profile IDs of the first token matched by given
PKCS#11 URI in human-readable form.</para>

</refsect1>

<refsect1 id="p11-kit-add-profile">
<title>Add Profile</title>

<para>Add PKCS#11 profile to the token.</para>
<para>Add PKCS#11 profile to a token.</para>

<programlisting>
$ p11-kit add-profile --profile profile pkcs11:token
$ p11-kit add-profile --profile=profile &lsqb;--login&rsqb; pkcs11:token
</programlisting>

<para>Creates a new PKCS#11 profile object on the token if it doesn't already exist.</para>
<para>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.</para>

<variablelist>
<varlistentry>
<term><option>--profile=&lt;profile&gt;</option></term>
<listitem><para>Profile ID to add. Value can either
be numerical or textual. This option is required.</para></listitem>
</varlistentry>
</variablelist>

</refsect1>

<refsect1 id="p11-kit-delete-profile">
<title>Delete Profile</title>

<para>Delete PKCS#11 profile from the token.</para>
<para>Delete PKCS#11 profile from a token.</para>

<programlisting>
$ p11-kit delete-profile --profile profile pkcs11:token
$ p11-kit delete-profile --profile=profile &lsqb;--login&rsqb; pkcs11:token
</programlisting>

<para>Searches the token for profile object that matches given PKCS#11
profile ID and attempts to destroy it.</para>
<para>Destroys all profile objects with given profile ID from
the first token matched by given PKCS#11 URI.</para>

<variablelist>
<varlistentry>
<term><option>--profile=&lt;profile&gt;</option></term>
<listitem><para>Profile ID to delete. Value can either
be numerical or textual. This option is required.</para></listitem>
</varlistentry>
</variablelist>

</refsect1>

Expand Down

0 comments on commit 96a8b14

Please sign in to comment.