From 0588229c7e70b4a915a4e71649b9920c68b444ad Mon Sep 17 00:00:00 2001 From: Kris Moore Date: Fri, 26 Feb 2016 18:59:23 -0500 Subject: [PATCH 1/6] Update service example --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7c8a802..1b9aedc 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,11 @@ Qt5 Websockets (pkg install qt5-websockets) ``` (For WebSockets - Required for SysAdm Client) -% sudo sysrc -f /etc/rc.conf sysadm_websocket_enable="YES" +% sudo sysrc -f /etc/rc.conf sysadm_enable="YES" % sudo service sysadm-websocket start (Optional for REST) -% sudo sysrc -f /etc/rc.conf sysadm_restserver_enable="YES" +% sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES" % sudo service sysadm-restserver start ``` From 1f94a24f1d6ba2227d1d2518f974a6ccbc1efe20 Mon Sep 17 00:00:00 2001 From: Kris Moore Date: Fri, 26 Feb 2016 18:59:54 -0500 Subject: [PATCH 2/6] Update more of the sysrc / service --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1b9aedc..6bb1b74 100644 --- a/README.md +++ b/README.md @@ -42,11 +42,11 @@ Qt5 Websockets (pkg install qt5-websockets) ``` (For WebSockets - Required for SysAdm Client) % sudo sysrc -f /etc/rc.conf sysadm_enable="YES" -% sudo service sysadm-websocket start +% sudo service sysadm start (Optional for REST) % sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES" -% sudo service sysadm-restserver start +% sudo service sysadm-rest start ``` ### API Documentation From 7be968877354a3fafbee7e4d51f2b951e47ac82c Mon Sep 17 00:00:00 2001 From: Kris Moore Date: Sat, 27 Feb 2016 12:01:11 -0500 Subject: [PATCH 3/6] Update README --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6bb1b74..0fb44d8 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,8 @@ Official repo for PC-BSD's sysadm middleware WebSocket & REST server This middleware acts as the core for controlling a PC-BSD or FreeBSD
-system either locally or remotely via WebSockets or REST. +system either locally or remotely via WebSockets or REST. It is also the
+server component to [PC-BSD's SysAdm GUI client](https://github.com/pcbsd/sysadm-ui-qt). ### Required Qt Modules From fb1e0008a5e1ca31e35200a64c44f02a57fa5fe8 Mon Sep 17 00:00:00 2001 From: Ken Moore Date: Mon, 29 Feb 2016 11:42:51 -0500 Subject: [PATCH 4/6] Update connection.rst Add information about the auth_ssl system, and clarify the localhost password requirements. --- api/connection.rst | 51 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 5 deletions(-) diff --git a/api/connection.rst b/api/connection.rst index 53bd018..6bab135 100644 --- a/api/connection.rst +++ b/api/connection.rst @@ -13,10 +13,6 @@ Add some links to docs on websockets and json.... Authentication ============== -Describe how to authenticate to websockets via Local / Remote, local connections do not need username / password... - - - Once a websocket connection is made to the server, the client needs to use the authentication class to authenticate itself to obtain access to the sysadm service. Every authentciation class request contains the following parameters: @@ -39,6 +35,7 @@ request contains the following parameters: Several methods are available for authentication. Here is an example of a login using a username and password: +(Note: When connecting to the localhost, the password field may be left empty for non-root user access). **WebSocket Request** @@ -69,6 +66,50 @@ Here is an example of using token authentication, where the token is invalidated } } +Here is an example of using a pre-registered SSL certificate to request authentication: +(Note: This is a two step process with only a 30 seconds window of validity, so this is best left up to automated systems rather than direct user requests). + +**WebSocket Request (Stage 1 - Initial Request)** + +.. code-block:: json + + { + "namespace" : "rpc", + "name" : "auth_ssl", + "id" : "sampleID", + "args" : "" + } +.. +**WebSocket Reply (Stage 1)** + +.. code-block:: json + + { + "args": { + "test_string" : "" + }, + "id": "sampleID", + "name": "response", + "namespace": "rpc" + } +.. + +On receipt of the test_string, the user-side client must encrypt that string with the desired SSL certificate/key combination, then return that encrypted string back to the server (Stage 2) within 30 seconds of the initial stage 1 reply. The encrypted string should also be base64-encoded before insertion into the stage 2 JSON request to ensure accurate transport back to the server. + +**WebSocket Request (Stage 2 - Return encoded string)** + +.. code-block:: json + + { + "namespace" : "rpc", + "name" : "auth_ssl", + "id" : "sampleID", + "args" : { + "encrypted_string" : "" + } + } +.. + A successful authentication will provide a reply similar to this: **WebSocket Reply** @@ -192,4 +233,4 @@ A query contains the following parameters: "id": "fooid", "name": "response", "namespace": "rpc" - } \ No newline at end of file + } From 2887addb926f74db6a9fa26c8d0070c098505d6c Mon Sep 17 00:00:00 2001 From: dlavigne Date: Mon, 29 Feb 2016 13:28:23 -0500 Subject: [PATCH 5/6] Minor formatting fixes. --- api/connection.rst | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/api/connection.rst b/api/connection.rst index 6bab135..89f6c7a 100644 --- a/api/connection.rst +++ b/api/connection.rst @@ -13,8 +13,8 @@ Add some links to docs on websockets and json.... Authentication ============== -Once a websocket connection is made to the server, the client needs to use the authentication class to authenticate itself to obtain access to the sysadm service. Every authentciation class -request contains the following parameters: +Once a websocket connection is made to the server, the client needs to use the authentication class to authenticate itself to obtain access to the sysadm service. Every authentciation +class request contains the following parameters: +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ | **Parameter** | **Value** | **Description** | @@ -34,8 +34,9 @@ request contains the following parameters: +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -Several methods are available for authentication. Here is an example of a login using a username and password: -(Note: When connecting to the localhost, the password field may be left empty for non-root user access). +Several methods are available for authentication. Here is an example of a login using a username and password. + +.. note:: when connecting to the localhost, the password field may be left empty for non-root user access. **WebSocket Request** @@ -66,8 +67,8 @@ Here is an example of using token authentication, where the token is invalidated } } -Here is an example of using a pre-registered SSL certificate to request authentication: -(Note: This is a two step process with only a 30 seconds window of validity, so this is best left up to automated systems rather than direct user requests). +Here is an example of using a pre-registered SSL certificate to request authentication. Note that this is a two-step process with only a 30 seconds window of validity, so this is best +left to automated systems rather than direct user requests. **WebSocket Request (Stage 1 - Initial Request)** @@ -78,8 +79,8 @@ Here is an example of using a pre-registered SSL certificate to request authenti "name" : "auth_ssl", "id" : "sampleID", "args" : "" - } -.. + } + **WebSocket Reply (Stage 1)** .. code-block:: json @@ -92,11 +93,12 @@ Here is an example of using a pre-registered SSL certificate to request authenti "name": "response", "namespace": "rpc" } -.. -On receipt of the test_string, the user-side client must encrypt that string with the desired SSL certificate/key combination, then return that encrypted string back to the server (Stage 2) within 30 seconds of the initial stage 1 reply. The encrypted string should also be base64-encoded before insertion into the stage 2 JSON request to ensure accurate transport back to the server. +On receipt of the "test_string", the user-side client must encrypt that string with the desired SSL certificate/key combination, then return that encrypted string back to the server +(Stage 2) within 30 seconds of the initial stage 1 reply. The encrypted string should also be base64-encoded before insertion into the stage 2 JSON request to ensure accurate transport +back to the server. -**WebSocket Request (Stage 2 - Return encoded string)** +**WebSocket Request (Stage 2 - Return Encoded String)** .. code-block:: json @@ -108,7 +110,6 @@ On receipt of the test_string, the user-side client must encrypt that string wit "encrypted_string" : "" } } -.. A successful authentication will provide a reply similar to this: @@ -126,9 +127,9 @@ A successful authentication will provide a reply similar to this: "namespace": "rpc" } -.. _note: the first element of the *"args"* array is the authentication token for use later as necessary, while the second element is the number of seconds for which that token is valid. - The token is reset after every successful communication with the websocket. In this example, it is set to 5 minutes of inactivity before the token is invalidated. The websocket server is - currently set to close any connection to a client after 10 minutes of inactivity. +.. note:: the first element of the "args" array is the authentication token for use later as necessary, while the second element is the number of seconds for which that token is valid. + The token is reset after every successful communication with the websocket. In this example, it is set to 5 minutes of inactivity before the token is invalidated. The websocket server + is currently set to close any connection to a client after 10 minutes of inactivity. An invalid authentication, or a system request after the user session has timed out due to inactivity, looks like this: From 187b1cc3e31c9cffa8bc579d8248b98efcfdc90c Mon Sep 17 00:00:00 2001 From: Dru Lavigne Date: Mon, 29 Feb 2016 13:35:55 -0500 Subject: [PATCH 6/6] Fix typo. --- api/connection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/connection.rst b/api/connection.rst index 89f6c7a..77955bc 100644 --- a/api/connection.rst +++ b/api/connection.rst @@ -13,7 +13,7 @@ Add some links to docs on websockets and json.... Authentication ============== -Once a websocket connection is made to the server, the client needs to use the authentication class to authenticate itself to obtain access to the sysadm service. Every authentciation +Once a websocket connection is made to the server, the client needs to use the authentication class to authenticate itself to obtain access to the sysadm service. Every authentication class request contains the following parameters: +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+