Examples are lacking leading to use confusion.

[Firstyear]

Problem Description

Because of the design of the pkcs11-tool cli, it is often unclear how various options and parts fit together. An example is that from reading the --help or the man page, there is no obvious or clear method to create an extractable key, and then to wrap it and unwrap it in a seperate card/hsm.

Proposed Resolution

As the cli structure is unlikely to change, this means that for features worked functional examples are critical, and the current man page is lacking in these.

Examples that should be added include:

• Creating new keys on a card with keypairgen
• Creating new keys that are extractable (with a wrap key)
• Wrapping and unwrapping keys
• listing and showing object uris
• Probably more that I need to think of

Alternately when a "verb" flag is passed, then the --help should be limited to the relevant options that apply. For example, --unwrap is nonsensical with --keypairgen, so when a --keypairgen is passed to the tool only options that apply to keypairgen should be shown.

Steps to reproduce

1. Be a new pkcs11 user
2. Google for hours how to do things
3. Read the man page
4. Walk away confused Add (fix) support for eGK v 2.1 #2871

Desired outcome

Improvement to documentation to make this tool more accessible to enable people to use pkcs11 more readily.

[frankmorgner]

Improvement to documentation to make this tool more accessible to enable people to use pkcs11 more readily.

Your contributions are happily welcome. Currently, documentation of this kind is driven by special interests - please consult the wiki pages regarding your token type whether this is covered. If it is not, first get in touch with the token creator how to do this. If this doesn't give any feedback, you can open a more specific issue here.

[frankmorgner]

Btw, the primary focus of OpenSC to make tokens work in a PKCS#11 module via end user applications (e.g. Browser, VPN, E-Mail). The targeted audience of pkcs11-tool is professionals rather than end users, so please don't expect end user documentation for pkcs11-tool.

[Firstyear]

Improvement to documentation to make this tool more accessible to enable people to use pkcs11 more readily.

Your contributions are happily welcome. Currently, documentation of this kind is driven by special interests - please consult the wiki pages regarding your token type whether this is covered. If it is not, first get in touch with the token creator how to do this. If this doesn't give any feedback, you can open a more specific issue here.

And how am I meant to contribute improvements to the examples, If I can't work out how to use the tool in the first place? 🤔

I can't document something that I can't work out ....

I am aware of the audience of pkcs11-tool being professionals and administrators, but even with nearly a decade of sysadmin experience the current man page is dense and hard to use at best.

For example, if I wanted to wrap a key to move to another token, there is no clear way to do this because the --wrap option doesn't show you what other options are needed to work with it.

[popovec]

I just added some examples to the pkcs11-tool manual page, they are available in PR #2936. Try to look in the OpenSC source code, there are integration tests that test wrap/unwrap (tests/test-pkcs11-tool-unwrap-wrap-test.sh).

[Firstyear]

Thank you! I'll have a look!

[frankmorgner]

Maybe we can also move some of the examples from https://github.com/OpenSC/OpenSC/tree/master/tests into the manual pages with some explanatory text