Adding description of hamd DBus interface as well as hamctl (sonic-net#57)

Author: martin-belanger

doc/aaa/SONiC RBAC HLD.md

@@ -1,4 +1,7 @@
+
+
 # Authentication and Role-Based Access Control
+
 # High Level Design Document
 #### Rev 0.1
 
@@ -187,9 +190,9 @@ Since these operations (i.e. creating Linux users, assigning certificates, etc.)
 
 ##### 1.1.1.6.1 Host Account Management Daemon (hamd)
 
-The hamd process runs on the host. It is accessed via a DBus interface that provides the ability to access and/or modify the host's Linux database (`/etc/passwd`, `/etc/group`, and optionally `/etc/shadow`). Since DBus is a secured interface we can control which processes will be allowed to access hamd. 
+The **hamd** process runs on the host. It is accessed via a DBus interface that provides the ability to access and/or modify the host's Linux database (`/etc/passwd`, `/etc/group`, and optionally `/etc/shadow`). Since DBus is a secured interface we can control which processes will be allowed to access **hamd**. 
 
-The hamd process will provide the following APIs to create/modify/delete user and group (role) accounts:
+The **hamd** process will provide the following DBus APIs to create/modify/delete user and group (role) accounts:
 
 - **useradd**: To create new users (similar to GNU [useradd](http://man7.org/linux/man-pages/man8/useradd.8.html))
 - **userdel**: To delete a user (similar to GNU [userdel](http://man7.org/linux/man-pages/man8/userdel.8.html))
@@ -198,16 +201,59 @@ The hamd process will provide the following APIs to create/modify/delete user an
 - **groupadd**: To create new groups/roles (similar to GNU [groupadd](http://man7.org/linux/man-pages/man8/groupadd.8.html))
 - **groupdel**: To delete groups/roles (similar to GNU [groupdel](http://man7.org/linux/man-pages/man8/groupdel.8.html))
 
-##### 1.1.1.6.2 Name Service Switch
-
-In addition to providing APIs to create/modify/delete user and group (role) accounts, hamd also provides APIs to simply read user and group (role) accounts. Here's the list:
+##### 1.1.1.6.2 User management with hamd 
+
+Applications that need to manage users (for example **click** or **klish**) can do so by using **hamd**'s DBus **ham.accounts** interface. DBus services such as **hamd** publish their interfaces. This can be retrieved and analyzed at runtime in order to understand the used implementation. The resulting introspection data is in XML format. DBus debug tools such as **qdbus** can be used to retrieve this data. At the time this document was written, the DBus XML definition for the APIs defined in the previous section was:
+
+> ```xml
+>   <interface name="ham.accounts">
+>       <method name="useradd">
+>           <arg direction="in"  type="s"  name="login"/>
+>           <arg direction="in"  type="as" name="roles"/>
+>           <arg direction="in"  type="s"  name="hashed_pw"/>
+>           <arg direction="out" type="(bs)" name="(success, errmsg)" />
+>       </method>
+>       <method name="userdel">
+>           <arg direction="in"  type="s"  name="login"/>
+>           <arg direction="out" type="(bs)" name="(success, errmsg)" />
+>       </method>
+>       <method name="passwd">
+>           <arg direction="in"  type="s"  name="login"/>
+>           <arg direction="in"  type="s"  name="hashed_pw"/>
+>           <arg direction="out" type="(bs)" name="(success, errmsg)" />
+>       </method>
+>       <method name="set_roles">
+>           <arg direction="in"  type="s"  name="login"/>
+>           <arg direction="in"  type="as" name="roles"/>
+>           <arg direction="out" type="(bs)" name="(success, errmsg)" />
+>       </method>
+>       <method name="groupadd">
+>           <arg direction="in"  type="s" name="group"/>
+>           <arg direction="out" type="(bs)" name="(success, errmsg)" />
+>       </method>
+>       <method name="groupdel">
+>           <arg direction="in"  type="s" name="group"/>
+>           <arg direction="out" type="(bs)" name="(success, errmsg)" />
+>       </method>
+>   </interface>
+> ```
+
+##### 1.1.1.6.3 The hamctl shell program
+
+A utility program, **hamctl**, is provided to make it easier for operators to interact with **hamd** from a Linux shell (e.g. bash). This is primarily a debug tool and <u>*should not be invoked from other programs*</u>. Programs should use the DBus interface described above. 
+
+Users logged in at a shell terminal can control **hamd** (e.g. ask it to create or delete a user) with **hamctl**. **hamctl** is sell-documented. Simply invoke "**hamctl --help**" to get the list of commands available.
+
+##### 1.1.1.6.4 Name Service Switch
+
+In addition to providing APIs to create/modify/delete user and group (role) accounts, **hamd** also provides APIs to simply read user and group (role) accounts. Here's the list:
 
 - **getpwnam**: To retrieve user credentials (similar to POSIX [getpwnam](http://man7.org/linux/man-pages/man3/getpwnam.3.html))
 - **getpwuid**: To retrieve user credentials (similar to POSIX [getpwuid](http://man7.org/linux/man-pages/man3/getpwnam.3.html))
 - **getgrnam**: To retrieve group/role credentials (similar to POSIX [getgrnam](http://man7.org/linux/man-pages/man3/getgrnam.3.html))
 - **getgrgid**: To retrieve group/role credentials (similar to POSIX [getgrgid](http://man7.org/linux/man-pages/man3/getgrnam.3.html))
 
-These APIs, however, are meant to be invoked through [NSS](https://en.wikipedia.org/wiki/Name_Service_Switch) (name service switch).  That is, applications running in containers can simply continue invoking the standard POSIX APIs (`getpwnam()`, `getgrnam()`, etc) and a Host Account Management NSS module will ensure that the credentials get retrieved from hamd running on the host. The HAM NSS module (`libnss_ham.so.2`) need be installed and configured (`/etc/nsswitch.conf`) in the containers that require access to the host's Linux database. 
+These APIs, however, are meant to be invoked through [NSS](https://en.wikipedia.org/wiki/Name_Service_Switch) (name service switch).  That is, applications running in containers can simply continue invoking the standard POSIX APIs (`getpwnam()`, `getgrnam()`, etc) and a Host Account Management NSS module will ensure that the credentials get retrieved from **hamd** running on the host. The HAM NSS module (`libnss_ham.so.2`) need be installed and configured (`/etc/nsswitch.conf`) in the containers that require access to the host's Linux database. 
 
 ### 1.1.2 Configuration and Management Requirements
 An interface and accompanying CLI must be developed for local user management. Local users should be configurable like any other feature: via CLI, REST, and gNMI. Additionally, users may also be created and managed via Linux commands in the Bash shell. This will add additional complexity and require a service to sync between the Redis DB and the Linux user database.