Merge pull request #36 from mheese/cargo-toml-and-others

Cargo.toml, READMEs and others

Cargo.toml

@@ -19,14 +19,21 @@ description = "Rust PKCS#11 Library"
 #documentation = "https://github.com/mheese/rust-pkcs11"
 homepage = "https://github.com/mheese/rust-pkcs11"
 repository = "https://github.com/mheese/rust-pkcs11"
-#readme = "..."
+readme = "README.md"
 keywords = ["pkcs11", "cryptoki"]
 categories = ["external-ffi-bindings", "cryptography", "hardware-support"]
 license = "Apache-2.0"
+license-file = "LICENSE"
 exclude = [
     "pkcs11-docs/**",
 ]
 
+[badges]
+maintenance = { status = "actively-developed" }
+codecov = { repository = "mheese/rust-pkcs11", branch = "master", service = "github" }
+is-it-maintained-issue-resolution = { repository = "mheese/rust-pkcs11" }
+is-it-maintained-open-issues = { repository = "mheese/rust-pkcs11" }
+
 [dependencies]
 libloading = "^0.5"
 num-bigint = "^0.2"

README.md

@@ -16,18 +16,60 @@ limitations under the License.
 
 # Rust PKCS#11 Library
 
+[![Latest version](https://img.shields.io/crates/v/pkcs11.svg)](https://crates.io/crates/pkcs11)
+[![Documentation](https://docs.rs/pkcs11/badge.svg)](https://docs.rs/pkcs11)
 ![Build status](https://github.com/mheese/rust-pkcs11/workflows/Linux/badge.svg)
 ![Build status](https://github.com/mheese/rust-pkcs11/workflows/macOS/badge.svg)
 ![Build status](https://github.com/mheese/rust-pkcs11/workflows/Windows/badge.svg)
+![Build status](https://github.com/mheese/rust-pkcs11/workflows/Audit/badge.svg)
 [![codecov](https://codecov.io/gh/mheese/rust-pkcs11/branch/master/graph/badge.svg)](https://codecov.io/gh/mheese/rust-pkcs11)
+![License](https://img.shields.io/crates/l/pkcs11.svg)
 
 This is a library which brings support for PKCS#11 to Rust. It is aiming at having both a very low-level API to map the PKCS#11 functionality to Rust as well as having a higher-level API for more easy usage as well as bringing more safety for programming against PKCS#11.
 
+## Status
+
+The library has full support for all functions in PKCS#11 v2.40.
+It should technically work with any Cryptoki version from v2.00.
+For example there is special handling for `C_WaitForSlotEvent` which has been added only in v2.01.
+You can successfully implement and reach all low-level Cryptoki semantics and structures.
+All of them are integration tested using SoftHSM.
+For better interoperability the low-level API is using nearly the same function/method calls and data structures as defined in the official standard.
+That means that using the low-level API should be very easy for people who are familiar with PKCS#11 as the naming and variables/constants/defines are the same.
+
+A high-level more Rust-friendly API is in the design process.
+Its goal is to hide most of the low-level PKCS#11 semantics that one does not need to be aware of as they can be very verbose.
+Furthermore using Rust datastructures it is possible to come up with a more type-safe library at compile time to help users to use PKCS#11 more successfully and to make it more robust.
+It will also provide easier primitives for multi-part encrypting/decrypting/signing/etc.
+Ideally by providing a streaming API.
+Last but not least it will provide session management and lock/unlock free sessions as they are available from the context.
+Especially on tokens that provide parallel processing this can be a very tedious and error-prone process.
+
+## Compatiblity Matrix
+
+**TODO:** This is still in the making, and most likely very incomplete.
+
+As PKCS#11 implementations are not always sticking to the standard, your token might still have problems, unfortunately.
+These are known tokens as reported by users that definitely work together with this library.
+
+- [SoftHSM version 2](https://github.com/opendnssec/SoftHSMv2) (duh, who would have thought)
+- [Nitrokey HSM 2](https://www.nitrokey.com)
+- [CardConnect SmartCard-HSM](https://www.smartcard-hsm.com/)
+- Safenet iKey 2032
+- and probably a lot more...
+
+If you use this library with an HSM that is not listed here, please open an issue (or even better a PR) so that I can update this matrix.
+If your token does not work, please also open an issue, of course, so that we can investigate.
+
 ## Testing
 
-Testing is currently done with [SoftHSM2](https://github.com/opendnssec/SoftHSMv2 "SoftHSM2 Repo"). A trillion thanks to the people at OpenDNSSEC for writing SoftHSM. This makes it possible to develop applications that need to support PKCS#11. I would have no idea what to do without it. (Suggestions are always welcome.)
+Testing is currently done with [SoftHSM2](https://github.com/opendnssec/SoftHSMv2 "SoftHSM2 Repo").
+A trillion thanks to the people at OpenDNSSEC for writing SoftHSM.
+This makes it possible to develop applications that need to support PKCS#11.
+I would have no idea what to do without it.
+(Suggestions are always welcome.)
 
-### Status
+## TODO
 
 Here is a list of the implementation status and plans on what to do next:
 
@@ -52,3 +94,4 @@ Here is a list of the implementation status and plans on what to do next:
 - [ ] Write and Generate Documentation for Rust docs
 - [ ] Better Testing (lots of repetitive code + we need a testing framework and different SoftHSM versions for different platforms)
 - [ ] Suppport for PKCS#11 v3.00
+- [ ] make packed struct and CK_ULONG / CK_LONG feature flags with platform defaults when it becomes possible - currently the default when the target is Windows as PKCS#11 explicitly demands packed structs on Windows and `unsigned long` and `long` are both only 32bit on Microsoft compilers by default. However, on any other unix platform the defaults are not really defined and one might need to opt in for one or the other.

pkcs11-docs/README.md

@@ -18,6 +18,13 @@ limitations under the License.
 
 The purpose of this section is to provide all possible available documentation that makes programming against PKCS#11 easier.
 
+## Collection of all PKCS#11 standards
+
+I ran across this only recently (April 2020).
+It is an invaluable collection of all PKCS#11 standards including all their C header files: <https://github.com/mheese/PKCS11-SPECS>
+
+Special thanks to the guys from [Pkcs11Interop](https://pkcs11interop.net/) to provide this collection.
+
 ## Reference Documentation
 
 When one first starts to explore the PKCS#11 world, there will be obstacles. The biggest one is to know and discover what documentation to read so that one can get familiar with the standard. It is best to read up on it in the following order:
@@ -26,17 +33,9 @@ When one first starts to explore the PKCS#11 world, there will be obstacles. The
 2. [Base Specification](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html "PKCS#11 v2.40 Base Specification") - This is the most important document for implementation of this library - in particular for the low-level API. It explains in detail how the C interface is structured and how to interact with it. Following this will provide all the details on how to write the FFI wrapper.
 3. [Current Mechanisms](http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/pkcs11-curr-v2.40.html "PKCS#11 v2.40 Current Mechanisms") - This document is in particular important for our higher-leval API. It explains in detail on how to interface in detail with all the cryptographic algorithms. E.g. go here if you need help on how to generate and use an RSA key or how to use the token for digital signatures.
 
-Here are the links to the documents that are also saved for reference in this repository (in case they become unavailable at some time):
-
-- <http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html>
-- <http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html>
-- <http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/pkcs11-curr-v2.40.html>
-
 ## C Header Files
 
-The C header files in this folder have been downloaded from the following links below.
-
-Normative computer language definition files for PKCS #11 v2.40:
+The C header files for PKCS #11 v2.40 can be found at this location:
 
 - <http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/include/pkcs11-v2.40/pkcs11.h>
 - <http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/include/pkcs11-v2.40/pkcs11t.h>