Commit fb7994a3 authored by Sietse Ringers's avatar Sietse Ringers
Browse files

docs: start godocs of exported functions in the keyshare server with the function name

parent 16bfa6f4
......@@ -82,8 +82,8 @@ func GenerateDecryptionKey() (AESKey, error) {
return res, err
}
// Add an aes key for decryption, with identifier keyid
// Calling this will cause all keyshare packets generated with the key to be trusted
// DangerousAddDecryptionKey adds an AES key for decryption, with identifier keyID.
// Calling this will cause all keyshare packets generated with the key to be trusted.
func (c *Core) DangerousAddDecryptionKey(keyID uint32, key AESKey) {
c.decryptionKeys[keyID] = key
}
......@@ -103,7 +103,8 @@ func (c *Core) setJWTPrivateKey(id uint32, key *rsa.PrivateKey) {
c.jwtPrivateKeyID = id
}
// Add public key as trusted by keyshareCore. Calling this on incorrectly generated key material WILL compromise keyshare secrets!
// DangerousAddTrustedPublicKey adds a public key as trusted by keysharecore.
// Calling this on incorrectly generated key material WILL compromise keyshare secrets!
func (c *Core) DangerousAddTrustedPublicKey(keyID irma.PublicKeyIdentifier, key *gabikeys.PublicKey) {
c.trustedKeys[keyID] = key
}
......@@ -25,7 +25,7 @@ var (
ErrUnknownCommit = errors.New("unknown commit id")
)
// Generate a new keyshare secret, secured with the given pin
// NewUser generates a new keyshare secret, secured with the given pin.
func (c *Core) NewUser(pinRaw string) (User, error) {
secret, err := gabi.NewKeyshareSecret()
if err != nil {
......@@ -60,7 +60,7 @@ func (c *Core) newUserFromSecret(pinRaw string, secret *big.Int) (User, error) {
return c.encryptUser(p)
}
// Check pin for validity, and generate jwt for future access
// ValidatePin checks pin for validity and generates JWT for future access.
func (c *Core) ValidatePin(ep User, pin string, userID string) (string, error) {
p, err := c.decryptUserIfPinOK(ep, pin)
if err != nil {
......@@ -80,13 +80,15 @@ func (c *Core) ValidatePin(ep User, pin string, userID string) (string, error) {
return token.SignedString(c.jwtPrivateKey)
}
// Check whether the given JWT is currently valid as an access token for operations on the provided encrypted keyshare packet
// ValidateJWT checks whether the given JWT is currently valid as an access token for operations
// on the provided encrypted keyshare packet.
func (c *Core) ValidateJWT(ep User, jwt string) error {
_, err := c.verifyAccess(ep, jwt)
return err
}
// Change pin in an encrypted keyshare packet to a new value, after validating that the old value is known by caller.
// ChangePin changes the pin in an encrypted keyshare packet to a new value, after validating that
// the old value is known by the caller.
func (c *Core) ChangePin(ep User, oldpinRaw, newpinRaw string) (User, error) {
p, err := c.decryptUserIfPinOK(ep, oldpinRaw)
if err != nil {
......@@ -109,8 +111,8 @@ func (c *Core) ChangePin(ep User, oldpinRaw, newpinRaw string) (User, error) {
return c.encryptUser(p)
}
// Verify that a given access jwt is valid, and if so, return decrypted keyshare packet
// Note: Although this is an internal function, it is tested directly
// verifyAccess checks that a given access jwt is valid, and if so, return decrypted keyshare packet.
// Note: Although this is an internal function, it is tested directly
func (c *Core) verifyAccess(ep User, jwtToken string) (unencryptedUser, error) {
// Verify token validity
token, err := jwt.Parse(jwtToken, func(token *jwt.Token) (interface{}, error) {
......@@ -156,7 +158,7 @@ func (c *Core) verifyAccess(ep User, jwtToken string) (unencryptedUser, error) {
return p, nil
}
// Get keyshare commitment usign given idemix public key(s)
// GenerateCommitments generates keyshare commitments using the specified Idemix public key(s).
func (c *Core) GenerateCommitments(ep User, accessToken string, keyIDs []irma.PublicKeyIdentifier) ([]*gabi.ProofPCommitment, uint64, error) {
// Validate input request and build key list
var keyList []*gabikeys.PublicKey
......@@ -195,7 +197,7 @@ func (c *Core) GenerateCommitments(ep User, accessToken string, keyIDs []irma.Pu
return commitments, commitID, nil
}
// Generate response for zero-knowledge proof of keyshare secret, for a given previous commit and challenge
// GenerateResponse generates the response of a zero-knowledge proof of the keyshare secret, for a given previous commit and challenge.
func (c *Core) GenerateResponse(ep User, accessToken string, commitID uint64, challenge *big.Int, keyID irma.PublicKeyIdentifier) (string, error) {
// Validate request
if uint(challenge.BitLen()) > gabikeys.DefaultSystemParameters[1024].Lh || challenge.Cmp(big.NewInt(0)) < 0 {
......
......@@ -20,7 +20,8 @@ type (
// security impact through error side channels.
unencryptedUser [64 + 64 + 32]byte
// Size is that of unencrypted packet + 12 bytes for nonce + 16 bytes for tag + 4 bytes for key ID
// User contains the encrypted data of a keyshare user.
// The size is that of unencryptedUser + 12 bytes for nonce + 16 bytes for tag + 4 bytes for key ID.
User [64 + 64 + 32 + 12 + 16 + 4]byte
)
......
......@@ -21,17 +21,16 @@ const (
eventTypeIRMASession eventType = "IRMA_SESSION"
)
// Interface used by server to manage data storage
// there are multiple implementations of this, currently:
// DB is an interface used by server to manage data storage.
// There are multiple implementations of this, currently:
// - memorydb (memorydb.go) storing all data in memory (forgets everything after reboot)
// - postgresdb (postgresdb.go) storing all data in a postgres database
type DB interface {
// User management
AddUser(user *User) error
user(username string) (*User, error)
updateUser(user *User) error
// ReservePinTry reserves a pin check attempt, and additionally it returns:
// reservePinTry reserves a pin check attempt, and additionally it returns:
// - allowed is whether the user is allowed to do the pin check (false if user is blocked)
// - tries is how many tries are remaining, after this pin check
// - wait is how long the user must wait before the next attempt is allowed if tries is 0
......@@ -44,8 +43,8 @@ type DB interface {
// default values (0 past attempts, no unblock date).
resetPinTries(user *User) error
// User activity registration
// SetSeen calls are used to track when a users account was last active, for deleting old accounts
// User activity registration.
// setSeen calls are used to track when a users account was last active, for deleting old accounts.
setSeen(user *User) error
addLog(user *User, eventType eventType, param interface{}) error
......@@ -53,7 +52,7 @@ type DB interface {
addEmailVerification(user *User, emailAddress, token string) error
}
// Actual data on a user used by this server.
// User represents a user of this server.
type User struct {
Username string
Language string
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment