diff --git a/doc/book/admin/access_control.rst b/doc/book/admin/access_control.rst index 18f5d82219..87408b206b 100644 --- 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 ` 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 new file mode 100644 index 0000000000..877f798985 --- /dev/null +++ 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 new file mode 100644 index 0000000000..1cef7b4fe9 --- /dev/null +++ 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 new file mode 100644 index 0000000000..1c370f7281 --- /dev/null +++ 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 new file mode 100644 index 0000000000..3c4abdba42 --- /dev/null +++ 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 new file mode 100644 index 0000000000..688b64e2fe --- /dev/null +++ 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 new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ 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 new file mode 100644 index 0000000000..692796caaa --- /dev/null +++ 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 new file mode 100644 index 0000000000..2a3e8a432d --- /dev/null +++ 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 new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ 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 new file mode 100644 index 0000000000..eb673159af --- /dev/null +++ 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 new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ 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 index 8a40e80a15..a2653fdd35 100644 --- 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 new file mode 100644 index 0000000000..916b24ba14 --- /dev/null +++ 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 `_ 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 ` 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 ` 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 ` option turns off access over remote connections from unauthenticated or :ref:`guest ` 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 ` +or update the password of an existing user with +:doc:`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 ` specifies that a password should be at least 16 characters. +- :ref:`password_enforce_lowercase ` and :ref:`password_enforce_uppercase ` specify that a password should contain lowercase and uppercase letters. +- :ref:`password_enforce_digits ` and :ref:`password_enforce_specialchars ` specify that a password should contain digits and at least one special character. +- :ref:`password_lifetime_days ` sets a maximum password age to 365 days. +- :ref:`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 `_ +protocol to authenticate users and applies ``SHA-1`` hashing to +:ref:`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 `_. + +In the Enterprise Edition, you can enable +`PAP `_ 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 ` 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 ` method generates authentication data using ``PAP-SHA256``. +For existing users, you need to reset a password using +:doc:`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 ` + 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 `: + +.. 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 index 9db4e2ecb0..eb8b48585b 100644 --- a/doc/enterprise/security.rst +++ b/doc/enterprise/security.rst @@ -15,7 +15,7 @@ initialization code. Tarantool Enterprise Edition has the following built-in security features: -* :ref:`authentication ` +* :ref:`authentication ` * :ref:`access control ` * :ref:`audit log ` * :ref:`traffic encryption ` @@ -74,301 +74,6 @@ privileges for what they create. For more information, see the :ref:`Owners and privileges ` section. -.. _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 disable access for guest users. - -The following :doc:`configuration options ` are available: - -* :ref:`auth_delay ` -* :ref:`disable_guest ` - - -.. _cfg_auth_delay: - -.. confval:: auth_delay - - Specifies a period of time (in seconds) that a specific user should wait - for the next attempt after failed authentication. - - With the configuration below, Tarantool refuses the authentication attempt if the previous - attempt was less than 5 seconds ago. - - .. code-block:: lua - - box.cfg{ auth_delay = 5 } - - - | Since version: 2.11 - | Type: number - | Default: 0 - | Environment variable: TT_AUTH_DELAY - | Dynamic: **yes** - - -.. _cfg_disable_guest: - -.. confval:: disable_guest - - If **true**, disables access over remote connections - from unauthenticated or :ref:`guest access ` users. - This option affects both - :doc:`net.box ` and - :ref:`replication ` connections. - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_DISABLE_GUEST - | Dynamic: **yes** - - - -.. _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 ` -or update the password of an existing user with -:doc:`box.schema.user.passwd `, -the password is checked against the configured password policy settings. - -The following :doc:`configuration options ` are available: - -* :ref:`password_min_length ` -* :ref:`password_enforce_uppercase ` -* :ref:`password_enforce_lowercase ` -* :ref:`password_enforce_digits ` -* :ref:`password_enforce_specialchars ` -* :ref:`password_lifetime_days ` -* :ref:`password_history_length ` - -.. _cfg_password_min_length: - -.. confval:: password_min_length - - Specifies the minimum number of characters for a password. - - The following example shows how to set the minimum password length to 10. - - .. code-block:: lua - - box.cfg{ password_min_length = 10 } - - | Since version: 2.11 - | Type: integer - | Default: 0 - | Environment variable: TT_PASSWORD_MIN_LENGTH - | Dynamic: **yes** - - -.. _cfg_password_enforce_uppercase: - -.. confval:: password_enforce_uppercase - - If **true**, a password should contain uppercase letters (A-Z). - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_PASSWORD_ENFORCE_UPPERCASE - | Dynamic: **yes** - - -.. _cfg_password_enforce_lowercase: - -.. confval:: password_enforce_lowercase - - If **true**, a password should contain lowercase letters (a-z). - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_PASSWORD_ENFORCE_LOWERCASE - | Dynamic: **yes** - - -.. _cfg_password_enforce_digits: - -.. confval:: password_enforce_digits - - If **true**, a password should contain digits (0-9). - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_PASSWORD_ENFORCE_DIGITS - | Dynamic: **yes** - - -.. _cfg_password_enforce_specialchars: - -.. confval:: password_enforce_specialchars - - If **true**, a password should contain at least one special character (such as ``&|?!@$``). - - | Since version: 2.11 - | Type: boolean - | Default: false - | Environment variable: TT_PASSWORD_ENFORCE_SPECIALCHARS - | Dynamic: **yes** - - -.. _cfg_password_lifetime_days: - -.. confval:: password_lifetime_days - - Specifies the maximum period of time (in days) a user can use the same password. - When this period ends, a user gets the "Password expired" error on a login attempt. - To restore access for such users, use :doc:`box.schema.user.passwd `. - - .. note:: - - The default 0 value means that a password never expires. - - The example below shows how to set a maximum password age to 365 days. - - .. code-block:: lua - - box.cfg{ password_lifetime_days = 365 } - - | Since version: 2.11 - | Type: integer - | Default: 0 - | Environment variable: TT_PASSWORD_LIFETIME_DAYS - | Dynamic: **yes** - - -.. _cfg_password_history_length: - -.. confval:: password_history_length - - Specifies the number of unique new user passwords before an old password can be reused. - - In the example below, a new password should differ from the last three passwords. - - .. code-block:: lua - - box.cfg{ password_history_length = 3 } - - | Since version: 2.11 - | Type: integer - | Default: 0 - | Environment variable: TT_PASSWORD_HISTORY_LENGTH - | Dynamic: **yes** - - .. note:: - Tarantool uses the ``auth_history`` field in the - :doc:`box.space._user ` - system space to store user passwords. - - - - -.. _enterprise-authentication-protocol: - -Authentication protocol -~~~~~~~~~~~~~~~~~~~~~~~ - -By default, Tarantool uses the -`CHAP `_ -protocol to authenticate users and applies ``SHA-1`` hashing to -:ref:`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 `_. - -In the Enterprise Edition, you can enable -`PAP `_ 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 ``box.cfg.auth_type`` option as follows: - -.. code-block:: lua - - box.cfg{ auth_type = 'pap-sha256' } - -| Since version: 2.11 -| Type: string -| Default value: 'chap-sha1' -| Possible values: 'chap-sha1', 'pap-sha256' -| Environment variable: TT_AUTH_TYPE -| Dynamic: **yes** - -For new users, the :doc:`box.schema.user.create ` method -will generate authentication data using ``PAP-SHA256``. -For existing users, you need to reset a password using -:doc:`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 ` - for a connection. - -The examples below show how to specify the authentication protocol on the client side: - -* For :doc:`net.box `, you can - specify the authentication protocol using the ``auth_type`` URI parameter or - the corresponding connection option: - - .. code-block:: lua - - -- URI parameters - conn = require('net.box').connect( - 'username:password@localhost:3301?auth_type=pap-sha256') - - -- URI parameters table - conn = require('net.box').connect({ - uri = 'username:password@localhost:3301', - params = {auth_type = 'pap-sha256'}, - }) - - -- Connection options - conn = require('net.box').connect('localhost:3301', { - user = 'username', - password = 'password', - auth_type = 'pap-sha256', - }) - -* For :ref:`replication configuration `, - the authentication protocol can be specified in URI parameters: - - .. code-block:: lua - - -- URI parameters - box.cfg{ - replication = { - 'replicator:password@localhost:3301?auth_type=pap-sha256', - }, - } - - -- URI parameters table - box.cfg{ - replication = { - { - uri = 'replicator:password@localhost:3301', - params = {auth_type = 'pap-sha256'}, - }, - }, - } - -If the authentication protocol isn't specified explicitly on the client side, -the client uses the protocol configured on the server via ``box.cfg.auth_type``. - - - .. _enterprise-logging: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 0f4be3a645..61dc1764fc 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -1483,3 +1483,226 @@ The ``replication`` section defines configuration parameters related to :ref:`re | Default: 1 | Environment variable: TT_REPLICATION_TIMEOUT + + +.. _configuration_reference_security: + +security +-------- + +.. admonition:: Enterprise Edition + :class: fact + + Configuring security parameters is available in the `Enterprise Edition `_ only. + +The ``security`` section defines configuration parameters related to various security settings. + +.. NOTE:: + + ``security`` can be defined in any :ref:`scope `. + +- :ref:`security.auth_delay ` +- :ref:`security.auth_retries ` +- :ref:`security.auth_type ` +- :ref:`security.disable_guest ` +- :ref:`security.password_enforce_digits ` +- :ref:`security.password_enforce_lowercase ` +- :ref:`security.password_enforce_specialchars ` +- :ref:`security.password_enforce_uppercase ` +- :ref:`security.password_history_length ` +- :ref:`security.password_lifetime_days ` +- :ref:`security.password_min_length ` +- :ref:`security.secure_erasing ` + + +.. _configuration_reference_security_auth_delay: + +.. confval:: security.auth_delay + + Specify a period of time (in seconds) that a specific user should wait for the next attempt after failed authentication. + + The :ref:`security.auth_retries ` option lets a client try to authenticate the specified number of times before ``security.auth_delay`` is enforced. + + In the configuration below, Tarantool lets a client try to authenticate with the same username three times. + At the fourth attempt, the authentication delay configured with ``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: auth_retries: 2 + :dedent: + + + | + | Type: number + | Default: 0 + | Environment variable: TT_SECURITY_AUTH_DELAY + + +.. _configuration_reference_security_auth_retries: + +.. confval:: security.auth_retries + + Specify the maximum number of authentication retries allowed before :ref:`security.auth_delay ` is enforced. + The default value is 0, which means ``security.auth_delay`` is enforced after the first failed authentication attempt. + + The retry counter is reset after ``security.auth_delay`` seconds since the first failed attempt. + For example, if a client tries to authenticate fewer than ``security.auth_retries`` times within ``security.auth_delay`` seconds, no authentication delay is enforced. + The retry counter is also reset after any successful authentication attempt. + + | + | Type: integer + | Default: 0 + | Environment variable: TT_SECURITY_AUTH_RETRIES + + +.. _configuration_reference_security_auth_type: + +.. confval:: security.auth_type + + Specify a protocol used to authenticate users. + The possible values are: + + - ``chap-sha1``: use the `CHAP `_ protocol with ``SHA-1`` hashing applied to :ref:`passwords `. + - ``pap-sha256``: use `PAP `_ authentication with the ``SHA256`` hashing algorithm. + + 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 `_. + 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 ``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: + + | + | Type: string + | Default: 'chap-sha1' + | Environment variable: TT_SECURITY_AUTH_TYPE + + +.. _configuration_reference_security_disable_guest: + +.. confval:: security.disable_guest + + If **true**, turn off access over remote connections from unauthenticated or :ref:`guest ` users. + This option affects connections between cluster members and :doc:`net.box ` connections. + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_DISABLE_GUEST + + +.. _configuration_reference_security_password_enforce_digits: + +.. confval:: security.password_enforce_digits + + If **true**, a password should contain digits (0-9). + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_PASSWORD_ENFORCE_DIGITS + + +.. _configuration_reference_security_password_enforce_lowercase: + +.. confval:: security.password_enforce_lowercase + + If **true**, a password should contain lowercase letters (a-z). + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_PASSWORD_ENFORCE_LOWERCASE + + +.. _configuration_reference_security_password_enforce_specialchars: + +.. confval:: security.password_enforce_specialchars + + If **true**, a password should contain at least one special character (such as ``&|?!@$``). + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_PASSWORD_ENFORCE_SPECIALCHARS + + +.. _configuration_reference_security_password_enforce_uppercase: + +.. confval:: security.password_enforce_uppercase + + If **true**, a password should contain uppercase letters (A-Z). + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_PASSWORD_ENFORCE_UPPERCASE + + +.. _configuration_reference_security_password_history_length: + +.. confval:: security.password_history_length + + Specify the number of unique new user passwords before an old password can be reused. + + .. NOTE:: + + Tarantool uses the ``auth_history`` field in the + :doc:`box.space._user ` + system space to store user passwords. + + | + | Type: integer + | Default: 0 + | Environment variable: TT_SECURITY_PASSWORD_HISTORY_LENGTH + + +.. _configuration_reference_security_password_lifetime_days: + +.. confval:: security.password_lifetime_days + + Specify the maximum period of time (in days) a user can use the same password. + When this period ends, a user gets the "Password expired" error on a login attempt. + To restore access for such users, use :doc:`box.schema.user.passwd `. + + .. note:: + + The default 0 value means that a password never expires. + + | + | Type: integer + | Default: 0 + | Environment variable: TT_SECURITY_PASSWORD_LIFETIME_DAYS + + +.. _configuration_reference_security_password_min_length: + +.. confval:: security.password_min_length + + Specify the minimum number of characters for a password. + + | + | Type: integer + | Default: 0 + | Environment variable: TT_SECURITY_PASSWORD_MIN_LENGTH + + +.. _configuration_reference_security_secure_erasing: + +.. confval:: security.secure_erasing + + If **true**, forces Tarantool to overwrite a data file a few times before deletion to render recovery of a deleted file impossible. + The option applies to both ``.xlog`` and ``.snap`` files as well as Vinyl data files. + + | + | Type: boolean + | Default: false + | Environment variable: TT_SECURITY_SECURE_ERASING