From: Sage Weil <sage@redhat.com>
Date: Fri, 1 Feb 2019 18:17:07 +0000 (-0600)
Subject: auth: document Auth{Client,Server} interfaces
X-Git-Tag: v14.1.0~183^2~17
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=e1f6eb8a7ad49f1eb0bc1424bdc199d84d4c0bbb;p=ceph.git

auth: document Auth{Client,Server} interfaces

Signed-off-by: Sage Weil <sage@redhat.com>
---

diff --git a/src/auth/AuthClient.h b/src/auth/AuthClient.h
index 8977772cf5c5..770d8d505124 100644
--- a/src/auth/AuthClient.h
+++ b/src/auth/AuthClient.h
@@ -12,17 +12,22 @@ class AuthClient {
 public:
   virtual ~AuthClient() {}
 
+  /// Build an authentication request to begin the handshake
   virtual int get_auth_request(
     Connection *con,
     AuthConnectionMeta *auth_meta,
     uint32_t *method,
     std::vector<uint32_t> *preferred_modes,
     bufferlist *out) = 0;
+
+  /// Handle server's request to continue the handshake
   virtual int handle_auth_reply_more(
     Connection *con,
     AuthConnectionMeta *auth_meta,
     const bufferlist& bl,
     bufferlist *reply) = 0;
+
+  /// Handle server's indication that authentication succeeded
   virtual int handle_auth_done(
     Connection *con,
     AuthConnectionMeta *auth_meta,
@@ -31,6 +36,8 @@ public:
     const bufferlist& bl,
     CryptoKey *session_key,
     std::string *connection_secret) = 0;
+
+  /// Handle server's indication that the previous auth attempt failed
   virtual int handle_auth_bad_method(
     Connection *con,
     AuthConnectionMeta *auth_meta,
diff --git a/src/auth/AuthServer.h b/src/auth/AuthServer.h
index fb54b0a59430..80412aa3e390 100644
--- a/src/auth/AuthServer.h
+++ b/src/auth/AuthServer.h
@@ -17,12 +17,15 @@ public:
   AuthServer(CephContext *cct) : auth_registry(cct) {}
   virtual ~AuthServer() {}
 
+  /// Get authentication methods and connection modes for the given peer type
   virtual void get_supported_auth_methods(
     int peer_type,
     std::vector<uint32_t> *methods,
     std::vector<uint32_t> *modes = nullptr) {
     auth_registry.get_supported_methods(peer_type, methods, modes);
   }
+
+  /// Get support connectino modes for the given peer type and auth method
   virtual void get_supported_con_modes(
     int peer_type,
     uint32_t auth_method,
@@ -30,16 +33,18 @@ public:
     auth_registry.get_supported_modes(peer_type, auth_method, modes);
   }
 
+  /// return an AuthAuthorizeHandler for hte given peer type and auth method
   AuthAuthorizeHandler *get_auth_authorize_handler(
     int peer_type,
     int auth_method) {
     return auth_registry.get_handler(peer_type, auth_method);
   }
 
+  /// Handle an authentication request on an incoming connection
   virtual int handle_auth_request(
     Connection *con,
     AuthConnectionMeta *auth_meta,
-    bool more,
+    bool more,           ///< true if this is not the first part of the handshake
     uint32_t auth_method,
     const bufferlist& bl,
     bufferlist *reply) = 0;