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/iproto_listen_address/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/config.yaml new file mode 100644 index 0000000000..dd03d061ba --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/config.yaml @@ -0,0 +1,15 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_address/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/config.yaml new file mode 100644 index 0000000000..79b0474a16 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/config.yaml @@ -0,0 +1,16 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + - uri: '127.0.0.1:3302' diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/config.yaml new file mode 100644 index 0000000000..6bfa766771 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/config.yaml @@ -0,0 +1,15 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: '3301' diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_port/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/config.yaml new file mode 100644 index 0000000000..e2bacce8bc --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/config.yaml @@ -0,0 +1,15 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: + iproto: + listen: + - uri: 'unix/:./var/run/{{ instance_name }}/tarantool.iproto' diff --git a/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/iproto_listen_socket/instances.yml @@ -0,0 +1 @@ +instance001: 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/code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml new file mode 100644 index 0000000000..69709e923b --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml @@ -0,0 +1,44 @@ +credentials: + users: + replicator: + password: 'topsecret' + roles: [replication] + +iproto: + advertise: + peer: + login: replicator + +replication: + failover: manual + +groups: + group001: + replicasets: + replicaset001: + leader: instance001 + instances: + instance001: + iproto: + listen: + - uri: '127.0.0.1:3301' + - uri: '127.0.0.1:4401' + advertise: + peer: + uri: '127.0.0.1:4401' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + - uri: '127.0.0.1:4402' + advertise: + peer: + uri: '127.0.0.1:4402' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' + - uri: '127.0.0.1:4403' + advertise: + peer: + uri: '127.0.0.1:4403' diff --git a/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/instances.yml new file mode 100644 index 0000000000..6c765b2e67 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/advertise_peer/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/README.md b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/README.md similarity index 86% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/README.md rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/README.md index cc747d8516..258232361e 100644 --- a/doc/code_snippets/snippets/replication/instances.enabled/ssl/README.md +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/README.md @@ -1,4 +1,4 @@ -# TLS traffic encryption +# SSL (with CA) A sample application demonstrating how to enable TLS traffic encryption for connections between replica set peers. @@ -7,5 +7,5 @@ A sample application demonstrating how to enable TLS traffic encryption for conn To start all instances, execute the following command in the [replication](../../../replication) directory: ```console -$ tt start ssl +$ tt start ssl_with_ca ``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/generate.sh b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/generate.sh similarity index 98% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/generate.sh rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/generate.sh index 4ceb4cc970..fe724af0e6 100644 --- a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/generate.sh +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/generate.sh @@ -26,4 +26,4 @@ cp server001.crt server001.key instance001 cp server002.crt server002.key instance002 cp server003.crt server003.key instance003 -rm -rf root_ca.key server* +rm -rf server* diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance001/server001.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.crt similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance001/server001.crt rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.crt diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance001/server001.key b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.key similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance001/server001.key rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance001/server001.key diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance002/server002.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.crt similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance002/server002.crt rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.crt diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance002/server002.key b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.key similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance002/server002.key rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance002/server002.key diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance003/server003.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.crt similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance003/server003.crt rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.crt diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance003/server003.key b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.key similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/instance003/server003.key rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/instance003/server003.key diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/root_ca.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/root_ca.crt similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/root_ca.crt rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/root_ca.crt diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/ssl_passwords.txt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/ssl_passwords.txt similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/certs/ssl_passwords.txt rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/certs/ssl_passwords.txt diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml similarity index 92% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/config.yaml rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml index 84afc46ee7..c19495d871 100644 --- a/doc/code_snippets/snippets/replication/instances.enabled/ssl/config.yaml +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml @@ -7,19 +7,17 @@ credentials: password: 'topsecret' roles: [replication] -iproto: - advertise: - peer: - login: replicator - -replication: - failover: manual - groups: group001: replicasets: replicaset001: + replication: + failover: manual leader: instance001 + iproto: + advertise: + peer: + login: replicator instances: instance001: iproto: diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/instances.yml similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/instances.yml rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/instances.yml diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl/myapp.lua b/doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/myapp.lua similarity index 100% rename from doc/code_snippets/snippets/replication/instances.enabled/ssl/myapp.lua rename to doc/code_snippets/snippets/replication/instances.enabled/ssl_with_ca/myapp.lua diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/README.md b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/README.md new file mode 100644 index 0000000000..14ad6e2937 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/README.md @@ -0,0 +1,11 @@ +# SSL (without CA) + +A sample application demonstrating how to enable TLS traffic encryption for connections between replica set peers. + +## Running + +To start all instances, execute the following command in the [replication](../../../replication) directory: + +```console +$ tt start ssl_without_ca +``` diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/generate.sh b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/generate.sh new file mode 100644 index 0000000000..877f798985 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/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/replication/instances.enabled/ssl_without_ca/certs/server.crt b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.crt new file mode 100644 index 0000000000..1cef7b4fe9 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/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/replication/instances.enabled/ssl_without_ca/certs/server.csr b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.csr new file mode 100644 index 0000000000..1c370f7281 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/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/replication/instances.enabled/ssl_without_ca/certs/server.key b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/certs/server.key new file mode 100644 index 0000000000..3c4abdba42 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/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/replication/instances.enabled/ssl_without_ca/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml new file mode 100644 index 0000000000..31343d07cf --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml @@ -0,0 +1,45 @@ +credentials: + users: + admin: + password: 'topsecret' + roles: [ super ] + replicator: + password: 'topsecret' + roles: [replication] + +groups: + group001: + replicasets: + replicaset001: + replication: + failover: manual + leader: instance001 + iproto: + advertise: + peer: + login: replicator + 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' + instance002: + iproto: + listen: + - uri: '127.0.0.1:3302' + params: + transport: 'ssl' + ssl_cert_file: 'certs/server.crt' + ssl_key_file: 'certs/server.key' + instance003: + iproto: + listen: + - uri: '127.0.0.1:3303' + params: + transport: 'ssl' + ssl_cert_file: 'certs/server.crt' + ssl_key_file: 'certs/server.key' diff --git a/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/instances.yml new file mode 100644 index 0000000000..9a634da7a0 --- /dev/null +++ b/doc/code_snippets/snippets/replication/instances.enabled/ssl_without_ca/instances.yml @@ -0,0 +1,3 @@ +instance001: +instance002: +instance003: diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index 40119a72dc..a2653fdd35 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -160,11 +160,11 @@ You can learn more about configuring replication from :ref:`Replication tutorial In the example above, the option includes ``login`` only. An URI is taken from ``iproto.listen`` that is set on the instance level. -- ``replication``: (*global*) +- ``replication`` (*global*) The ``replication.failover`` global option sets a manual failover for all replica sets. -- ``leader``: (*replica set*) +- ``leader`` (*replica set*) The ``.leader`` option sets a :ref:`master ` instance for *replicaset001*. @@ -303,7 +303,7 @@ Below are a few examples that show how to set environment variables of different The *simple* format is applicable only to maps containing scalar values. -* Array of maps. In the example below, ``TT_IPROTO_LISTEN`` is used to specify a :ref:`listening host and port ` values: +* Array of maps. In the example below, ``TT_IPROTO_LISTEN`` is used to specify a :ref:`listening host and port ` values: .. code-block:: console @@ -378,56 +378,15 @@ Connection settings ~~~~~~~~~~~~~~~~~~~ To configure an address used to listen for incoming requests, use the ``iproto.listen`` option. -Below are a few examples on how to do this: +The example below shows how to set a listening IP address for ``instance001`` to ``127.0.0.1:3301``: -* Set a listening port to ``3301``: - - .. code-block:: yaml - - iproto: - listen: - - uri: '3301' - -* Set a listening address to ``127.0.0.1:3301``: - - .. code-block:: yaml - - iproto: - listen: - - uri: '127.0.0.1:3301' - -* Configure several listening addresses: - - .. code-block:: yaml - - iproto: - listen: - - uri: '127.0.0.1:3301' - - uri: '127.0.0.1:3302' - -* Enable :ref:`traffic encryption ` for a connection using the ``params`` section of the specified URI: - - .. code-block:: yaml - - iproto: - listen: - - uri: '127.0.0.1:3301' - params: - transport: 'ssl' - ssl_ca_file: 'ca.crt' - ssl_cert_file: 'localhost.crt' - ssl_key_file: 'localhost.key' - - Note that traffic encryption is supported by the `Enterprise Edition `_ only. - - -* Use a Unix domain socket: - - .. code-block:: yaml +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_address/config.yaml + :start-at: instance001 + :end-at: '127.0.0.1:3301' + :language: yaml + :dedent: - iproto: - listen: - - uri: 'unix/:./var/run/{{ instance_name }}/tarantool.iproto' +You can learn more from the :ref:`configuration_connections` topic. .. _configuration_options_access_control: @@ -491,4 +450,6 @@ 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/concepts/configuration/configuration_connections.rst b/doc/concepts/configuration/configuration_connections.rst new file mode 100644 index 0000000000..5fbb1b0ad5 --- /dev/null +++ b/doc/concepts/configuration/configuration_connections.rst @@ -0,0 +1,299 @@ +.. _configuration_connections: + +Connections +=========== + +To set up a Tarantool cluster, you need to enable communication between its instances, regardless of whether they running on one or different hosts. +This requires :ref:`configuring ` connection settings that include: + +- One or several URIs used to listen for incoming requests. +- An URI used to advertise an instance to other cluster members. This URI lets other cluster members know how to connect to the current Tarantool instance. +- (Optional) SSL settings used to secure connections between instances. + +Configuring connection settings is also required to enable communication of a Tarantool cluster to external systems. +For example, this might be administering cluster members using :ref:`tt `, managing clusters using :ref:`Tarantool Cluster Manager `, or using :ref:`connectors ` for different languages. + +This topic describes how to define connection settings in the :ref:`iproto ` section of a YAML configuration. + +.. NOTE:: + + iproto is a :ref:`binary protocol ` used to communicate between cluster instances and with external systems. + + +.. _configuration_connections_listen_uri: + +Listen URI +---------- + +To configure URIs used to listen for incoming requests, use the :ref:`iproto.listen ` configuration option. + +.. _configuration_connections_listen_address: + +One listen address +~~~~~~~~~~~~~~~~~~ + +The example below shows how to set a listening IP address for ``instance001`` to ``127.0.0.1:3301``: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_address/config.yaml + :start-at: instance001 + :end-at: '127.0.0.1:3301' + :language: yaml + :dedent: + +.. _configuration_connections_listen_addresses: + +Multiple listen addresses +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this example, ``instance001`` listens on two IP addresses: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_addresses/config.yaml + :start-at: instance001 + :end-at: '127.0.0.1:3302' + :language: yaml + :dedent: + +.. _configuration_connections_listen_port: + +Listen port +~~~~~~~~~~~ + +You can pass only a port value to ``iproto.listen``: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_port/config.yaml + :start-at: instance001 + :end-at: '3301' + :language: yaml + :dedent: + +In this case, this port is used for all IP addresses the server listens on. + + +.. _configuration_connections_listen_ssl: + +SSL parameters +~~~~~~~~~~~~~~ + +In the Enterprise Edition, you can enable for a connection using the ``params`` section of the specified URI: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml + :language: yaml + :start-at: instance001: + :end-before: instance002: + :dedent: + +Learn more from :ref:`configuration_connections_ssl`. + + +.. _configuration_connections_unix_socket: + +Unix domain socket +~~~~~~~~~~~~~~~~~~ + +For local development, you can enable communication between cluster members by using Unix domain sockets: + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/iproto_listen_socket/config.yaml + :start-at: instance001 + :end-at: tarantool.iproto + :language: yaml + :dedent: + + + + +.. _configuration_connections_advertise: + +Advertise URI +------------- + +An advertise URI (:ref:`iproto.advertise.* `) lets other cluster members or clients know how to connect to the current Tarantool instance: + +- ``iproto.advertise.peer`` specifies how to advertise the instance to other cluster members. +- ``iproto.advertise.sharding`` specifies how to advertise the instance to a :ref:`router ` and :ref:`rebalancer `. +- ``iproto.advertise.client`` accepts a URI used to advertise the instance to clients. + +``iproto.advertise.`` might include the credentials required to connect to this instance, a URI used to listen for incoming requests, and SSL settings. + +If ``iproto.advertise..uri`` is not specified explicitly, a :ref:`listen URI ` of this instance is used. +In this case, you need at least to specify credentials for connecting to this instance. + + +.. _configuration_connections_advertise_credentials: + +Connection credentials +~~~~~~~~~~~~~~~~~~~~~~ + +In the example below, the ``iproto.advertise.peer`` option is used to inform other replica set members that the ``replicator`` user should be used to connect to the current instance: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml + :language: yaml + :start-after: roles: [replication] + :end-at: login: replicator + :dedent: + +In a sharded cluster, ``iproto.advertise.sharding`` specifies that a router and rebalancer should use the ``storage`` user to connect to storages: + +.. literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/config.yaml + :language: yaml + :start-at: iproto + :end-at: login: storage + :dedent: + + +.. _configuration_connections_advertise_explicitly: + +URI +~~~ + +If required, you can specify an advertise URI explicitly by setting up the :ref:`iproto.advertise.\.uri ` option. +In the example below, ``iproto.listen`` includes two URIs that can be used to connect to ``instance001`` but only the second one is used to advertise this instance to other replica set peers: + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/advertise_peer/config.yaml + :language: yaml + :start-at: instance001: + :end-before: instance002: + :dedent: + +The ``iproto.advertise..uri`` option can also accept an FQDN instead of an IP address: + +.. code-block:: yaml + + instance001: + iproto: + listen: + - uri: '192.168.0.101:3301' + advertise: + peer: + uri: 'server001.example.com:3301' + +To learn about the specifics of configuring an advertise URI’s SSL settings, see :ref:`configuration_connections_ssl_advertise_uri`. + + + + +.. _configuration_connections_ssl: +.. _enterprise-iproto-encryption: +.. _enterprise-iproto-encryption-config: + +Securing connections with SSL +----------------------------- + +.. admonition:: Enterprise Edition + :class: fact + + SSL is supported by the `Enterprise Edition `_ only. + +Tarantool supports the use of SSL connections to encrypt client-server communications for increased security. +To enable SSL, use the :ref:`.params.* ` options, which can be applied to both listen and advertise URIs. + + +.. _configuration_connections_ssl_without_ca: + +Without CA +~~~~~~~~~~ + +The example below demonstrates how to enable traffic encryption by using a self-signed server certificate. +The following parameters are specified for each instance: + +- :ref:`ssl_cert_file `: a path to an SSL certificate file. +- :ref:`ssl_key_file `: a path to a private SSL key file. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml + :language: yaml + :start-at: instances: + :dedent: + +You can find the full example here: `ssl_without_ca `_. + + +.. _configuration_connections_ssl_with_ca: + +With CA +~~~~~~~ + +The example below demonstrates how to enable traffic encryption by using a server certificate signed by a trusted certificate authority. +In this case, all replica set peers verify each other for authenticity. + +The following parameters are specified for each instance: + +- :ref:`ssl_ca_file `: a path to a trusted certificate authorities (CA) file. +- :ref:`ssl_cert_file `: a path to an SSL certificate file. +- :ref:`ssl_key_file `: a path to a private SSL key file. +- :ref:`ssl_password ` (``instance001``): a password for an encrypted private SSL key. +- :ref:`ssl_password_file ` (``instance002`` and ``instance003``): a text file containing passwords for encrypted SSL keys. +- :ref:`ssl_ciphers `: a colon-separated list of SSL cipher suites the connection can use. + +.. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_with_ca/config.yaml + :language: yaml + :start-at: instances: + :end-before: app: + :dedent: + +You can find the full example here: `ssl_with_ca `_. + + +.. _configuration_connections_ssl_advertise_uri: + +Advertise URI specifics +~~~~~~~~~~~~~~~~~~~~~~~ + +SSL parameters for an advertise URI should be set only if this :ref:`advertise URI is specified explicitly `. +Otherwise, SSL parameters of a listen URI are used and no additional configuration is required. + +Configuring an advertise URI's SSL options depends on whether a trusted certificate authorities (CA) file is set or not. +Without the CA file, you only need to set ``iproto.advertise..params.transport`` to ``ssl`` as shown below: + +.. code-block:: yaml + + instance001: + iproto: + listen: + - uri: '192.168.0.101:3301' + params: + transport: 'ssl' + ssl_cert_file: 'certs/server.crt' + ssl_key_file: 'certs/server.key' + advertise: + peer: + uri: 'server.example.com:3301' + params: + transport: 'ssl' + + +If the CA file is specified for a listen URI, you also need to configure ``ssl_cert_file`` and ``ssl_key_file`` for this advertise URI: + +.. code-block:: yaml + + instance001: + iproto: + listen: + - uri: '192.168.0.101:3301' + params: + transport: 'ssl' + ssl_ca_file: 'certs/root_ca.crt' + ssl_cert_file: 'certs/instance001/server001.crt' + ssl_key_file: 'certs/instance001/server001.key' + advertise: + peer: + uri: 'server001.example.com:3301' + params: + transport: 'ssl' + ssl_cert_file: 'certs/instance001/server001.crt' + ssl_key_file: 'certs/instance001/server001.key' + + + +.. _configuration_connections_ssl_reloading_certificates: + +Reloading certificates +~~~~~~~~~~~~~~~~~~~~~~ + +To reload SSL certificate files specified in the configuration, open an :ref:`admin console ` and reload the configuration using :ref:`config.reload() `: + +.. code-block:: lua + + require('config'):reload() + +New certificates will be used for new connections. +Existing connections will continue using old SSL certificates until reconnection is required. +For example, certificate expiry or a network issue causes reconnection. diff --git a/doc/enterprise/security.rst b/doc/enterprise/security.rst index ee22781975..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: @@ -408,275 +113,7 @@ For more information on logging, see the following: Access permissions to audit log files can be set up as to any other Unix file system object -- via ``chmod``. -.. _enterprise-iproto-encryption: - -Traffic encryption ------------------- - -Since version 2.10.0, Tarantool Enterprise Edition has the built-in support for using SSL to encrypt the client-server communications over :ref:`binary connections `, -that is, between Tarantool instances in a cluster or connecting to an instance via connectors using :doc:`net.box `. - -Tarantool uses the OpenSSL library that is included in the delivery package. -Please note that SSL connections use only TLSv1.2. - -.. _enterprise-iproto-encryption-config: - -Configuration -~~~~~~~~~~~~~ - -To configure traffic encryption, you need to set the special :ref:`URI parameters ` for a particular connection. -The parameters can be set for the following ``box.cfg`` options and ``nex.box`` method: - -* :ref:`box.cfg.listen ` -- on the server side. -* :ref:`box.cfg.replication `--on the client side. -* :ref:`net_box_object.connect() `--on the client side. - -Below is the list of the parameters. -In the :ref:`next section `, you can find details and examples on what should be configured on both the server side and the client side. - -* ``transport`` -- enables SSL encryption for a connection if set to ``ssl``. - The default value is ``plain``, which means the encryption is off. If the parameter is not set, the encryption is off too. - Other encryption-related parameters can be used only if the ``transport = 'ssl'`` is set. - - Example: - - .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl/myapp.lua - :language: lua - :start-at: net.box - :end-before: return connection - :dedent: - -* ``ssl_key_file`` -- a path to a private SSL key file. - Mandatory for a server. - For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. - If the private key is encrypted, provide a password for it in the ``ssl_password`` or ``ssl_password_file`` parameter. - -* ``ssl_cert_file`` -- a path to an SSL certificate file. - Mandatory for a server. - For a client, it's mandatory if the ``ssl_ca_file`` parameter is set for a server; otherwise, optional. - -* ``ssl_ca_file`` -- a path to a trusted certificate authorities (CA) file. Optional. If not set, the peer won't be checked for authenticity. - - Both a server and a client can use the ``ssl_ca_file`` parameter: - - * If it's on the server side, the server verifies the client. - * If it's on the client side, the client verifies the server. - * If both sides have the CA files, the sever and the client verify each other. - -* ``ssl_ciphers`` -- a colon-separated (``:``) list of SSL cipher suites the connection can use. See the :ref:`enterprise-iproto-encryption-ciphers` section for details. Optional. - Note that the list is not validated: if a cipher suite is unknown, Tarantool just ignores it, doesn't establish the connection and writes to the log that no shared cipher found. - -* ``ssl_password`` -- a password for an encrypted private SSL key. Optional. Alternatively, the password - can be provided in ``ssl_password_file``. - -* ``ssl_password_file`` -- a text file with one or more passwords for encrypted private SSL keys - (each on a separate line). Optional. Alternatively, the password can be provided in ``ssl_password``. - - Tarantool applies the ``ssl_password`` and ``ssl_password_file`` parameters in the following order: - - 1. If ``ssl_password`` is provided, Tarantool tries to decrypt the private key with it. - 2. If ``ssl_password`` is incorrect or isn't provided, Tarantool tries all passwords from ``ssl_password_file`` - one by one in the order they are written. - 3. If ``ssl_password`` and all passwords from ``ssl_password_file`` are incorrect, - or none of them is provided, Tarantool treats the private key as unencrypted. - -Configuration example: - -.. code-block:: lua - - box.cfg{ listen = { - uri = 'localhost:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file', - ssl_ciphers = 'HIGH:!aNULL', - ssl_password = 'topsecret' - } - }} - -.. _enterprise-iproto-encryption-ciphers: - -Supported ciphers -***************** - -Tarantool Enterprise supports the following cipher suites: - -* ECDHE-ECDSA-AES256-GCM-SHA384 -* ECDHE-RSA-AES256-GCM-SHA384 -* DHE-RSA-AES256-GCM-SHA384 -* ECDHE-ECDSA-CHACHA20-POLY1305 -* ECDHE-RSA-CHACHA20-POLY1305 -* DHE-RSA-CHACHA20-POLY1305 -* ECDHE-ECDSA-AES128-GCM-SHA256 -* ECDHE-RSA-AES128-GCM-SHA256 -* DHE-RSA-AES128-GCM-SHA256 -* ECDHE-ECDSA-AES256-SHA384 -* ECDHE-RSA-AES256-SHA384 -* DHE-RSA-AES256-SHA256 -* ECDHE-ECDSA-AES128-SHA256 -* ECDHE-RSA-AES128-SHA256 -* DHE-RSA-AES128-SHA256 -* ECDHE-ECDSA-AES256-SHA -* ECDHE-RSA-AES256-SHA -* DHE-RSA-AES256-SHA -* ECDHE-ECDSA-AES128-SHA -* ECDHE-RSA-AES128-SHA -* DHE-RSA-AES128-SHA -* AES256-GCM-SHA384 -* AES128-GCM-SHA256 -* AES256-SHA256 -* AES128-SHA256 -* AES256-SHA -* AES128-SHA -* GOST2012-GOST8912-GOST8912 -* GOST2001-GOST89-GOST89 - -Tarantool Enterprise static build has the embeded engine to support the GOST cryptographic algorithms. -If you use these algorithms for traffic encryption, specify the corresponding cipher suite in the ``ssl_ciphers`` parameter, for example: - -.. code-block:: lua - - box.cfg{ listen = { - uri = 'localhost:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file', - ssl_ciphers = 'GOST2012-GOST8912-GOST8912' - } - }} - -For detailed information on SSL ciphers and their syntax, refer to `OpenSSL documentation `__. - -Using environment variables -*************************** - -The URI parameters for traffic encryption can also be set via environment variables. For example: - -.. code-block:: bash - - export TT_LISTEN="localhost:3301?transport=ssl&ssl_cert_file=/path_to_cert_file&ssl_key_file=/path_to_key_file" - -For details, refer to the Tarantool :ref:`configuration reference `. - -.. _enterprise-iproto-encryption-config-sc: - -Server-client configuration details -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When configuring the traffic encryption, you need to specify the necessary parameters on both the server side and the client side. -Below you can find the summary on the options and parameters to be used and :ref:`examples of configuration `. - -**Server side** - -* Is configured via the ``box.cfg.listen`` option. -* Mandatory URI parameters: ``transport``, ``ssl_key_file`` and ``ssl_cert_file``. -* Optional URI parameters: ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file``. - - -**Client side** - -* Is configured via the ``box.cfg.replication`` option (see :ref:`details `) or ``net_box_object.connect()``. - -Parameters: - -* If the server side has only the ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` parameters set, - on the client side, you need to specify only ``transport = ssl`` as the mandatory parameter. - All other URI parameters are optional. - -* If the server side also has the ``ssl_ca_file`` parameter set, - on the client side, you need to specify ``transport``, ``ssl_key_file`` and ``ssl_cert_file`` as the mandatory parameters. - Other parameters -- ``ssl_ca_file``, ``ssl_ciphers``, ``ssl_password``, and ``ssl_password_file`` -- are optional. - -.. _enterprise-iproto-encryption-config-example: - -Configuration examples -********************** - -Suppose, there is a :ref:`master-replica ` set with two Tarantool instances: - -* 127.0.0.1:3301 -- master (server) -* 127.0.0.1:3302 -- replica (client). - -Examples below show the configuration related to connection encryption for two cases: -when the trusted certificate authorities (CA) file is not set on the server side and when it does. -Only mandatory URI parameters are mentioned in these examples. - -1. **Without CA** - -* 127.0.0.1:3301 -- master (server) - - .. code-block:: lua - - box.cfg{ - listen = { - uri = '127.0.0.1:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file' - } - } - } - -* 127.0.0.1:3302 -- replica (client) - - .. code-block:: lua - - box.cfg{ - listen = { - uri = '127.0.0.1:3302', - params = {transport = 'ssl'} - }, - replication = { - uri = 'username:password@127.0.0.1:3301', - params = {transport = 'ssl'} - }, - read_only = true - } - -2. **With CA** - -* 127.0.0.1:3301 -- master (server) - - .. code-block:: lua - - box.cfg{ - listen = { - uri = '127.0.0.1:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file', - ssl_ca_file = '/path_to_ca_file' - } - } - } - -* 127.0.0.1:3302 -- replica (client) - - .. code-block:: lua - box.cfg{ - listen = { - uri = '127.0.0.1:3302', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file' - } - }, - replication = { - uri = 'username:password@127.0.0.1:3301', - params = { - transport = 'ssl', - ssl_key_file = '/path_to_key_file', - ssl_cert_file = '/path_to_cert_file' - } - }, - read_only = true - } .. _enterprise-security-hardening: diff --git a/doc/how-to/getting_started_db.rst b/doc/how-to/getting_started_db.rst index c9b3159eac..5949a2732d 100644 --- a/doc/how-to/getting_started_db.rst +++ b/doc/how-to/getting_started_db.rst @@ -231,12 +231,10 @@ Each record of the array contains a required :ref:`URI ` (uniform res :ref:`params ` field. The ``iproto.listen.uri`` field may contain: -* a listening address (for example, ``127.0.0.1:3301``) +* a listening address (for example, ``127.0.0.1:3301``) * a listening port (for example, `3301`) -The field can't contain parameters, login, or password. - -Learn more about the :ref:`connection parameters `. +Learn more about the :ref:`connection parameters `. You can send requests to a Tarantool instance using: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index c676c5fca1..ccca9d8a5f 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -501,7 +501,7 @@ The ``database`` section defines database-specific configuration parameters, suc iproto ------ -The ``iproto`` section is used to configure parameters related to communicating to and between cluster instances. +The ``iproto`` section is used to configure parameters related to :ref:`communicating to and between cluster instances `. .. NOTE:: @@ -564,9 +564,8 @@ iproto.advertise.* .. confval:: iproto.advertise.peer - A URI used to advertise the current instance to other cluster members. - - The ``iproto.advertise.peer`` option accepts a URI in the format described in :ref:`iproto_advertise.\.* `. + Settings used to advertise the current instance to other cluster members. + The format of these settings is described in :ref:`iproto.advertise.\.* `. **Example** @@ -588,9 +587,12 @@ iproto.advertise.* .. confval:: iproto.advertise.sharding - An advertise URI used by a router and rebalancer. + Settings used to advertise the current instance to a router and rebalancer. + The format of these settings is described in :ref:`iproto.advertise.\.* `. + + .. NOTE:: - The ``iproto.advertise.sharding`` option accepts a URI in the format described in :ref:`iproto_advertise.\.* `. + If ``iproto.advertise.sharding`` is not specified, advertise settings from :ref:`iproto.advertise.peer ` are used. **Example** @@ -617,7 +619,7 @@ iproto.advertise..* .. _configuration_reference_iproto_advertise.peer_sharding.uri: -.. confval:: iproto_advertise..uri +.. confval:: iproto.advertise..uri (Optional) A URI used to advertise the current instance. By default, the URI defined in :ref:`iproto.listen ` is used to advertise the current instance. @@ -633,7 +635,7 @@ iproto.advertise..* .. _configuration_reference_iproto_advertise.peer_sharding.login: -.. confval:: iproto_advertise..login +.. confval:: iproto.advertise..login (Optional) A username used to connect to the current instance. If a username is not set, the ``guest`` user is used. @@ -645,7 +647,7 @@ iproto.advertise..* .. _configuration_reference_iproto_advertise.peer_sharding.password: -.. confval:: iproto_advertise..password +.. confval:: iproto.advertise..password (Optional) A password for the specified user. If a ``login`` is specified but a password is missing, it is taken from the user's :ref:`credentials `. @@ -657,7 +659,7 @@ iproto.advertise..* .. _configuration_reference_iproto_advertise.peer_sharding.params: -.. confval:: iproto_advertise..params +.. confval:: iproto.advertise..params (Optional) URI parameters (:ref:`.params.* `) required for connecting to the current instance. @@ -674,14 +676,7 @@ iproto.* An array of URIs used to listen for incoming requests. If required, you can enable SSL for specific URIs by providing additional parameters (:ref:`.params.* `). - These URIs are used for different purposes, for example: - - - Communicating between replica set peers or cluster members. See also: :ref:`iproto.advertise.* `. - - Remote administration using :ref:`tt connect `. - - Connecting to an instance using the :ref:`net.box ` module. - - Connecting to an instance using :ref:`connectors ` for different languages. - - To grant the specified privileges for connecting to an instance, use the :ref:`credentials ` configuration section. + Note that a URI value can't contain parameters, a login, or a password. **Example** @@ -693,7 +688,7 @@ iproto.* :end-before: Load sample data :dedent: - See also: :ref:`Connection settings `. + See also: :ref:`Connections `. | | Type: array @@ -714,7 +709,7 @@ iproto.* starts processing pending requests immediately. - On weaker systems, decrease ``net_msg_max``, and the overhead - may decrease. Although this may take some time because the + may decrease. However, this may take some time because the scheduler must wait until already-running requests finish. When ``net_msg_max`` is reached, @@ -788,8 +783,8 @@ iproto.* URI parameters that can be used in the following options: -- :ref:`iproto_advertise.\.params ` -- :ref:`iproto.listen ` +- :ref:`iproto.advertise.\.params ` +- :ref:`iproto.listen.\.params ` .. NOTE:: @@ -799,15 +794,8 @@ URI parameters that can be used in the following options: .. confval:: .params.transport - Allows you to enable traffic encryption for client-server communications over :ref:`binary connections `: - - - A server is a Tarantool instance. - - A client might be one of the following: - - - Another Tarantool instance from this cluster. This means that one instance might act as the server that accepts connections from other instances and the client that connects to other instances. - - A remote administrative console (:ref:`tt connect `). - - A :ref:`net.box ` connector. - - :ref:`Connectors ` provided for different languages. + Allows you to enable :ref:`traffic encryption ` for client-server communications over binary connections. + In a Tarantool cluster, one instance might act as the server that accepts connections from other instances and the client that connects to other instances. ``.params.transport`` accepts one of the following values: @@ -816,23 +804,18 @@ URI parameters that can be used in the following options: **Example** - The example below demonstrates how to enable traffic encryption for connections between replica set peers. + The example below demonstrates how to enable traffic encryption by using a self-signed server certificate. The following parameters are specified for each instance: - - ``ssl_ca_file``: a path to a trusted certificate authorities (CA) file. - ``ssl_cert_file``: a path to an SSL certificate file. - ``ssl_key_file``: a path to a private SSL key file. - - ``ssl_password`` (``instance001``): a password for an encrypted private SSL key. - - ``ssl_password_file`` (``instance002`` and ``instance003``): a text file containing passwords for encrypted SSL keys. - - ``ssl_ciphers``: a colon-separated list of SSL cipher suites the connection can use. - .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl/config.yaml + .. literalinclude:: /code_snippets/snippets/replication/instances.enabled/ssl_without_ca/config.yaml :language: yaml - :start-at: groups: - :end-before: app: + :start-at: replicaset001: :dedent: - You can find the full example here: `ssl `_. + You can find the full example here: `ssl_without_ca `_. | | Type: string @@ -1504,3 +1487,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 diff --git a/doc/reference/tooling/tcm/tcm_configuration_reference.rst b/doc/reference/tooling/tcm/tcm_configuration_reference.rst index dec444ea2d..cf16fffbb1 100644 --- a/doc/reference/tooling/tcm/tcm_configuration_reference.rst +++ b/doc/reference/tooling/tcm/tcm_configuration_reference.rst @@ -1677,7 +1677,7 @@ etcd cluster is not available or not needed. A path to a TLS private key file to use for connecting to the Tarantool |tcm| configuration storage. - See also: :ref:`Traffic encryption `. + See also: :ref:`configuration_connections_ssl`. | | Type: string @@ -1692,7 +1692,7 @@ etcd cluster is not available or not needed. A path to an SSL certificate to use for connecting to the Tarantool |tcm| configuration storage. - See also: :ref:`Traffic encryption `. + See also: :ref:`configuration_connections_ssl`. | | Type: string @@ -1707,7 +1707,7 @@ etcd cluster is not available or not needed. A path to a trusted CA certificate to use for connecting to the Tarantool |tcm| configuration storage. - See also: :ref:`Traffic encryption `. + See also: :ref:`configuration_connections_ssl`. | | Type: string @@ -1720,9 +1720,9 @@ etcd cluster is not available or not needed. .. confval:: storage.tarantool.ssl.ciphers A list of SSL cipher suites that can be used for connecting to the Tarantool |tcm| - configuration storage. Possible values are listed in :ref:`Supported ciphers `. + configuration storage. Possible values are listed in :ref:`.params.ssl_ciphers `. - See also: :ref:`Traffic encryption `. + See also: :ref:`configuration_connections_ssl`. | | Type: string @@ -1737,7 +1737,7 @@ etcd cluster is not available or not needed. A password for an encrypted private SSL key to use for connecting to the Tarantool |tcm| configuration storage. - See also: :ref:`Traffic encryption `. + See also: :ref:`configuration_connections_ssl`. | | Type: string