More comments

Signed-off-by: Alessandro Sorniotti <aso@zurich.ibm.com>

bccsp/handlers/nym.go

@@ -160,6 +160,14 @@ func (i *NymPublicKeyImporter) KeyImport(raw interface{}, opts bccsp.KeyImportOp
 
 	pk, err := i.User.NewPublicNymFromBytes(bytes)
 	if err != nil {
+		// A Nym public key is just a group element. There are 2 main ways of serialising
+		// an uncompressed point: either the two coordinates, or the prefix `0x04` and the
+		// two coordinates. Typically these serialisation issues are handled with a
+		// `translator` object which gets bytes, understands the serialisation and produces
+		// a group element. This code does not have that, however. As a consequence, we
+		// handle the issue by prefixing the `0x04` byte and re-attempting deserialisation
+		// in case it first failed. Issue https://github.com/IBM/idemix/issues/42 has
+		// been created to fix this properly by adding the translator.
 		pk, err = i.User.NewPublicNymFromBytes(append([]byte{04}, bytes...))
 		if err != nil {
 			return nil, err

bccsp/schemes/aries/smartcard.go

@@ -17,6 +17,14 @@ import (
 	math "github.com/IBM/mathlib"
 )
 
+// Smartcard is an implementation of an idemix joint signature where one of
+// the attributes is only known to a smartcard. This structure plays a dual
+// role:
+//  1. emulation of the smartcard to be able to test verification without
+//     external hardware. (`PRF`, `NymEid`, `NymSign` methods). These
+//     functions are never used in production.
+//  2. implementation of the verification of signatures produced by a
+//     real smartcard (`NymVerify` method). This function is used in production.
 type Smartcard struct {
 	H0, H1, H2     *math.G1
 	Uid_sk, EID    *math.Zr

bccsp/types/idemixopts.go

@@ -355,6 +355,8 @@ type IdemixNymSignerOpts struct {
 	IsSmartcard bool
 
 	// Smartcard is a software smartcard used to support signing in s/w
+	// this field is only used in testing to emulate a real smartcard
+	// and may never be set in production.
 	Smartcard interface{}
 
 	// NymEid is the nym eid to use in the verification