pkcs11mod allows you to create PKCS#11 modules in Go. You implement your PKCS#11 functions by providing a struct that implements the same API as pkcs11.Ctx
from Miek Gieben's pkcs11 package; pkcs11mod takes care of exposing this as a C ABI library.
Prerequisites:
- Ensure you have the Go tools installed.
Option A: Using Go build commands without Go modules (works on any platform with Bash; will not work on Go 1.17+):
-
Ensure you have the GOPATH environment variable set. (For those not familar with Go, setting it to the path to an empty directory will suffice. The directory will be filled with build files.)
-
Run
export GO111MODULE=off
to disable Go modules. -
Run
go get -d -t -u github.com/namecoin/pkcs11mod
. The pkcs11mod source code will be retrieved automatically. -
Run
go generate github.com/namecoin/pkcs11mod
. Some source code will be generated. -
Run
go get -t -u github.com/namecoin/pkcs11mod
. pkcs11mod will build. -
You can now
import "github.com/namecoin/pkcs11mod"
from your Go PKCS#11 module.
Option B: Using Go build commands with Go modules (works on any platform with Bash):
-
Run the following in the
pkcs11mod
directory to set up Go modules:go mod init github.com/namecoin/pkcs11mod go mod tidy go generate ./... go mod tidy
-
Place your Go PKCS#11 module's directory as a sibling of the
pkcs11mod
directory. -
Run the following in your Go PKCS#11 module's directory:
go mod edit -replace github.com/namecoin/pkcs11mod=../pkcs11mod go mod tidy
-
You can now
import "github.com/namecoin/pkcs11mod"
from your Go PKCS#11 module.
See the pkcs11proxy
subdirectory for an example of how to use pkcs11mod. Also consider using the higher-level p11mod library instead of using pkcs11mod directly (see this section).
Set the environment variable PKCS11MOD_TRACE=1
to enable debug tracing. To include sensitive data that might be a privacy leak, also set PKCS11MOD_TRACE_SENSITIVE=1
. The trace will be outputted to the log file.
PKCS#11 is a plugin specification frequently used with smartcards and certificate databases. You may find the following links informative:
- Specification
- Wikipedia article
- Sharing Trust Policy (p11-glue)
- Grayhat 2020 presentation (Namecoin)
Miek Gieben's pkcs11 and p11 packages are for implementing applications that open PKCS#11 modules (e.g. you'd use pkcs11 or p11 if you're creating a web browser that will open a certificate database); pkcs11mod and p11mod are for implementing PKCS#11 modules that are opened by an application (e.g. you'd use pkcs11mod or p11mod if you're creating a certificate database that will be opened by a web browser).
p11mod is much easier to use and more idiomatic to Go. However, p11mod implements less of the PKCS#11 specification than pkcs11mod. If you only need functionality that p11mod has, you will probably find p11mod more pleasant to work with. On the other hand, p11mod is much newer and less battle-tested, so you may find pkcs11mod more reliable.
pkcs11mod is primarily motivated by the use cases that Namecoin has; as such, the PKCS#11 features we've implemented so far are mostly the features used by applications such as NSS's certificate verifier and PKCS#11 modules such as NSS's CKBI (built-in certificates). We don't have any objection to implementing the rest of the PKCS#11 spec (and we'd happily accept pull requests to this end), but it's unlikely that we'll spend much of our free time on features that aren't relevant to Namecoin.
While we do plan to use pkcs11mod in production in the future, it is not yet used in production, and any horrifying bugs in pkcs11mod probably haven't been noticed by us yet.
Copyright (C) 2018-2022 Namecoin Developers
pkcs11mod is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
pkcs11mod is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with pkcs11mod; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
pkcs11mod is based on:
- https://github.com/miekg/pkcs11
- BSD 3-Clause License
- https://github.com/Pkcs11Interop/pkcs11-mock
- Apache 2.0 License
- https://github.com/pipelined/vst2
- MIT License