[#1304] Updated CA doc

diff --git a/doc/sphinx/arm/agent.rst b/doc/sphinx/arm/agent.rst
index 51bd64aae0a6e54eee42e0291d025cf57058c254..37c215a12abff97edf3e6d33f171c9f40d8d034d 100644 (file)
--- a/doc/sphinx/arm/agent.rst
+++ b/doc/sphinx/arm/agent.rst
@@ -50,6 +50,7 @@ The following example demonstrates the basic CA configuration.
        "Control-agent": {
            "http-host": "10.20.30.40",
            "http-port": 8000,
+           "basic-authentication-realm": "kea-control-agent",
 
            "control-sockets": {
                "dhcp4": {
@@ -68,6 +69,12 @@ The following example demonstrates the basic CA configuration.
                },
            },
 
+           "basic-authentications": [
+           {
+               "user": "admin",
+               "password": "1234"
+           } ],
+
            "hooks-libraries": [
            {
                "library": "/opt/local/control-agent-commands.so",
@@ -125,10 +132,32 @@ formatting; please consult the relevant hook library documentation for
 details.
 
 User contexts can be specified on either global scope, control socket,
-or loggers. One other useful feature is the ability to store comments or
-descriptions; the parser translates a "comment" entry into a user
-context with the entry, which allows a comment to be attached within the
-configuration itself.
+basic authentication, or loggers. One other useful feature is the
+ability to store comments or descriptions; the parser translates a
+"comment" entry into a user context with the entry, which allows a
+comment to be attached within the configuration itself.
+
+The basic HTTP authentication was added by Kea 1.7.10. It protects
+not authorized uses of the control agent by local users. For the
+protection against remote attackers HTTPS and reverse proxy of
+:ref:`agent-secure-connection` provide a stronger security.
+
+The ``basic-authentication-realm`` is used for error message when
+the basic HTTP authentication is mandatory but the client is not
+authorized.
+
+When the ``basic-authentications`` list is configured and not empty
+the basic HTTP authentication is required. Each element of the list
+specifies a user id and a password. The user id is mandatory, must
+be not empty and must not contain the colon (:) character. The
+password is optional: when it is not specified an empty password
+is used.
+
+.. note::
+
+   The basic HTTP authentication user id and password are encoded
+   in UTF-8 but the current Kea JSON syntax only supports the latin-1
+   (i.e. 0x00..0xff) unicode subset.
 
 Hooks libraries can be loaded by the Control Agent in the same way as
 they are loaded by the DHCPv4 and DHCPv6 servers. The CA currently
@@ -151,7 +180,7 @@ The Control Agent does not natively support secure HTTP connections like
 SSL or TLS. In order to setup a secure connection, please use one of the
 available third-party HTTP servers and configure it to run as a reverse
 proxy to the Control Agent. Kea has been tested with two major HTTP
-server implentations working as a reverse proxy: Apache2 and nginx.
+server implementations working as a reverse proxy: Apache2 and nginx.
 Example configurations, including extensive comments, are provided in
 the ``doc/examples/https/`` directory.
 
@@ -205,6 +234,7 @@ server enables authentication of the clients using certificates.
    #        -H Content-Type:application/json -d '{ "command": "list-commands" }' \
    #         https://kea.example.org/kea
    #
+   #   curl syntax for basic authentication is -u user:password
    #
    #
    #   nginx configuration starts here.

diff --git a/doc/sphinx/arm/shell.rst b/doc/sphinx/arm/shell.rst
index 75ba6a543d0d440841da06b9c638c9793bacf505..9380a316aaf6c09dba553345a258e6ac4636bfa2 100644 (file)
--- a/doc/sphinx/arm/shell.rst
+++ b/doc/sphinx/arm/shell.rst
@@ -22,6 +22,8 @@ As the primary purpose of the Kea shell is as a tool in a scripting
 environment, it is not interactive. However, following simple guidelines it can
 be run manually.
 
+Kea 1.7.10 introduced basic HTTP authentication support.
+
 Shell Usage
 ===========
 
@@ -29,7 +31,7 @@ Shell Usage
 
 .. code-block:: console
 
-   $ kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [--service service-name] [command]
+   $ kea-shell [--host hostname] [--port number] [--path path] [--auth-user] [--auth-password] [--timeout seconds] [--service service-name] [command]
 
 where:
 
@@ -43,6 +45,13 @@ where:
    specified, an empty path is used. As the CA listens at the empty
    path, this parameter is useful only with a reverse proxy.
 
+-  ``--auth-user`` specifies the user id for basic HTTP authentication.
+   If not specified or specified as the empty string authentication is
+   not used.
+
+- ``--auth-password`` specifies the password for basic HTTP authentication.
+   If not specified but the user id is specified an empty password is used.
+
 -  ``--timeout seconds`` specifies the timeout (in seconds) for the
    connection. If not given, 10 seconds is used.
 

diff --git a/doc/sphinx/man/kea-shell.8.rst b/doc/sphinx/man/kea-shell.8.rst
index fb88cdc419776c64750ea783091df61f3ecc7d11..2fe12ee410e017499bed3dafe33088ffa8d4f12a 100644 (file)
--- a/doc/sphinx/man/kea-shell.8.rst
+++ b/doc/sphinx/man/kea-shell.8.rst
@@ -51,12 +51,12 @@ The arguments are as follows:
    parameter is useful only with a reverse proxy.
 
 ``--auth-user``
-   Specifies the user name for basic HTTP authentication. If not specified
+   Specifies the user id for basic HTTP authentication. If not specified
    or specified as the empty string authentication is not used.
 
 ``--auth-password``
    Specifies the password for basic HTTP authentication. If not specified
-   but the user name is specified an empty password is used.
+   but the user id is specified an empty password is used.
 
 ``--timeout``
    Specifies the connection timeout in seconds. If not specified, 10

diff --git a/src/bin/shell/kea-shell.rst b/src/bin/shell/kea-shell.rst
index 6a721f96998d724447d845ac6cdd7e89ed2658d4..b10483f97e2759cb1482eeaf7bfcff64092d5de2 100644 (file)
--- a/src/bin/shell/kea-shell.rst
+++ b/src/bin/shell/kea-shell.rst
@@ -50,12 +50,12 @@ The arguments are as follows:
    parameter is useful only with a reverse proxy.
 
 ``--auth-user``
-   Specifies the user name for basic HTTP authentication. If not specified
+   Specifies the user id for basic HTTP authentication. If not specified
    or specified as the empty string authentication is not used.
 
 ``--auth-password``
    Specifies the password for basic HTTP authentication. If not specified
-   but the user name is specified an empty password is used.
+   but the user id is specified an empty password is used.
 
 ``--timeout``
    Specifies the connection timeout in seconds. If not specified, 10