Add/Update docs to include auditor, add ReqUnknownDirectory auditor e…

…rror

protocol/auditlog.go

@@ -128,8 +128,23 @@ func (h *directoryHistory) verifySTRConsistency(str *m.SignedTreeRoot) error {
 	return CheckBadSTR
 }
 
-// TODO add doc
-func (l *ConiksAuditLog) Query(req *AuditingRequest) (*Response, ErrorCode) {
+// GetObservedSTR gets the observed STR for the CONIKS directory address indicated
+// in the AuditingRequest req received from a CONIKS client from the auditor's latest
+// directory history entry, and returns a tuple of the form
+// (response, error).
+// The response (which also includes the error code) is supposed to
+// be sent back to the client. The returned error is used by the auditor
+// for logging purposes.
+//
+// A request without a directory address is considered
+// malformed, and causes GetObservedSTR() to return a
+// message.NewErrorResponse(ErrMalformedClientMessage) tuple.
+// GetObservedSTR() returns a message.NewObservedSTR(str) tuple.
+// str is the signed tree root the auditor has observed for the latest epoch.
+// If the auditor doesn't have any history entries for the requested CONIKS
+// directory, GetObservedSTR() returns a
+// message.NewErrorResponse(ReqUnknownDirectory) tuple.
+func (l *ConiksAuditLog) GetObservedSTR(req *AuditingRequest) (*Response, ErrorCode) {
 
 	// make sure the request is well-formed
 	if len(req.DirectoryAddr) <= 0 {
@@ -141,12 +156,29 @@ func (l *ConiksAuditLog) Query(req *AuditingRequest) (*Response, ErrorCode) {
 		return NewObservedSTR(h.latestSTR)
 	}
 
-	// FIXME: return ErrUnknownDirectory
-	return nil, ErrDirectory
+	return NewErrorResponse(ReqUnknownDirectory), ReqUnknownDirectory
 }
 
-// TODO: add doc
-func (l *ConiksAuditLog) QueryInEpoch(req *AuditingInEpochRequest) (*Response,
+// GetObservedSTRInEpoch gets the observed STR for the CONIKS directory address
+// for a prior directory history entry indicated in the
+// AuditingInEpochRequest req received from a CONIKS client,
+// and returns a tuple of the form (response, error).
+// The response (which also includes the error code) is supposed to
+// be sent back to the client. The returned error is used by the auditor
+// for logging purposes.
+//
+// A request without a directory address or with an epoch greater than the latest
+// observed epoch of this directory is considered malformed, and causes
+// GetObservedSTRInEpoch() to return a
+// message.NewErrorResponse(ErrMalformedClientMessage) tuple.
+// GetObservedSTRInEpoch() returns a message.NewObservedSTRs(strs) tuple.
+// strs is a list of STRs for the epoch range [ep,
+// l.histories[req.DirectoryAddr].latestSTR.Epoch], where ep is the past epoch
+// for which the client has requested the observed STR.
+// If the auditor doesn't have any history entries for the requested CONIKS
+// directory, GetObservedSTR() returns a
+// message.NewErrorResponse(ReqUnknownDirectory) tuple.
+func (l *ConiksAuditLog) GetObservedSTRInEpoch(req *AuditingInEpochRequest) (*Response,
 	ErrorCode) {
 
 	// make sure the request is well-formed
@@ -178,6 +210,5 @@ func (l *ConiksAuditLog) QueryInEpoch(req *AuditingInEpochRequest) (*Response,
 		return NewObservedSTRs(strs)
 	}
 
-	// FIXME: return ErrUnknownDirectory
-	return nil, ErrDirectory
+	return NewErrorResponse(ReqUnknownDirectory), ReqUnknownDirectory
 }

protocol/error.go

@@ -8,14 +8,17 @@ package protocol
 // An ErrorCode implements the built-in error interface type.
 type ErrorCode int
 
-// These codes indicate the status of a client-server message exchange.
+// These codes indicate the status of a client-server or client-auditor message
+// exchange.
 // Codes prefixed by "Req" indicate different client request results.
 // Codes prefixed by "Err" indicate an internal server error or a malformed
 // message.
 const (
 	ReqSuccess ErrorCode = iota + 100
 	ReqNameExisted
 	ReqNameNotFound
+	// auditor->client: no observed history for the requested directory
+	ReqUnknownDirectory
 
 	ErrDirectory
 	ErrMalformedClientMessage

protocol/message.go

@@ -91,26 +91,27 @@ type MonitoringRequest struct {
 }
 
 // An AuditingRequest is a message with a CONIKS key directory's address
-// as a string that a CONIKS client sends to a CONIKS auditor to request
-// the latest STR the auditor has observed for the given directory.
-// If the client needs to request a directory's STR for a prior epoch, it
+// as a string that a CONIKS client sends to a CONIKS auditor, or a CONIKS auditor
+// sends to a CONIKS directory, to request the given directory's latest STR.
+// If the client/auditor needs to request a directory's STR for a prior epoch, it
 // must send an AuditingInEpochRequest.
 //
-// The response to a successful request is an ObservedDirectoryProof.
+// The response to a successful request is an ObservedSTR.
 type AuditingRequest struct {
 	DirectoryAddr string `json:"directory_addr"`
 }
 
 // An AuditingInEpochRequest is a message with a key directory's address
 // as a string and an epoch as a uint64 that a CONIKS client sends to
-// a CONIKS auditor to retrieve the STR it observed for the directory in
-// the given epoch. The client sends this request type when it needs to
+// a CONIKS auditor, or a CONIKS auditor sends to a CONIKS directory,
+// to retrieve the STR for the directory in
+// the given epoch. The client/auditor sends this request type when it needs to
 // audit a directory's STR for a prior epoch (i.e. as part of a
-// key lookup in epoch check or a monitoring check). The client can send an
-// AuditingRequest if it needs to audit a directory's STR for its latest
-// epoch.
+// key lookup in epoch check, a monitoring check, or an auditor update).
+// The client/auditor can send an AuditingRequest if it needs to audit a
+// directory's STR for its latest epoch.
 //
-// The response to a successful request is an ObservedDirectoryProofs with
+// The response to a successful request is an ObservedSTRs with
 // a list of STRs covering the epoch range [Epoch, d.LatestSTR().Epoch].
 type AuditingInEpochRequest struct {
 	DirectoryAddr string `json:"directory_addr"`
@@ -260,10 +261,10 @@ func NewMonitoringProof(ap []*m.AuthenticationPath,
 }
 
 // NewObservedSTR creates the response message a CONIKS auditor
-// sends to a client upon an AuditingRequest,
-// and returns a Response containing an ObservedSTR struct.
-// auditlog.Audit() passes the signed tree root for the auditor's latest
-// observed epoch str.
+// sends to a client, or a CONIKS directory sends to an auditor,
+// upon an AuditingRequest, and returns a Response containing an ObservedSTR struct.
+// auditlog.GetObservedSTR(), or directory.GetLatestSTR(), passes the signed
+// tree root for the directory's latest str.
 //
 // See auditlog.Audit() for details on the contents of the created
 // ObservedSTR.