doc: add chapter about secured data in user's guide

6 files changed, 513 insertions, 3 deletions

diff --git a/doc/de/weechat_user.de.txt b/doc/de/weechat_user.de.txt
index 977acb5e0..9cc7cedb4 100644
--- a/doc/de/weechat_user.de.txt
+++ b/doc/de/weechat_user.de.txt
@@ -1483,6 +1483,90 @@ Um der Vordergrundfarbe des Terminals das Attribut "fett" zuzuordnen:
 /set weechat.color.status_time *99999
 ----
 
+// TRANSLATION MISSING
+[[secured_data]]
+=== Secured data
+
+[[secured_data_storage]]
+==== Storage
+
+WeeChat can encrypt passwords or private data using secured data, stored in file
+'sec.conf'.
+
+This configuration file is read before any other file, and the values stored
+inside can be used in various WeeChat or plugins/scripts options.
+
+You can set a passphrase to encrypt data in 'sec.conf'. This is not mandatory
+but highly recommended, otherwise data is stored as plain text in file.
+
+----
+/secure passphrase this is my passphrase
+----
+
+When a passphrase is set, WeeChat will ask you to enter it on startup (but not
+on `/upgrade`).
+
+You can change this behavior and use a file with the passphrase (see option
+<<option_sec.crypt.passphrase_file,sec.crypt.passphrase_file>>).
+
+[[secured_data_encryption]]
+===== Encryption
+
+The encryption of data is made in 3 steps:
+
+. Derive a key from the passphrase (with optional salt).
+. Compute hash of data to encrypt.
+. Encrypt the hash + data (output is: salt + encrypted hash/data).
+
+[NOTE]
+The cipher block mode is 'CFB'.
+
+The result is put as hexadecimal string in file 'sec.conf', for example:
+
+----
+[data]
+__passphrase__ = on
+freenode = "53B1C86FCDA28FC122A95B0456ABD79B5AB74654F21C3D099A6CCA8173239EEA59533A1D83011251F96778AC3F5166A394"
+----
+
+[[secured_data_decryption]]
+===== Decryption
+
+The decryption of data is made in 3 steps:
+
+. Derive a key using salt and passphrase.
+. Decrypt hash + data.
+. Check that decrypted hash == hash of data.
+
+[[secured_data_manage]]
+==== Manage secured data
+
+To add secured data, use `/secure set`, for example a password for 'freenode'
+IRC server:
+
+----
+/secure set freenode mypassword
+----
+
+For comfort, secured data can be displayed in a dedicated buffer (key[alt-v] on
+buffer to see values), just do:
+
+----
+/secure
+----
+
+Secured data can be used in some options that can contain private data like
+password, using this format: "${sec.data.xxx}" where "xxx" is the name of
+secured data (used with `/secure set xxx ...`). +
+For a complete list of supported options, see `/help secure`.
+
+To use the 'freenode' password, for example with
+<<irc_sasl_authentication,SASL authentication>>:
+
+----
+/set irc.server.freenode.sasl_password "${sec.data.freenode}"
+----
+
 [[options_and_commands]]
 === Optionen und Befehle
 
diff --git a/doc/en/weechat_user.en.txt b/doc/en/weechat_user.en.txt
index 28053323c..d6087579f 100644
--- a/doc/en/weechat_user.en.txt
+++ b/doc/en/weechat_user.en.txt
@@ -1458,6 +1458,89 @@ Example of bold with terminal foreground color:
 /set weechat.color.status_time *99999
 ----
 
+[[secured_data]]
+=== Secured data
+
+[[secured_data_storage]]
+==== Storage
+
+WeeChat can encrypt passwords or private data using secured data, stored in file
+'sec.conf'.
+
+This configuration file is read before any other file, and the values stored
+inside can be used in various WeeChat or plugins/scripts options.
+
+You can set a passphrase to encrypt data in 'sec.conf'. This is not mandatory
+but highly recommended, otherwise data is stored as plain text in file.
+
+----
+/secure passphrase this is my passphrase
+----
+
+When a passphrase is set, WeeChat will ask you to enter it on startup (but not
+on `/upgrade`).
+
+You can change this behavior and use a file with the passphrase (see option
+<<option_sec.crypt.passphrase_file,sec.crypt.passphrase_file>>).
+
+[[secured_data_encryption]]
+===== Encryption
+
+The encryption of data is made in 3 steps:
+
+. Derive a key from the passphrase (with optional salt).
+. Compute hash of data to encrypt.
+. Encrypt the hash + data (output is: salt + encrypted hash/data).
+
+[NOTE]
+The cipher block mode is 'CFB'.
+
+The result is put as hexadecimal string in file 'sec.conf', for example:
+
+----
+[data]
+__passphrase__ = on
+freenode = "53B1C86FCDA28FC122A95B0456ABD79B5AB74654F21C3D099A6CCA8173239EEA59533A1D83011251F96778AC3F5166A394"
+----
+
+[[secured_data_decryption]]
+===== Decryption
+
+The decryption of data is made in 3 steps:
+
+. Derive a key using salt and passphrase.
+. Decrypt hash + data.
+. Check that decrypted hash == hash of data.
+
+[[secured_data_manage]]
+==== Manage secured data
+
+To add secured data, use `/secure set`, for example a password for 'freenode'
+IRC server:
+
+----
+/secure set freenode mypassword
+----
+
+For comfort, secured data can be displayed in a dedicated buffer (key[alt-v] on
+buffer to see values), just do:
+
+----
+/secure
+----
+
+Secured data can be used in some options that can contain private data like
+password, using this format: "${sec.data.xxx}" where "xxx" is the name of
+secured data (used with `/secure set xxx ...`). +
+For a complete list of supported options, see `/help secure`.
+
+To use the 'freenode' password, for example with
+<<irc_sasl_authentication,SASL authentication>>:
+
+----
+/set irc.server.freenode.sasl_password "${sec.data.freenode}"
+----
+
 [[options_and_commands]]
 === Options and commands
 
@@ -2457,7 +2540,7 @@ include::autogen/user/relay_commands.txt[]
 It is highly recommended to set a password for relay, with command:
 
 ----
-/set relay.network.password "mypass"
+/set relay.network.password "mypassword"
 ----
 
 This password is used for 'irc' and 'weechat' protocols.
@@ -2514,7 +2597,7 @@ Example: IRC proxy without SSL only for server "freenode":
 ----
 
 Now you can connect on port 8000 with any IRC client using server password
-"mypass" (or "freenode:mypass" if no server was specified in the relay).
+"mypassword" (or "freenode:mypassword" if no server was specified in the relay).
 
 [[relay_weechat_protocol]]
 ==== WeeChat protocol
@@ -2534,7 +2617,7 @@ For example:
 ----
 
 Now you can connect on port 9000 with a remote interface using password
-"mypass".
+"mypassword".
 
 [[relay_websocket]]
 ==== WebSocket
diff --git a/doc/fr/weechat_user.fr.txt b/doc/fr/weechat_user.fr.txt
index fb2b0d90b..9dd81e576 100644
--- a/doc/fr/weechat_user.fr.txt
+++ b/doc/fr/weechat_user.fr.txt
@@ -1500,6 +1500,97 @@ Exemple de gras avec la couleur de texte du terminal :
 /set weechat.color.status_time *99999
 ----
 
+[[secured_data]]
+=== Données sécurisées
+
+[[secured_data_storage]]
+==== Stockage
+
+WeeChat peut chiffrer les mots de passe ou les données sensibles en utilisant
+des données sécurisées, stockées dans le fichier 'sec.conf'.
+
+Ce fichier de configuration est lu avant tout autre fichier, et les valeurs
+ici stockées peuvent être utilisées dans diverses options de WeeChat ou des
+extensions/scripts.
+
+Vous pouvez définir une phrase secrète pour chiffrer les données dans le fichier
+'sec.conf'. Ce n'est pas obligatoire, mais fortement recommandé, sinon les
+données sont stockées sous forme de texte en clair dans le fichier.
+
+----
+/secure passphrase ceci est ma phrase secrète
+----
+
+Lorsqu'une phrase secrète est définie, WeeChat vous demandera de la saisir lors
+du démarrage (mais pas sur `/upgrade`).
+
+Vous pouvez modifier ce comportement et utiliser un fichier avec la phrase
+secrète (voir l'option
+<<option_sec.crypt.passphrase_file,sec.crypt.passphrase_file>>).
+
+[[secured_data_encryption]]
+===== Chiffrement
+
+Le chiffrement des données se fait en 3 étapes :
+
+. Dériver une clé de la phrase secrète (avec du salage en option).
+. Calculer la somme de contrôle des données à chiffrer.
+. Chiffrer la seomme de contrôle + les données (la sortie est : sel + somme de
+  contrôle et données chiffrées).
+
+[NOTE]
+Le mode de chiffrement par bloc est 'CFB'.
+
+Le résultat est stocké sous forme d'une chaîne hexadécimale dans le fichier
+'sec.conf', par exemple :
+
+----
+[data]
+__passphrase__ = on
+freenode = "53B1C86FCDA28FC122A95B0456ABD79B5AB74654F21C3D099A6CCA8173239EEA59533A1D83011251F96778AC3F5166A394"
+----
+
+[[secured_data_decryption]]
+===== Déchiffrement
+
+Le déchiffrement des données se fait en 3 étapes :
+
+. Dériver une clé en utilisant le sel et la phrase secrète.
+. Déchiffrer la somme de contrôle et les données.
+. Vérifier que la somme de contrôle déchiffrée correspond à la somme de contrôle
+  des données.
+
+[[secured_data_manage]]
+==== Gérer les données sécurisées
+
+Pour ajouter une donnée sécurisée, utilisez la commande `/secure set`, par
+exemple un mot de passe pour le serveur IRC 'freenode' :
+
+----
+/secure set freenode motdepasse
+----
+
+Pour plus de confort, les données sécurisées peuvent être affichées dans un
+tampon dédié (touche key[alt-v] sur le tampon pour voir les valeurs), faites
+simplement :
+
+----
+/secure
+----
+
+Les données sécurisées peuvent être utilisées dans quelques options qui peuvent
+contenir des données sensibles comme un mot de passe, en utilisant ce format :
+"${sec.data.xxx}" où "xxx" est le nom de la donnée sécurisée (utilisé dans la
+commande `/secure set xxx ...`). +
+Pour une liste complète des options supportées, voir `/help secure`.
+
+Pour utiliser le mot de passe 'freenode', par exemple avec
+<<irc_sasl_authentication,l'authentification SASL>>:
+
+----
+/set irc.server.freenode.sasl_password "${sec.data.freenode}"
+----
+
 [[options_and_commands]]
 === Options et commandes
 
diff --git a/doc/it/weechat_user.it.txt b/doc/it/weechat_user.it.txt
index 3cdbe9632..b0c335ac2 100644
--- a/doc/it/weechat_user.it.txt
+++ b/doc/it/weechat_user.it.txt
@@ -1512,6 +1512,90 @@ Esempio di grassetto con il colore di primo piano del terminale:
 ----
 
 // TRANSLATION MISSING
+[[secured_data]]
+=== Secured data
+
+[[secured_data_storage]]
+==== Storage
+
+WeeChat can encrypt passwords or private data using secured data, stored in file
+'sec.conf'.
+
+This configuration file is read before any other file, and the values stored
+inside can be used in various WeeChat or plugins/scripts options.
+
+You can set a passphrase to encrypt data in 'sec.conf'. This is not mandatory
+but highly recommended, otherwise data is stored as plain text in file.
+
+----
+/secure passphrase this is my passphrase
+----
+
+When a passphrase is set, WeeChat will ask you to enter it on startup (but not
+on `/upgrade`).
+
+You can change this behavior and use a file with the passphrase (see option
+<<option_sec.crypt.passphrase_file,sec.crypt.passphrase_file>>).
+
+[[secured_data_encryption]]
+===== Encryption
+
+The encryption of data is made in 3 steps:
+
+. Derive a key from the passphrase (with optional salt).
+. Compute hash of data to encrypt.
+. Encrypt the hash + data (output is: salt + encrypted hash/data).
+
+[NOTE]
+The cipher block mode is 'CFB'.
+
+The result is put as hexadecimal string in file 'sec.conf', for example:
+
+----
+[data]
+__passphrase__ = on
+freenode = "53B1C86FCDA28FC122A95B0456ABD79B5AB74654F21C3D099A6CCA8173239EEA59533A1D83011251F96778AC3F5166A394"
+----
+
+[[secured_data_decryption]]
+===== Decryption
+
+The decryption of data is made in 3 steps:
+
+. Derive a key using salt and passphrase.
+. Decrypt hash + data.
+. Check that decrypted hash == hash of data.
+
+[[secured_data_manage]]
+==== Manage secured data
+
+To add secured data, use `/secure set`, for example a password for 'freenode'
+IRC server:
+
+----
+/secure set freenode mypassword
+----
+
+For comfort, secured data can be displayed in a dedicated buffer (key[alt-v] on
+buffer to see values), just do:
+
+----
+/secure
+----
+
+Secured data can be used in some options that can contain private data like
+password, using this format: "${sec.data.xxx}" where "xxx" is the name of
+secured data (used with `/secure set xxx ...`). +
+For a complete list of supported options, see `/help secure`.
+
+To use the 'freenode' password, for example with
+<<irc_sasl_authentication,SASL authentication>>:
+
+----
+/set irc.server.freenode.sasl_password "${sec.data.freenode}"
+----
+
+// TRANSLATION MISSING
 [[options_and_commands]]
 === Options and commands
 
diff --git a/doc/ja/weechat_user.ja.txt b/doc/ja/weechat_user.ja.txt
index 923a229b5..6dedd9427 100644
--- a/doc/ja/weechat_user.ja.txt
+++ b/doc/ja/weechat_user.ja.txt
@@ -1458,6 +1458,90 @@ WeeChat はスクリーンに色が表示された時点で色ペアを動的に
 /set weechat.color.status_time *99999
 ----
 
+// TRANSLATION MISSING
+[[secured_data]]
+=== Secured data
+
+[[secured_data_storage]]
+==== Storage
+
+WeeChat can encrypt passwords or private data using secured data, stored in file
+'sec.conf'.
+
+This configuration file is read before any other file, and the values stored
+inside can be used in various WeeChat or plugins/scripts options.
+
+You can set a passphrase to encrypt data in 'sec.conf'. This is not mandatory
+but highly recommended, otherwise data is stored as plain text in file.
+
+----
+/secure passphrase this is my passphrase
+----
+
+When a passphrase is set, WeeChat will ask you to enter it on startup (but not
+on `/upgrade`).
+
+You can change this behavior and use a file with the passphrase (see option
+<<option_sec.crypt.passphrase_file,sec.crypt.passphrase_file>>).
+
+[[secured_data_encryption]]
+===== Encryption
+
+The encryption of data is made in 3 steps:
+
+. Derive a key from the passphrase (with optional salt).
+. Compute hash of data to encrypt.
+. Encrypt the hash + data (output is: salt + encrypted hash/data).
+
+[NOTE]
+The cipher block mode is 'CFB'.
+
+The result is put as hexadecimal string in file 'sec.conf', for example:
+
+----
+[data]
+__passphrase__ = on
+freenode = "53B1C86FCDA28FC122A95B0456ABD79B5AB74654F21C3D099A6CCA8173239EEA59533A1D83011251F96778AC3F5166A394"
+----
+
+[[secured_data_decryption]]
+===== Decryption
+
+The decryption of data is made in 3 steps:
+
+. Derive a key using salt and passphrase.
+. Decrypt hash + data.
+. Check that decrypted hash == hash of data.
+
+[[secured_data_manage]]
+==== Manage secured data
+
+To add secured data, use `/secure set`, for example a password for 'freenode'
+IRC server:
+
+----
+/secure set freenode mypassword
+----
+
+For comfort, secured data can be displayed in a dedicated buffer (key[alt-v] on
+buffer to see values), just do:
+
+----
+/secure
+----
+
+Secured data can be used in some options that can contain private data like
+password, using this format: "${sec.data.xxx}" where "xxx" is the name of
+secured data (used with `/secure set xxx ...`). +
+For a complete list of supported options, see `/help secure`.
+
+To use the 'freenode' password, for example with
+<<irc_sasl_authentication,SASL authentication>>:
+
+----
+/set irc.server.freenode.sasl_password "${sec.data.freenode}"
+----
+
 [[options_and_commands]]
 === オプションとコマンド
 
diff --git a/doc/pl/weechat_user.pl.txt b/doc/pl/weechat_user.pl.txt
index 5ce279ceb..4fba64ecb 100644
--- a/doc/pl/weechat_user.pl.txt
+++ b/doc/pl/weechat_user.pl.txt
@@ -1468,6 +1468,90 @@ Przykład pogrubienia z domyślnym kolorem terminala:
 /set weechat.color.status_time *99999
 ----
 
+// TRANSLATION MISSING
+[[secured_data]]
+=== Secured data
+
+[[secured_data_storage]]
+==== Storage
+
+WeeChat can encrypt passwords or private data using secured data, stored in file
+'sec.conf'.
+
+This configuration file is read before any other file, and the values stored
+inside can be used in various WeeChat or plugins/scripts options.
+
+You can set a passphrase to encrypt data in 'sec.conf'. This is not mandatory
+but highly recommended, otherwise data is stored as plain text in file.
+
+----
+/secure passphrase this is my passphrase
+----
+
+When a passphrase is set, WeeChat will ask you to enter it on startup (but not
+on `/upgrade`).
+
+You can change this behavior and use a file with the passphrase (see option
+<<option_sec.crypt.passphrase_file,sec.crypt.passphrase_file>>).
+
+[[secured_data_encryption]]
+===== Encryption
+
+The encryption of data is made in 3 steps:
+
+. Derive a key from the passphrase (with optional salt).
+. Compute hash of data to encrypt.
+. Encrypt the hash + data (output is: salt + encrypted hash/data).
+
+[NOTE]
+The cipher block mode is 'CFB'.
+
+The result is put as hexadecimal string in file 'sec.conf', for example:
+
+----
+[data]
+__passphrase__ = on
+freenode = "53B1C86FCDA28FC122A95B0456ABD79B5AB74654F21C3D099A6CCA8173239EEA59533A1D83011251F96778AC3F5166A394"
+----
+
+[[secured_data_decryption]]
+===== Decryption
+
+The decryption of data is made in 3 steps:
+
+. Derive a key using salt and passphrase.
+. Decrypt hash + data.
+. Check that decrypted hash == hash of data.
+
+[[secured_data_manage]]
+==== Manage secured data
+
+To add secured data, use `/secure set`, for example a password for 'freenode'
+IRC server:
+
+----
+/secure set freenode mypassword
+----
+
+For comfort, secured data can be displayed in a dedicated buffer (key[alt-v] on
+buffer to see values), just do:
+
+----
+/secure
+----
+
+Secured data can be used in some options that can contain private data like
+password, using this format: "${sec.data.xxx}" where "xxx" is the name of
+secured data (used with `/secure set xxx ...`). +
+For a complete list of supported options, see `/help secure`.
+
+To use the 'freenode' password, for example with
+<<irc_sasl_authentication,SASL authentication>>:
+
+----
+/set irc.server.freenode.sasl_password "${sec.data.freenode}"
+----
+
 [[options_and_commands]]
 === Opcje i komendy