README.md
1# PKCS#11 [![Build Status](https://travis-ci.org/miekg/pkcs11.png?branch=master)](https://travis-ci.org/miekg/pkcs11) [![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](http://godoc.org/github.com/miekg/pkcs11)
2
3This is a Go implementation of the PKCS#11 API. It wraps the library closely, but uses Go idiom
4were it makes sense. It has been tested with SoftHSM.
5
6## SoftHSM
7
8* Make it use a custom configuration file `export SOFTHSM_CONF=$PWD/softhsm.conf`
9
10* Then use `softhsm` to init it
11
12 softhsm --init-token --slot 0 --label test --pin 1234
13
14* Then use `libsofthsm.so` as the pkcs11 module:
15```go
16 p := pkcs11.New("/usr/lib/softhsm/libsofthsm.so")
17```
18## Examples
19
20A skeleton program would look somewhat like this (yes, pkcs#11 is verbose):
21```go
22 p := pkcs11.New("/usr/lib/softhsm/libsofthsm.so")
23 err := p.Initialize()
24 if err != nil {
25 panic(err)
26 }
27
28 defer p.Destroy()
29 defer p.Finalize()
30
31 slots, err := p.GetSlotList(true)
32 if err != nil {
33 panic(err)
34 }
35
36 session, err := p.OpenSession(slots[0], pkcs11.CKF_SERIAL_SESSION|pkcs11.CKF_RW_SESSION)
37 if err != nil {
38 panic(err)
39 }
40 defer p.CloseSession(session)
41
42 err = p.Login(session, pkcs11.CKU_USER, "1234")
43 if err != nil {
44 panic(err)
45 }
46 defer p.Logout(session)
47
48 p.DigestInit(session, []*pkcs11.Mechanism{pkcs11.NewMechanism(pkcs11.CKM_SHA_1, nil)})
49 hash, err := p.Digest(session, []byte("this is a string"))
50 if err != nil {
51 panic(err)
52 }
53
54 for _, d := range hash {
55 fmt.Printf("%x", d)
56 }
57 fmt.Println()
58```
59Further examples are included in the tests.
60
61To expose PKCS#11 keys using the
62[crypto.Signer interface](https://golang.org/pkg/crypto/#Signer),
63please see [github.com/thalesignite/crypto11](https://github.com/thalesignite/crypto11).
64
65# TODO
66
67* Fix/double check endian stuff, see types.go NewAttribute()
68* Look at the memory copying in fast functions (sign, hash etc)
69