PKCS #11 Version 3.2 Support

[FAlbertDev]

This PR brings an experimental integration of PKCS #11 v3.2 (draft 06) into Botan's low-level PKCS 11 wrapper.

Key Changes v2.40 → v3.2

Compared to the currently supported PKCS 11 v2.40, here are the key changes:

• Interfaces: To maintain backward compatibility and support vendor-defined extensions, v3.0 introduced the concept of interfaces. These interfaces have a name, configuration flags, and a pointer to a FunctionList struct, which contains pointers to the loaded p11 library's functions. By calling C_GetInterfaceList, we can get a list of all available interfaces. If the loaded p11 library only supports v3.0, we won't get an interface for v3.2 functions, but we can still use the v3.0 functions without backpatching the pkcs11 headers in Botan.

  The new Botan implementation automatically looks for the latest/best available interface and loads it. If you call functions not supported by the latest interface, we throw an exception.

• New Functions: Beside many others features, v3.2 adds functions for key encapsulation and decapsulation. It also extends constants to support new FIPS 20X PQC algorithms. I've added many of these new constants to the existing enums. However, I haven't created enums for every new algorithm yet. These can be added if needed.

Vendor-Defined Methods Support

Regarding vendor-defined methods: I've made Botan's handling of the InterfaceWrapper and LowLevel class extendable. This allows applications to create subclasses of these classes and add their own vendor-defined function lists and methods. Extending PKCS11::Modules isn't supported yet. I didn't want to invest too much time and code into a feature that might not be needed.

Other Improvements

Besides these new features, I've also improved the existing implementation in a few ways:

• Constant Correctness: PKCS 11 doesn't know about constant types. Until now, applications had to const_cast all const pointers to non-constants, even if the standard specifies their content isn't modified. I've changed this so that the interface of LowLevel is const correct, and the const_cast is done in the wrapper functions behind the scene.
• Improved Error Display: I've added information to the PKCS11_ReturnError exception output string, so it now briefly describes the error instead of just the error code number.

Tests

The existing tests with SoftHSM still pass, and I'm not sure if there's more room for other tests. SoftHSM only supports v2.40, and I don't see the need to test the new LowLevel functions, which are just wrappers. I wrote one test for getting the latest interface, which I ran with SoftHSM (returns v2.4 interface) and an experimental v3.2 library (returns the v3.2 interface).

Review

Here's what you need to know to review my changes without wasting time:

• The changes in pkcs11.h, pkcs11f.h, and pkcs11t.h are straight from the official PKCS 11 v3.2 draft 06 headers. No need to review these.
• The documentation for the wrapper functions is copy-pasted from the draft documentation. The parameter description comes from the p11 headers. I didn't tweak anything there.
• I'm really looking for feedback on how I implemented the handling of interfaces. I tried a few other approaches with inheritance, etc., but this one seemed the most straightforward. If you have a better idea, I'm all ears.
• Happy reviewing! 😉

Status of this PR

Since PKCS 11 v3.2 is still a draft and likely to change, we shouldn't merge this PR until the final version is out. I'll keep it as a draft PR until then.

[coveralls]

coverage: 90.363% (-0.3%) from 90.668% when pulling b4994b5c00d6b9e49e431166d511847086d69259 on Rohde-Schwarz:feature/pkcs11v32 into 0d4cd13de1a5977da0df3911fb93cfd443732b69 on randombit:master.

[randombit]

Would it be worth updating to 3.1 now, and then doing a 3.2 update when that's released? I'm not sure what timeline this process is on but it's been six months since draft6 came out and no draft7 that I can find.

[FAlbertDev]

To be honest, my main interest in this PR is the draft's PQC support. Splitting the PR into a 3.1 part and a 3.2 draft part would be possible but somewhat fiddly. I would like to avoid this work if no one is keen on 3.1 without PQC.

[FAlbertDev]

Rebased to master. I'll update this MR for the most recent PKCS 11 v3.2 draft in the coming week(s).

[FAlbertDev]

Thanks for your review!

@randombit As stated in the (edited) PR description above, I think we may integrate this PKCS 11 v3.2 update into master, even if the official version is not yet published. What do you think?

I'm quite positive that there will be no changes between the current PKCS 11 v3.2 draft 13 and the final official version that affect the pkcs11 header file. As far as I know, only editorial changes in the specification document are still planned. Therefore, I suggest we merge this PR and hope for the best. Also, even if the header needs to be changed, no one should wish for compatibility with the draft version.

[boricm]

@FAlbertDev and @randombit, I don't know how Botan usually handles this, but maybe you could include the draft 13 string somewhere? Just to be prepared in case this needs to be distinguishable from a possibly different final version. Once it is clear, that there are no changes, this string can be removed.

[FAlbertDev]

I don't know how Botan usually handles this, but maybe you could include the draft 13 string somewhere? Just to be prepared in case this needs to be distinguishable from a possibly different final version. Once it is clear, that there are no changes, this string can be removed.

Good point! I'll reference it in the documentation and maybe the p11.h and pkcs11.h headers. Hopefully we don't forget to remove it after the official standard is published 😉

[FAlbertDev]

This MR is ready for review.