libp11/p11-kit confusion in openssl_engine.adoc

[dextercd]

Hey team,

The doc/YKCS11/Supported_applications/openssl_engine.adoc file has some issues.

It mentions pll-kit which doesn't exist. It's supposed to be p11-kit with 1's instead of l's.

But, then the documentation still isn't correct, since it demonstrates how to use libp11 without going through the p11-kit proxy module.

Just to be clear, libp11 is a PKCS#11 wrapper library which also provides an OpenSSL engine module allowing OpenSSL to interface with PKCS#11. (In this case to perform crypto operations on a Yubikey via your libykcs11.so module.)

p11-kit is a different project to make the various PKCS#11 modules someone might have on their system discoverable. It also has a p11-kit-proxy PKCS#11 module that can then internally forward calls into multiple p11-kit discovery enabled PKCS#11 modules, including to libykcs11.so if it's configured to do so. This component can be used by libp11, but that's not what's happening in the documentation you provide, since setting PKCS11_MODULE_PATH tells libp11 to not look for the proxy module but instead just use the module assigned to the env var.

Source (DEFAULT_PKCS11_MODULE is set to /usr/lib/p11-kit-proxy.so normally). Additional confirmation inside this comment: OpenSC/libp11#437 (comment).

---

I think there are two ways to fix the docs:

1. Remove reference to the p11-kit proxy module and perhaps mention the libp11 project instead.
2. Use the p11-kit proxy module by leaving PKCS11_MODULE_PATH unset and add instructions on how to make libykcs11.so discoverable to p11-kit.

I ended up going with the second approach for my Yubikey by creating a /etc/pkcs11/modules/yubikey.module file with this contents:

module: /usr/lib/libykcs11.so
trust-policy: no

---

How the OpenSSL, libp11, p11-kit-proxy, and libykcs11 components all fit together is confusing, especially with the libp11 and p11-kit project names being so similar. This documentation might've added to my and other people's confusion while they're trying to get a better understanding.

It would be nice if the mistake in the docs can be fixed. Perhaps it can even be changed to help explain how these components integrate with each other.