Authentication settings (#3991)

andreyaksenov · web-flow · commit 61651a8b6fe2 · 2024-01-18T15:38:23.000+03:00
diff --git a/doc/book/admin/access_control.rst b/doc/book/admin/access_control.rst
@@ -90,7 +90,7 @@ There are two functions for managing passwords in Tarantool:
 
 *   :doc:`/reference/reference_lua/box_schema/user_password` returns a hash of a user's password.
 
-Tarantool Enterprise Edition also allows you to improve database security by enforcing the use of strong passwords, setting up a maximum password age, and so on. Learn more from the :ref:`Access control <enterprise-access-control>` section.
+Tarantool Enterprise Edition also allows you to improve database security by enforcing the use of strong passwords, setting up a maximum password age, and so on. Learn more from the :ref:`configuration_authentication` topic.
 
 
 
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/generate.sh b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/generate.sh
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -xeuo pipefail
+
+# 1. Generate an unencrypted server key.
+openssl genrsa -out server.key 2048
+
+# 2. Create a certificate signing request based on the server key.
+openssl req -new -key server.key -subj "/C=US/ST=State/L=City/O=Example-Certificates/CN=server/" -out server.csr
+
+# 3. Generate a server certificate.
+openssl x509 -req -in server.csr -signkey server.key -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -days 365 -out server.crt
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.crt b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.crt
@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDhTCCAm2gAwIBAgIUM0cXJSowqJRoJlpwxgJBpS1V7KkwDQYJKoZIhvcNAQEL
+BQAwXDELMAkGA1UEBhMCVVMxDjAMBgNVBAgMBVN0YXRlMQ0wCwYDVQQHDARDaXR5
+MR0wGwYDVQQKDBRFeGFtcGxlLUNlcnRpZmljYXRlczEPMA0GA1UEAwwGc2VydmVy
+MCAXDTI0MDExMjE0MTc1NFoYDzIxMDAwMTAxMTQxNzU0WjBcMQswCQYDVQQGEwJV
+UzEOMAwGA1UECAwFU3RhdGUxDTALBgNVBAcMBENpdHkxHTAbBgNVBAoMFEV4YW1w
+bGUtQ2VydGlmaWNhdGVzMQ8wDQYDVQQDDAZzZXJ2ZXIwggEiMA0GCSqGSIb3DQEB
+AQUAA4IBDwAwggEKAoIBAQCekLkd2cXQfgRDBJK0LIEfzeH0C/AqQPr58qc3+A9i
+MxbPquzq/272QqAzT1YXYVHNjL0QzzE/1bt6cLcFPObd0XkDUbXQW1i2/BWI6ai3
+7FLs6qfo7MA+UQTA5a0jNrKGV1TctJae4dxxEQqnr+K2+EhbqWfS88Gf5+1kWvJq
+AyUN80Nzut7MgfAKPLEnQei7mGBk+UTo3SBNqq9RQL+AcIdl5UFSApmnzOFDCdiK
+qnw9ntIoJUIh+kAUPyNZ32aow9BBRC/9ibIBbvdsvGD7ONqewqdGC0xSa4Xx+XJn
+8lBTTFryc6D6C9KrRAV/Y7choK4Rsn2GLcnuRQ8FQifxAgMBAAGjPTA7MBoGA1Ud
+EQQTMBGCCWxvY2FsaG9zdIcEfwAAATAdBgNVHQ4EFgQU6oCAZ+kJ88rox7OFt/tr
+GIYQVFYwDQYJKoZIhvcNAQELBQADggEBABvev81NhG1DR5mS4UbpEvl6NGtcDE4H
+yVKPpI3gfdJ3etZhV2FQ7nZZzQcTaqsm2IMr336s+nb4wrqDkZJ+OhYsU1OgFF3b
+DM0BJ91YUeZz/redx7naxhawHn1BKXDvseNrH9C+XKa+1maK7bCYLkZZEtiOYZku
+yD4pfBx+A+zipas3iQdLiXDkg+qoY2OmO+9bo+tvV8zzVx7V0+8L/NU8bU2d/Dgb
+IuEPKc98hVx1W1v4RndrUmcneovbBEv82Y17RUqTi42TumsYjOjx/LvdD7RKBDZw
+XVtjKL+zwuge9rQU4sZMAwN/tHanOXAfWG6/LU5RNW87b8+YcwOxMVc=
+-----END CERTIFICATE-----
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.csr b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.csr
@@ -0,0 +1,17 @@
+-----BEGIN CERTIFICATE REQUEST-----
+MIICoTCCAYkCAQAwXDELMAkGA1UEBhMCVVMxDjAMBgNVBAgMBVN0YXRlMQ0wCwYD
+VQQHDARDaXR5MR0wGwYDVQQKDBRFeGFtcGxlLUNlcnRpZmljYXRlczEPMA0GA1UE
+AwwGc2VydmVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnpC5HdnF
+0H4EQwSStCyBH83h9AvwKkD6+fKnN/gPYjMWz6rs6v9u9kKgM09WF2FRzYy9EM8x
+P9W7enC3BTzm3dF5A1G10FtYtvwViOmot+xS7Oqn6OzAPlEEwOWtIzayhldU3LSW
+nuHccREKp6/itvhIW6ln0vPBn+ftZFryagMlDfNDc7rezIHwCjyxJ0Hou5hgZPlE
+6N0gTaqvUUC/gHCHZeVBUgKZp8zhQwnYiqp8PZ7SKCVCIfpAFD8jWd9mqMPQQUQv
+/YmyAW73bLxg+zjansKnRgtMUmuF8flyZ/JQU0xa8nOg+gvSq0QFf2O3IaCuEbJ9
+hi3J7kUPBUIn8QIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAF2jrSsrQyfET0Ux
+SEeuyJemaLp8CYGbaICDIpM5jvq43ZGDKzQWqZGgOe2QmKR4mOqe2ixr3duwjpaK
+Yd3eqQCMYkW9s5QdIs4AasQVMJXZ8uL5gIuFPtAT5BNa8GAhmpfUvHlLQeobZX4N
+NpYaZZTLvQkjqnxOU9OQfnQ/89sa5zi8+G9xgWPnu3BOBznZvWsqcIVPZAekafvd
+iP78wBWn9aF9CYrUvCmMmLgmwUe4BC3Lo4MvkosMFFH96oqrOPBztMv8swYGJBY8
+WFv1aJ8AtxpF9IGIDaP58TT0eEg/pDLGtPdaH4Q4TP9WkAs8Ybgn331xSmDDidLl
+WQFHHXY=
+-----END CERTIFICATE REQUEST-----
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.key b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/certs/server.key
@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCekLkd2cXQfgRD
+BJK0LIEfzeH0C/AqQPr58qc3+A9iMxbPquzq/272QqAzT1YXYVHNjL0QzzE/1bt6
+cLcFPObd0XkDUbXQW1i2/BWI6ai37FLs6qfo7MA+UQTA5a0jNrKGV1TctJae4dxx
+EQqnr+K2+EhbqWfS88Gf5+1kWvJqAyUN80Nzut7MgfAKPLEnQei7mGBk+UTo3SBN
+qq9RQL+AcIdl5UFSApmnzOFDCdiKqnw9ntIoJUIh+kAUPyNZ32aow9BBRC/9ibIB
+bvdsvGD7ONqewqdGC0xSa4Xx+XJn8lBTTFryc6D6C9KrRAV/Y7choK4Rsn2GLcnu
+RQ8FQifxAgMBAAECggEAM20OjK7faCImsbGe/s5cRntYZ/UjPCD9BOl88DsEij21
+jT6LPh//1eB/4oQ9kLGgfUDC5Nu9xk1EU46Q3SMGYTSZwcjTZbLqj9YsCc52SMhd
+kLb+JB38r3lJSGJ1B7GqrsVOIZJ0My1feFAlm4MAzYSyuv+zS4iA6KKorF6OtnCx
+RIvWTWrQM0yIxm8HBpNu1hFLqr7QV57u18pz6zSnBTd5VTYivQQkv7JWR5ci2Hry
+4yjVfwwh8Xcm8i8S+BZZ1hsVrVsoKmjMyqbj/Lrnx4/MsfCG3WQOL/ZP38w+z+Ds
+XptopV3/ZKC8Dnyf3x7HyJ0uDGD0fAzxtdCslk3TrQKBgQC1nzyDX2i/uZlhK+3T
+Nkj1LFakANY8yIY3AfPVJROuA+KERAkuTJfRfSxDUkE9QJyxy0S2DUSq2pOov33Q
+6NH0wNEjCFRoXGqCgkNPbwECwJtKQWwsrHHpZZCINH7TyWCUi9p4tcAzww7UyUDT
+JiJP7iOvxMCB8ebNca6rQ0xI+wKBgQDfgEj+PI8kXCP4qk2xcVJ+yOkwoSWoBS0s
+KBV5pGgbO12NPDHal5ZWLpCZMi3Cw0gObEj5mYbcj+fkmk9xKhuxtfo4DQaAP5y4
+VnoXsaAwryLqG/iby3zAFkspN+5hoD8hmDXHrqrqC7AOmPrrAHIQHdt11TCBheEY
+UuK+xrBXAwKBgE/+R4fRQPCYzW5YC9KoKTAbDDoFyFZTN5IIwR1SzD0rptv8n1KO
+F5wEFre8BdH1oE5KqgPJCkJ6LOj5FnAp6zdyqWpVo9+nPJ4ow3679GUC8iKdeAih
+FzbmLedfv7CGFIy4oEvkOThTJDgiP/P/6sLrrzoeXW+eXLqF5Jm39WR7AoGAYqSf
+Er6turGEGtMneUJ304dfDFyDXzXxqwSB/e8nF6XK83P22PCApMbmgQbZlZVU7zCx
+wKAXGq/U/Fty5pJcKMIVjrmI/f+VbvKT7nMyLWqO8V6pCjH0fF8aizWpW6M7Wdtx
+GRGpU6UW7kpsrF3E+gIDg201fGUXZQHoG6Vb3PsCgYBRgDDKXXD0dKqU9GzO/og7
+WpJOZqI+OZoG778aP2HqQ8z9m93nQ0NTzXK8rRNDSEbd+QFFf9s5Y5gjjK5bsNUJ
+mDziJ7B8tP2ecLcuO5DF2ro9nCPPYNixViKqZ1oJAFEIFetZzp7ZB6PFf7tcnXJ3
+aqTpCZBW2gL5iktwXYz+DA==
+-----END PRIVATE KEY-----
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml
@@ -0,0 +1,25 @@
+credentials:
+  users:
+    admin:
+      password: 'topsecret'
+      roles: [ super ]
+
+security:
+  auth_type: 'pap-sha256'
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3301'
+                params:
+                  transport: 'ssl'
+                  ssl_cert_file: 'certs/server.crt'
+                  ssl_key_file: 'certs/server.key'
+
+app:
+  file: 'myapp.lua'
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/security_auth_protocol/myapp.lua
@@ -0,0 +1,10 @@
+function connect()
+    local connection = require('net.box').connect({
+        uri = 'admin:topsecret@127.0.0.1:3301',
+        params = { auth_type = 'pap-sha256',
+                   transport = 'ssl',
+                   ssl_cert_file = 'certs/server.crt',
+                   ssl_key_file = 'certs/server.key' }
+    })
+    return connection
+end
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml
@@ -0,0 +1,20 @@
+credentials:
+  users:
+    admin:
+      password: 'topsecret'
+      roles: [ super ]
+
+security:
+  auth_delay: 10
+  auth_retries: 2
+  disable_guest: true
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3301'
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/security_auth_restrictions/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/config.yaml
@@ -0,0 +1,24 @@
+credentials:
+  users:
+    admin:
+      password: 'T0p_Secret_P@$$w0rd'
+      roles: [ super ]
+
+security:
+  password_min_length: 16
+  password_enforce_lowercase: true
+  password_enforce_uppercase: true
+  password_enforce_digits: true
+  password_enforce_specialchars: true
+  password_lifetime_days: 365
+  password_history_length: 3
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3301'
diff --git a/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/security_password_policy/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst
@@ -451,4 +451,5 @@ To learn more about the persistence mechanism in Tarantool, see the :ref:`Persis
     configuration/configuration_etcd
     configuration/configuration_code
     configuration/configuration_connections
+    configuration/configuration_authentication
     .. configuration/configuration_migrating
diff --git a/doc/concepts/configuration/configuration_authentication.rst b/doc/concepts/configuration/configuration_authentication.rst
@@ -0,0 +1,110 @@
+..  _configuration_authentication:
+
+Authentication
+==============
+
+..  admonition:: Enterprise Edition
+    :class: fact
+
+    Authentication features are supported by the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
+
+.. _enterprise-auth-restrictions:
+
+Authentication restrictions
+---------------------------
+
+Tarantool Enterprise Edition provides the ability to apply additional restrictions for user authentication.
+For example, you can specify the minimum time between authentication attempts
+or turn off access for guest users.
+
+In the configuration below, :ref:`security.auth_retries <configuration_reference_security_auth_retries>` is set to ``2``,
+which means that Tarantool lets a client try to authenticate with the same username three times.
+At the fourth attempt, the authentication delay configured with :ref:`security.auth_delay <configuration_reference_security_auth_delay>` is enforced.
+This means that a client should wait 10 seconds after the first failed attempt.
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_restrictions/config.yaml
+    :language: yaml
+    :start-at: security:
+    :end-at: disable_guest
+    :dedent:
+
+The :ref:`disable_guest <configuration_reference_security_disable_guest>` option turns off access over remote connections from unauthenticated or :ref:`guest <authentication-passwords>` users.
+
+
+.. _enterprise-password-policy:
+
+Password policy
+---------------
+
+A password policy allows you to improve database security by enforcing the use
+of strong passwords, setting up a maximum password age, and so on.
+When you create a new user with
+:doc:`box.schema.user.create </reference/reference_lua/box_schema/user_create>`
+or update the password of an existing user with
+:doc:`box.schema.user.passwd </reference/reference_lua/box_schema/user_passwd>`,
+the password is checked against the configured password policy settings.
+
+In the example below, the following options are specified:
+
+-   :ref:`password_min_length <configuration_reference_security_password_min_length>` specifies that a password should be at least 16 characters.
+-   :ref:`password_enforce_lowercase <configuration_reference_security_password_enforce_lowercase>` and :ref:`password_enforce_uppercase <configuration_reference_security_password_enforce_uppercase>` specify that a password should contain lowercase and uppercase letters.
+-   :ref:`password_enforce_digits <configuration_reference_security_password_enforce_digits>` and :ref:`password_enforce_specialchars <configuration_reference_security_password_enforce_specialchars>` specify that a password should contain digits and at least one special character.
+-   :ref:`password_lifetime_days <configuration_reference_security_password_lifetime_days>` sets a maximum password age to 365 days.
+-   :ref:`password_history_length <configuration_reference_security_password_history_length>` specifies that a new password should differ from the last three passwords.
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/security_password_policy/config.yaml
+    :language: yaml
+    :start-at: security:
+    :end-at: password_history_length
+    :dedent:
+
+
+
+
+.. _enterprise-authentication-protocol:
+
+Authentication protocol
+-----------------------
+
+By default, Tarantool uses the
+`CHAP <https://en.wikipedia.org/wiki/Challenge-Handshake_Authentication_Protocol>`_
+protocol to authenticate users and applies ``SHA-1`` hashing to
+:ref:`passwords <authentication-passwords>`.
+Note that CHAP stores password hashes in the ``_user`` space unsalted.
+If an attacker gains access to the database, they may crack a password, for example, using a `rainbow table <https://en.wikipedia.org/wiki/Rainbow_table>`_.
+
+In the Enterprise Edition, you can enable
+`PAP <https://en.wikipedia.org/wiki/Password_Authentication_Protocol>`_ authentication
+with the ``SHA256`` hashing algorithm.
+For PAP, a password is salted with a user-unique salt before saving it in the database,
+which keeps the database protected from cracking using a rainbow table.
+
+To enable PAP, specify the :ref:`security.auth_type <configuration_reference_security_auth_type>` option as follows:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_protocol/config.yaml
+    :language: yaml
+    :start-at: security:
+    :end-at: pap-sha256
+    :dedent:
+
+For new users, the :doc:`box.schema.user.create </reference/reference_lua/box_schema/user_create>` method generates authentication data using ``PAP-SHA256``.
+For existing users, you need to reset a password using
+:doc:`box.schema.user.passwd </reference/reference_lua/box_schema/user_passwd>`
+to use the new authentication protocol.
+
+.. warning::
+
+    Given that ``PAP`` transmits a password as plain text,
+    Tarantool requires configuring :ref:`SSL/TLS <configuration_connections_ssl>`
+    for a connection.
+
+The example below shows how to specify the authentication protocol using the ``auth_type`` parameter when connecting to an instance using :doc:`net.box </reference/reference_lua/net_box>`:
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/security_auth_protocol/myapp.lua
+    :language: lua
+    :start-at: local connection
+    :end-before: return connection
+    :dedent:
+
+If the authentication protocol isn't specified explicitly on the client side,
+the client uses the protocol configured on the server via ``security.auth_type``.
diff --git a/doc/enterprise/security.rst b/doc/enterprise/security.rst
diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst

Original file line number	Diff line number	Diff line change
`@@ -90,7 +90,7 @@ There are two functions for managing passwords in Tarantool:`
`90`	`90`
`91`	`91`	* :doc:`/reference/reference_lua/box_schema/user_password` returns a hash of a user's password.
`92`	`92`
`93`		-Tarantool Enterprise Edition also allows you to improve database security by enforcing the use of strong passwords, setting up a maximum password age, and so on. Learn more from the :ref:`Access control <enterprise-access-control>` section.
	`93`	+Tarantool Enterprise Edition also allows you to improve database security by enforcing the use of strong passwords, setting up a maximum password age, and so on. Learn more from the :ref:`configuration_authentication` topic.
`94`	`94`
`95`	`95`
`96`	`96`