Add comments and documentation

irma_signature.go

@@ -11,7 +11,7 @@ import (
 )
 
 // IrmaSignedMessage is a message signed with an attribute-based signature
-// The 'realnonce' will be calculated as: SigRequest.GetNonce() = ASN1(sha256(message), sha256(nonce))
+// The 'realnonce' will be calculated as: SigRequest.GetNonce() = ASN1(nonce, SHA256(message), timestampSignature)
 type IrmaSignedMessage struct {
 	Signature gabi.ProofList  `json:"signature"`
 	Nonce     *big.Int        `json:"nonce"`

irmaclient/legacy.go

@@ -6,6 +6,7 @@ import (
 	"github.com/mhe/gabi"
 )
 
+// These have no (de)serializer in Java so we have to deal with how Java serializes them by default.
 func (pki *publicKeyIdentifier) MarshalJSON() ([]byte, error) {
 	temp := struct {
 		Issuer  map[string]string `json:"issuer"`
@@ -17,6 +18,7 @@ func (pki *publicKeyIdentifier) MarshalJSON() ([]byte, error) {
 	return json.Marshal(temp)
 }
 
+// Same as above since these use publicKeyIdentifier as map key type.
 func (comms *proofPCommitmentMap) UnmarshalJSON(bytes []byte) error {
 	comms.Commitments = map[publicKeyIdentifier]*gabi.ProofPCommitment{}
 	temp := struct {

irmaclient/session.go

@@ -115,6 +115,7 @@ func calcVersion(qr *irma.Qr) (*irma.ProtocolVersion, error) {
 	return nil, fmt.Errorf("No supported protocol version between %s and %s", qr.ProtocolVersion, qr.ProtocolMaxVersion)
 }
 
+// IsInteractive returns whether this session uses an API server or not.
 func (session *session) IsInteractive() bool {
 	return session.ServerURL != ""
 }
@@ -386,6 +387,9 @@ func (session *session) getSessionInfo() {
 	}
 }
 
+// doSession performs the session: it computes all proofs of knowledge, constructs credentials in case of issuance,
+// asks for the pin and performs the keyshare session, and finishes the session by either POSTing the result to the
+// API server or returning it to the caller (in case of interactive and noninteractive sessions, respectively).
 func (session *session) doSession(proceed bool) {
 	defer session.recoverFromPanic()
 
@@ -420,6 +424,7 @@ func (session *session) doSession(proceed bool) {
 	}
 }
 
+// Distributed returns whether or not this session involves a keyshare server.
 func (session *session) Distributed() bool {
 	var smi irma.SchemeManagerIdentifier
 	if session.Action == irma.ActionIssuing {
@@ -486,6 +491,8 @@ func (session *session) KeysharePinOK() {
 
 type disclosureResponse string
 
+// sendResponse sends the proofs of knowledge of the hidden attributes and/or the secret key, or the constructed
+// attribute-based signature, to the API server.
 func (session *session) sendResponse(message interface{}) {
 	var log *LogEntry
 	var err error
@@ -555,14 +562,9 @@ func (session *session) sendResponse(message interface{}) {
 	session.Handler.Success(session.Action, string(messageJson))
 }
 
+// managerSession performs a "session" in which a new scheme manager is added (asking for permission first).
 func (session *session) managerSession() {
-	defer func() {
-		if e := recover(); e != nil {
-			if session.Handler != nil {
-				session.Handler.Failure(session.Action, panicToError(e))
-			}
-		}
-	}()
+	defer session.recoverFromPanic()
 
 	// We have to download the scheme manager description.xml here before installing it,
 	// because we need to show its contents (name, description, website) to the user

legacy.go

@@ -13,6 +13,9 @@ import (
 // Legacy from the old Android app, and from the protocol that will be updated
 // in the future
 
+// Because the Java version of the current version of the protocol misses a serializer for the Java-equivalent
+// of the Java-equivalent of the IssuerIdentifier struct, these get serialized to an ugly map structure that we
+// have to parse here.
 func (si *SessionInfo) UnmarshalJSON(b []byte) error {
 	temp := &struct {
 		Jwt     string          `json:"jwt"`

requests.go

@@ -60,7 +60,9 @@ type DisclosureRequest struct {
 // A SignatureRequest is a a request to sign a message with certain attributes.
 type SignatureRequest struct {
 	DisclosureRequest
-	Message   string          `json:"message"`
+	Message string `json:"message"`
+
+	// Session state
 	Timestamp *atum.Timestamp `json:"-"`
 }