Documentation review

re #6

README.md

@@ -13,6 +13,7 @@ uses [PKCS#11](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/p
 * DSA signing.
 * Random number generation.
 * (Experimental) AES and DES3 encryption and decryption.
+* (Experimental) HMAC support.
 
 Signing is done through the
 [crypto.Signer](https://golang.org/pkg/crypto/#Signer) interface and
@@ -175,7 +176,7 @@ Copyright
 
 MIT License.
 
-Copyright 2016, 2017 Thales e-Security, Inc
+Copyright 2016-2018 Thales e-Security, Inc
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

aead.go

@@ -30,6 +30,14 @@ import (
 
 // cipher.AEAD ----------------------------------------------------------
 
+const (
+	// PaddingNone represents a block cipher with no padding. (See NewCBC.)
+	PaddingNone = iota
+
+	// PaddingPKCS represents a block cipher used with PKCS#7 padding. (See NewCBC.)
+	PaddingPKCS
+)
+
 type genericAead struct {
 	key *PKCS11SecretKey
 

block.go

@@ -35,6 +35,10 @@ func (key *PKCS11SecretKey) BlockSize() int {
 
 // Decrypt decrypts the first block in src into dst.
 // Dst and src must overlap entirely or not at all.
+//
+// Using this method for bulk operation is very inefficient, as it makes a round trip to the HSM
+// (which may be network-connected) for each block.
+// For more efficient operation, see NewCBCDecrypterCloser, NewCBCDecrypter or NewCBC.
 func (key *PKCS11SecretKey) Decrypt(dst, src []byte) {
 	var result []byte
 	if err := withSession(key.Slot, func(session *PKCS11Session) (err error) {
@@ -59,6 +63,10 @@ func (key *PKCS11SecretKey) Decrypt(dst, src []byte) {
 
 // Encrypt encrypts the first block in src into dst.
 // Dst and src must overlap entirely or not at all.
+//
+// Using this method for bulk operation is very inefficient, as it makes a round trip to the HSM
+// (which may be network-connected) for each block.
+// For more efficient operation, see NewCBCEncrypterCloser, NewCBCEncrypter or NewCBC.
 func (key *PKCS11SecretKey) Encrypt(dst, src []byte) {
 	var result []byte
 	if err := withSession(key.Slot, func(session *PKCS11Session) (err error) {

blockmode.go

@@ -30,28 +30,14 @@ import (
 	"runtime"
 )
 
-const (
-	// PaddingNone represents a block cipher with no padding.
-	PaddingNone = iota
-
-	// PaddingPKCS represents a block cipher used with PKCS#7 padding.
-	PaddingPKCS
-)
-
 // cipher.BlockMode -----------------------------------------------------
 
-// BlockModeCloser represents a block cipher running in a block-based mode (CBC, ECB etc).
+// BlockModeCloser represents a block cipher running in a block-based mode (e.g. CBC).
 //
-// BlockModeCloser implements cipher.BlockMode, and can be used as such.
+// BlockModeCloser embeds cipher.BlockMode, and can be used as such.
 // However, in this case
 // (or if the Close() method is not explicitly called for any other reason),
-// resources allocated to it may remain live longer than necessary.
-//
-// The underlying implementations set a finalizer
-// so these resources will eventually be released,
-// but if your application has resource consumption problems or hangs
-// then adding an explicit Close() call may be the solution.
-// If that is not possible then adding calls to runtime.GC() may help.
+// resources allocated to it may remain live indefinitely.
 type BlockModeCloser interface {
 	cipher.BlockMode
 
@@ -69,6 +55,8 @@ const (
 //
 // The new BlockMode acquires persistent resources which are released (eventually) by a finalizer.
 // If this is a problem for your application then use NewCBCEncrypterCloser instead.
+//
+// If that is not possible then adding calls to runtime.GC() may help.
 func (key *PKCS11SecretKey) NewCBCEncrypter(iv []byte) (bm cipher.BlockMode, err error) {
 	return key.newBlockModeCloser(key.Cipher.CBCMech, modeEncrypt, iv, true)
 }
@@ -78,18 +66,26 @@ func (key *PKCS11SecretKey) NewCBCEncrypter(iv []byte) (bm cipher.BlockMode, err
 //
 // The new BlockMode acquires persistent resources which are released (eventually) by a finalizer.
 // If this is a problem for your application then use NewCBCDecrypterCloser instead.
+//
+// If that is not possible then adding calls to runtime.GC() may help.
 func (key *PKCS11SecretKey) NewCBCDecrypter(iv []byte) (bm cipher.BlockMode, err error) {
 	return key.newBlockModeCloser(key.Cipher.CBCMech, modeDecrypt, iv, true)
 }
 
 // NewCBCEncrypterCloser returns a  BlockModeCloser which encrypts in cipher block chaining mode, using the given key.
 // The length of iv must be the same as the key's block size.
+//
+// Use of NewCBCEncrypterCloser rather than NewCBCEncrypter represents a commitment to call the Close() method
+// of the returned BlockModeCloser.
 func (key *PKCS11SecretKey) NewCBCEncrypterCloser(iv []byte) (bmc BlockModeCloser, err error) {
 	return key.newBlockModeCloser(key.Cipher.CBCMech, modeEncrypt, iv, false)
 }
 
 // NewCBCDecrypterCloser returns a  BlockModeCloser which decrypts in cipher block chaining mode, using the given key.
 // The length of iv must be the same as the key's block size and must match the iv used to encrypt the data.
+//
+// Use of NewCBCDecrypterCloser rather than NewCBCEncrypter represents a commitment to call the Close() method
+// of the returned BlockModeCloser.
 func (key *PKCS11SecretKey) NewCBCDecrypterCloser(iv []byte) (bmc BlockModeCloser, err error) {
 	return key.newBlockModeCloser(key.Cipher.CBCMech, modeDecrypt, iv, false)
 }

crypto11.go

@@ -70,6 +70,11 @@
 // and an error is returned if it is nonzero.
 // The reason for this is that it is not possible for crypto11 to guarantee the constant-time behavior in the specification.
 // See https://github.com/thalesignite/crypto11/issues/5 for further discussion.
+//
+// Symmetric crypto support via cipher.Block is very slow.
+// You can use the BlockModeCloser API
+// but you must call the Close() interface (not found in cipher.BlockMode).
+// See https://github.com/ThalesIgnite/crypto11/issues/6 for further discussion.
 package crypto11
 
 import (

symmetric.go

@@ -239,7 +239,10 @@ var Ciphers = map[int]*SymmetricCipher{
 // PKCS11SecretKey contains a reference to a loaded PKCS#11 symmetric key object.
 //
 // A *PKCS11SecretKey implements the cipher.Block interface, allowing it be used
-// as the argument to cipher.NewCBCDecrypter, etc.
+// as the argument to cipher.NewCBCEncrypter and similar methods.
+// For bulk operation this is very inefficient;
+// using NewCBCEncrypterCloser, NewCBCEncrypter or NewCBC from this package is
+// much faster.
 type PKCS11SecretKey struct {
 	PKCS11Object