Merge pull request #176 from LinuxJedi/wolfSSH-RFC-4256

Add wolfSSH documentation for Keyboard-Interactive

Author: JacobBarthelmeh

wolfSSH/src/chapter01.md

@@ -29,7 +29,7 @@ The wolfSSH library is a lightweight SSHv2 server library written in ANSI C and
 
 - Public key authentication options: RSA and ECDSA (with curves NISTP256, NISTP384, NISTP521)
 
-- User authentication support (password and public key authentication)
+- User authentication support (password, keyboard-interactive and public key authentication)
 
 - Simple API
 

wolfSSH/src/chapter05.md

@@ -44,6 +44,7 @@ The following are values passed to the user authentication callback function in
 
 ```
 WOLFSSH_USERAUTH_PASSWORD
+WOLFSSH_USERAUTH_KEYBOARD
 WOLFSSH_USERAUTH_PUBLICKEY
 ```
 
@@ -72,6 +73,7 @@ WOLFSSH_USERAUTH_INVALID_USER
 WOLFSSH_USERAUTH_INVALID_PASSWORD
 WOLFSSH_USERAUTH_INVALID_PUBLICKEY
 WOLFSSH_USERAUTH_PARTIAL_SUCCESS
+WOLFSSH_USERAUTH_SUCCESS_ANOTHER
 ```
 
 ##  Callback Function Data Types
@@ -84,10 +86,11 @@ typedef struct WS_UserAuthData {
     byte* username ;
     word32 usernameSz ;
     byte* serviceName ;
-    word32 serviceNameSz ; n
+    word32 serviceNameSz ;
     union {
         WS_UserAuthData_Password password ;
         WS_UserAuthData_PublicKey publicKey ;
+        WS_UserAuthData_Keyboard keyboard ;
     } sf;
 } WS_UserAuthData;
 ```
@@ -110,6 +113,51 @@ typedef struct WS_UserAuthData_Password {
 } WS_UserAuthData_Password;
 ```
 
+### Keyboard-Interactive
+
+The Keyboard-Interactive mode allows for an arbitrary number of prompts and
+responses from the server to the client. The structure that contains the
+information is as follows:
+
+```c
+typedef struct WS_UserAuthData_Keyboard {
+    word32 promptCount;
+    word32 responseCount;
+    word32 promptNameSz;
+    word32 promptInstructionSz;
+    word32 promptLanguageSz;
+    byte* promptName;
+    byte* promptInstruction;
+    byte* promptLanguage;
+    word32* promptLengths;
+    word32* responseLengths;
+    byte* promptEcho;
+    byte** responses;
+    byte** prompts;
+} WS_UserAuthData_Keyboard;
+```
+
+On the client side, during authentication, the `promptName` and
+`promptInstruction` will indicate to the user information about the
+authentication. The `promptLanguage` field is a deprecated part of the API and
+is ignored.
+
+The `promptCount` indicates how many prompts there are. `prompts` contains the
+array of prompts, `promptLengths` is an array containing the length of prompt
+in `prompts`. `promptEcho` in an array of booleans indicating whether or not
+each prompt response should be echoed to the user as they are typing.
+
+Conversely there is `responseCount` to set the number of responses given.
+`responses` and `responseLengths` contain the response data for the prompts.
+
+The server can set the prompts using the `wolfSSH_SetKeyboardAuthPrompts()`
+callback. The `WS_CallbackKeyboardAuthPrompts` callback should set the
+`promptCount`, `prompts`, `promptLengths` and `promptEcho`. The other `prompt*`
+items are optional.
+
+The server should return `WOLFSSH_USERAUTH_SUCCESS_ANOTHER` from the
+`WS_CallbackUserAuth` callback to execute subsequent request / response rounds.
+
 ###  Public Key
 
 wolfSSH will support multiple public key algorithms. The publicKeyType member points to the algorithm name used.

wolfSSH/src/chapter06.md

@@ -22,6 +22,18 @@ void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh );
 ```
 This returns the pointer to the user authentication context data stored in the provided wolfSSH session. This is not to be confused with the wolfSSH’s context data used to create the session.
 
+## Setting the Keyboard Authentication Prompts Callback Function
+```
+void wolfSSH_SetKeyboardAuthPrompts(WOLFSSH_CTX* ctx, WS_CallbackKeyboardAuthPrompts cb);
+```
+
+The server needs to specify the prompts that are to be given to the client so
+that it can authenticate in Keyboard-Interactive mode. This callback allows the
+server to set the prompts ready to send to the client.
+
+Without this set, Keyboard-Interactive mode will be disabled on the server, even
+if attempts are made to explicitly enable it.
+
 ##  Example Echo Server User Authentication
 
 The example echo server implements the authentication callback with sample users using passwords and public keys. The example callback, wsUserAuth, is set on the wolfSSH context:

wolfSSH/src/chapter13.md

@@ -841,6 +841,55 @@ authentication context.
 void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh )
 ```
 
+### wolfSSH_SetKeyboardAuthPrompts()
+
+
+**Synopsis**
+
+**Description**
+
+The wolfSSH_SetKeyboardAuthPrompts() function is used to setup the callback
+which will provide the server with the prompts to send to the client.
+
+**Return Values**
+
+None
+
+**Parameters**
+
+**ctx** - pointer to the wolfSSH context
+**cb** - callback function to provide the keyboard prompts
+
+```
+#include <wolfssh/ssh.h>
+void wolfSSH_SetKeyboardAuthPrompts(WOLFSSH_CTX* ctx,
+                                    WS_CallbackKeyboardAuthPrompts cb)
+```
+
+### wolfSSH_SetKeyboardAuthCtx()
+
+
+**Synopsis**
+
+**Description**
+
+The wolfSSH_SetKeyboardAuthCtx() function is used to setup the user context
+for the wolfSSH_SetKeyboardAuthPrompts() function.
+
+**Return Values**
+
+None
+
+**Parameters**
+
+**ssh** - pointer to the WOLFSSH object
+**keyboardAuthCtx* - pointer to the user context data
+
+```
+#include <wolfssh/ssh.h>
+void wolfSSH_SetKeyboardAuthCtx(WOLFSSH* ssh, void* keyboardAuthCtx)
+```
+
 ##  Set Username