From 2ad972828926e8e3ed2d66e89efa6375944f9bd0 Mon Sep 17 00:00:00 2001 From: Simeon Simeonov Date: Wed, 11 Apr 2018 13:08:36 +0200 Subject: Reastructure the documentation in order to please GitHub --- README | 508 ------------------------------------------------------------- README.org | 290 +++++++++++++++++++++++++++++++++++ README.rst | 231 ++++++++++++++++++++++++++++ 3 files changed, 521 insertions(+), 508 deletions(-) delete mode 100644 README create mode 100644 README.org create mode 100644 README.rst diff --git a/README b/README deleted file mode 100644 index 9dcc6de..0000000 --- a/README +++ /dev/null @@ -1,508 +0,0 @@ - Sylpheed - lightweight and user-friendly e-mail client - - Copyright(C) 1999-2018 Hiroyuki Yamamoto - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software Foundation, - Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - - For more details see the file COPYING. - - -What's Sylpheed -=============== - -Sylpheed is an e-mail client based on GTK+ GUI toolkit. -Sylpheed runs on Unix-like systems such as Linux, BSD and Mac OS X, or -Microsoft Windows (XP or later). - -Sylpheed is a free software distributed under the GNU GPL (the library part -LibSylph is GNU LGPL). - -Sylpheed has the following features: - - * Simple, beautiful, and well-polished user interface - * Comfortable operationality which is built in detail - * Well-organized, easy-to-understand configuration - * Lightweight operation - * High reliability - * Internationalization and Multilingualization support - * High-level Japanese processing - * Various protocols support - * Multi-thread support - * Security feature (GnuPG, SSL/TLSv1) - * Powerful filtering and search - * Junk mail control - * Flexible cooperation with external commands - * Plug-in faculty - -The appearance and interface are similar to some popular e-mail clients for -Windows, such as Outlook or Becky!. Many commands are accessible with -the keyboard like the Emacs-based mailers such as Mew and Wanderlust. -So you will be able to migrate to Sylpheed without much discomfort, even if -you are accustomed to other mailers. - -The messages are managed by MH format, and you will be able to use it together -with another mailer based on MH format (like Mew). It has less possibility -of losing mails on failures since one file corresponds to one mail. You can -import or export mbox and eml format messages. You can also utilize fetchmail -and/or procmail, and external programs on receiving (like inc or imget). - -Currently implemented major features -==================================== - -Supported protocols - - o POP3 - o IMAP4rev1 - o SMTP - o NNTP - o SSL/TLSv1 (POP3, SMTP, IMAP4rev1, NNTP) - o IPv6 - o SOCKS4/5 - -Features - - o multiple accounts - o powerful filtering (POP3, IMAP4, local spool) - o powerful search (query search, quick search, search folder) - o Junk mail control - o plug-in faculty - o thread display - o display and transfer of attachments by MIME - o inline image display - o News reader - o SMTP AUTH support (PLAIN / LOGIN / CRAM-MD5) - o CRAM-MD5 authentication (SMTP AUTH / IMAP4rev1) - o APOP authentication (POP3) - o PGP signature / encryption (requires GPGME) - o spell checking (requires GtkSpell) - o SOCKS4/5 proxy support - o X-Face display - o user-defined headers - o mark / color label - o Mew/Wanderlust compatible key bind - o multiple MH folder support - o mbox and eml import / export - o action function to work with external commands - o external editor - o message queueing - o automatic mail checking - o draft message - o template - o line-wrapping - o autosave - o clickable URI - o address book - o newly arrived and unread message management - o printing - o POP3 remote mailbox - o offline mode - o tray icon (minimize to tray icon, new mail notification) - o customization of toolbar - o remote operation by command line - o per-folder configuration - o LDAP, vCard, and JPilot support in address book - o CSV, LDIF file import in address book - o auto-registration of recipient's addresses to address book - o auto-completion of addresses - o Drag & Drop - o autoconf, automake support - o internationalization of messages by gettext - o m17n (multilingualization) support - -and more. - -Installation -============ - -See INSTALL for installation instructions. - -Usage -===== - -Preparation before running --------------------------- - -If you are using a character encoding other than UTF-8 for filename, -you must set the following environmental variable (it will not work if -it is not specified): - -(use locale-specific encoding) -% export G_FILENAME_ENCODING=@locale - -or - -(manually specifying encoding) -% export G_FILENAME_ENCODING=ISO-8859-1 - -If you want to display messages translated to your language, -you must specify some environmental variables related to locale. -For example: - -% export LANG=de_DE.UTF-8 - -(replace de_DE.UTF-8 to the actual locale name) - -If you don't want translated messages, set LC_MESSAGES to "C" -(and unset LC_ALL if specified). - -How to run ----------- - -Input `sylpheed' on a command line, or double-click the icon in a file -manager to execute. - -Initial startup ---------------- - -When Sylpheed is executed for the first time, it automatically creates the -configuration files under ~/.sylpheed-2.0/, and asks you the location of -mailbox. The default is ~/Mail. If some files, which are non-MH format, -already exist on the directory, you will have to specify another location. - -If ~/.sylpheed-2.0/ doesn't exist, but the previous version of configuration -exists in ~/.sylpheed/, migration will be made automatically after the -confirmation. - -If the locale encoding is not UTF-8 and the environmental variable -G_FILENAME_ENCODING is not set, an alert dialog will be displayed. - -Required settings ------------------ - -Initially, you have to create at least one account to send or receive -messages (you can read messages that already exist without creating -accounts). The configuration dialog will be shown by clicking -"Configuration -> Create new account..." in the menu, or "Account" on -the toolbar. Then, fill the required settings. - -Refer to the manual supplied with this program for the general usage. - -Hidden settings ---------------- - -You can configure most of the features in Sylpheed through the preferences -dialog, but there are a few parameters which don't have user interface -(you don't need to modify them in normal use). You must edit -~/.sylpheed-2.0/sylpheedrc by an editor while Sylpheed is not running. - -allow_jisx0201_kana allow JIS X 0201 Kana (half-width kana) on - sending - 0: off 1: on [default: 0] -translate_header translate headers such as 'From:', 'To:' and - 'Subject:' - 0: off 1: on [default: 1] -enable_rules_hint enable alternating row colors for summary view - 0: off 1: on [default: 1] -bold_unread show unread messages using bold font in - summary view - 0: off 1: on [default: 1] -textview_cursor_visible show cursor in the text view - 0: off 1: on [default: 0] -mime_image_viewer specify the command to open attached image - files [default: none] -mime_audio_player specify the command to open attached audio - files [default: none] -mime_command specify the command to open MIME attachments - [default: none] -logwindow_line_limit specify the limit of line numbers of log - window - 0: unlimited n (> 0): n lines [default: 1000] -mark_as_read_on_new_window only mark messages as read when they are - opened with new window - 0: off 1: on [default: 0] - -Unlike 1.0.x, this version doesn't allow direct modification of the menu -shortcuts by default. You can use the following methods to configure them: - -1. Using GNOME 2.8 or later - Run gconf-editor from 'Applications - System Tools - Configuration Editor'. - Select 'desktop - gnome - interface' and check 'can-change-accels' in it. - -2. Using GNOME before 2.8, or other environments - Add gtk-can-change-accels = 1 to the file ~/.gtkrc-2.0 (or create a new - one, if it doesn't exist). - -3. When Sylpheed is not running, directly edit ~/.sylpheed-2.0/menurc with - an editor. - -Information -=========== - -You can check the newest version and information about Sylpheed at: - - http://sylpheed.sraoss.jp/ - -You can also download files from the SourceForce.JP project page: - - http://sourceforge.jp/projects/sylpheed/ - -The bug tracking system of Sylpheed is: - - http://sylpheed.sraoss.jp/redmine/projects/sylpheed - -The Sylpheed documentation in English and several other languages can be -obtained from: - - http://sylpheeddoc.sourceforge.net/ - -Feedback -======== - -Comments, ideas and (most of all) bug reports (and especially patches) are -very welcome. - -Subversion -========== - -You can get the newest source code from the Subversion repository. - -Move to an appropriate directory, and with the command: - - svn checkout svn://sylpheed.sraoss.jp/sylpheed/trunk - -a source tree named 'trunk' is created under the current directory. - -The subdirectory of sylpheed is divided as following: - - * trunk/ Main tree - * branches/ Miscellaneous experimental branches - * tags/ Release-tagged branches - -To update to the newest source tree, run the command: - - svn update - -at the target directory. - --- -Hiroyuki Yamamoto - - -Master password (by sgs) -======================== - -The master password feature is developed by -Simeon Simeonov (sgs - sgs@pichove.org) and is currently in an experimental -state. - - -Motivation ----------- - -Currently Sylpheed is storing passwords in palin-text. One can always refrain -from storing passwords and let Sylpheed prompt for them, but the more accounts -one has, the more annoying this becomes. - -The goal is to have the passwords stored in a secure way and let Sylpheed only -prompt for the master password. - - -Security goals --------------- - -- attacker (A) should not be able to derive the password from the digest - -- A should not be able to derive the master password even if she has - read and write access to the storage - -- A should not be able to determine the length of the encrypted password - even if she has read and write access to the storage - -- A should not be able to craft an edited password without obtaining the - master password - -- a warning / prompt should be given if a user accidently types in a "wrong" - master password before decryption is initiated - - -Usage in Sylpheed ------------------ - -- backup your Sylpheed profile (often $HOME/.sylpheed-2.0)! - -- start Sylpheed and open Configuration -> Common preferences...! - -- select the "Master password" tab, enable "Use master password" and - apply the changes! - -- restart Sylpheed (exit and then start Sylpheed again)! - -- you will be asked to type and verify a new master password. - -Note: -Sylpheed will automatically convert existing stored passwords, but it will not -touch your backups. You will have to remove all remnants of plain-text -passwords manually. - - -Choice of cryptographic primitives ----------------------------------- - -The primary concern when selecting cryptographic primitives was portability. -The desire was to go for primitives that are both strong and available in all -supported production distributions of OpenSSL and LibreSSL. - - -Cipher -...... - -When it comes to implementation, there are several advantages in using stream -cipher or a block cipher that behaves like a stream cipher when used in a -certain mode of operation. One is avoiding to deal with padding. - -AES-256 operating in CFB was selected for these reasons. -ChaCha20 should be considered as a replacement in the future. - - -Hash-function -............. - -Hash-functions are used for: -- key derivation -- plain-text digest - -Those operations do not have to use the same hash-function. -(See the "Encryption & decryption scheme" section for more details!) - -Key-derivation: -Since AES-256 uses a 256 bits key, we need a hash-function with at least -the same digest size or bigger. -Since the digest (which is the key itself) is considered confidential and is -stored only in memory for only a limited amount of time, SHA-256 is considered -sufficiently strong for that purpose. - -Size + plain-text + padding digest: -Since the digest is created of both the plain-text and the plain-text size, -as well as being encrypted, SHA-256 is considered sufficiently strong. -SHA-512 may increase security at the price of adding additional 32 bytes -to the encrypted password digest. - -Stronger hash-functions like SHA-3 or BLAKE2b can be considered as a -replacement in the future. - - -Master password digest -...................... - -In order to be able to decide whether the user typed a "wrong" master password, -before attempting to decrypt, Sylpheed stores a digest of the master password -in 'master_password_hash' in sylpheedrc. -100000 iterations of PBKDF2_HMAC with SHA-512 and 16 bytes salt is used. -Note that this digest is useless as a key and even if a plain-text that -produces the same digest is found, it will most probably be useless as a -master-password. - - -Encryption & decryption scheme ------------------------------- - - -Encryption -.......... - - -Input: - -- palin-text password to be encrypted (P) - -- plain-text master-password used for key derivation (M) - -- integer minimum password length (0 < L < 100) - - -Output: - -- an encrypted password digest (base64) (B) - - -Operation: - -- generate 16 bytes of random data to be used as a salt (S) - -- derive the key (K): K = SHA_256(S + M) - -- produce a 2 byte string (N) indicating the length of P - -- if the length of P < L, produce L - P bytes of random data (R), N = "%02d" - if the length of P >= L, N = "-1" - -- produce a hash digest (H): H = SHA_256(N + P + R (if the length of P < L)) - -- encrypt (E): E = AES_256_CFB_ENCRYPT(H + N + P + R (if the length of P < L), K) - -- B = mpes1:BASE64_ENCODE(S + E) - example: - mpes1:vo7lsIpD7i6byBA6+vlUoF4OVDfEe+aYRRk4FRtfJ2gMY8M43Kj6WfdfgbViIOl83bI4XEc96okhPW5Mla813aAR1gbPjDg0xmCyIbWOiUv/dg== - - -Decryption -.......... - - -Input: - -- encrypted password digest (base64) (B) - -- plain-text master-password used for key derivation (M) - - -Output: - -- palin-text password (P) - - -Operation: - -- remove the prefix (mpes1:) and base64-decode the rest of the digest: B = BASE64_DECODE(B) - -- fetch the first 16 bytes for the salt: S = B[0 : 15] - -- derive the key (K): K = SHA_256(S + M) - -- decrypt the rest of B (D): D = AES_256_CFB_DECRYPT(B[16 :], K) - -- extract the first 16 bytes for the hash digest (H): H = D[0 : 15] - -- in order to detect data-inconsistency, assert H == SHA_256(D[16 :]) - -- extract the next 2 bytes for the length of P (N): N = D[16 : 17] - -- if N == "-1" the password is the remaining bytes of D: P = D[18 :] - if N != "-1", extract the next N-bytes from D: P = D[18 : (18 + N)] - - -Limitations ------------ - -- when Sylpheed starts, the master-password is loaded into memory and remains - there as long as Sylpheed is running. Currently no strong mechanisms, - preventing someone with access to the memory from snatching it, - are implemented. - "Unloading" the master-password immediately after - account-processing (decryption) should be considered in the future. - -- currently only the 'password' and 'smtp_password' keys in accountrc - are encrypted. - A machanism that allows for any key and even folders to be encrypted - should be considered in the future. - -- currently it is not possible to select alternative ciphers, hash-functions - and modes of operation (without editing the source code). - -- currently it is not possible to change your master password without having to - set your passwords manually. - --- -Simeon Simeonov diff --git a/README.org b/README.org new file mode 100644 index 0000000..d805f27 --- /dev/null +++ b/README.org @@ -0,0 +1,290 @@ + Sylpheed - lightweight and user-friendly e-mail client + + Copyright(C) 1999-2018 Hiroyuki Yamamoto + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + For more details see the file COPYING. + + +What's Sylpheed +=============== + +Sylpheed is an e-mail client based on GTK+ GUI toolkit. +Sylpheed runs on Unix-like systems such as Linux, BSD and Mac OS X, or +Microsoft Windows (XP or later). + +Sylpheed is a free software distributed under the GNU GPL (the library part +LibSylph is GNU LGPL). + +Sylpheed has the following features: + + * Simple, beautiful, and well-polished user interface + * Comfortable operationality which is built in detail + * Well-organized, easy-to-understand configuration + * Lightweight operation + * High reliability + * Internationalization and Multilingualization support + * High-level Japanese processing + * Various protocols support + * Multi-thread support + * Security feature (GnuPG, SSL/TLSv1) + * Powerful filtering and search + * Junk mail control + * Flexible cooperation with external commands + * Plug-in faculty + +The appearance and interface are similar to some popular e-mail clients for +Windows, such as Outlook or Becky!. Many commands are accessible with +the keyboard like the Emacs-based mailers such as Mew and Wanderlust. +So you will be able to migrate to Sylpheed without much discomfort, even if +you are accustomed to other mailers. + +The messages are managed by MH format, and you will be able to use it together +with another mailer based on MH format (like Mew). It has less possibility +of losing mails on failures since one file corresponds to one mail. You can +import or export mbox and eml format messages. You can also utilize fetchmail +and/or procmail, and external programs on receiving (like inc or imget). + +Currently implemented major features +==================================== + +Supported protocols + + o POP3 + o IMAP4rev1 + o SMTP + o NNTP + o SSL/TLSv1 (POP3, SMTP, IMAP4rev1, NNTP) + o IPv6 + o SOCKS4/5 + +Features + + o multiple accounts + o powerful filtering (POP3, IMAP4, local spool) + o powerful search (query search, quick search, search folder) + o Junk mail control + o plug-in faculty + o thread display + o display and transfer of attachments by MIME + o inline image display + o News reader + o SMTP AUTH support (PLAIN / LOGIN / CRAM-MD5) + o CRAM-MD5 authentication (SMTP AUTH / IMAP4rev1) + o APOP authentication (POP3) + o PGP signature / encryption (requires GPGME) + o spell checking (requires GtkSpell) + o SOCKS4/5 proxy support + o X-Face display + o user-defined headers + o mark / color label + o Mew/Wanderlust compatible key bind + o multiple MH folder support + o mbox and eml import / export + o action function to work with external commands + o external editor + o message queueing + o automatic mail checking + o draft message + o template + o line-wrapping + o autosave + o clickable URI + o address book + o newly arrived and unread message management + o printing + o POP3 remote mailbox + o offline mode + o tray icon (minimize to tray icon, new mail notification) + o customization of toolbar + o remote operation by command line + o per-folder configuration + o LDAP, vCard, and JPilot support in address book + o CSV, LDIF file import in address book + o auto-registration of recipient's addresses to address book + o auto-completion of addresses + o Drag & Drop + o autoconf, automake support + o internationalization of messages by gettext + o m17n (multilingualization) support + +and more. + +Installation +============ + +See INSTALL for installation instructions. + +Usage +===== + +Preparation before running +-------------------------- + +If you are using a character encoding other than UTF-8 for filename, +you must set the following environmental variable (it will not work if +it is not specified): + +(use locale-specific encoding) +% export G_FILENAME_ENCODING=@locale + +or + +(manually specifying encoding) +% export G_FILENAME_ENCODING=ISO-8859-1 + +If you want to display messages translated to your language, +you must specify some environmental variables related to locale. +For example: + +% export LANG=de_DE.UTF-8 + +(replace de_DE.UTF-8 to the actual locale name) + +If you don't want translated messages, set LC_MESSAGES to "C" +(and unset LC_ALL if specified). + +How to run +---------- + +Input `sylpheed' on a command line, or double-click the icon in a file +manager to execute. + +Initial startup +--------------- + +When Sylpheed is executed for the first time, it automatically creates the +configuration files under ~/.sylpheed-2.0/, and asks you the location of +mailbox. The default is ~/Mail. If some files, which are non-MH format, +already exist on the directory, you will have to specify another location. + +If ~/.sylpheed-2.0/ doesn't exist, but the previous version of configuration +exists in ~/.sylpheed/, migration will be made automatically after the +confirmation. + +If the locale encoding is not UTF-8 and the environmental variable +G_FILENAME_ENCODING is not set, an alert dialog will be displayed. + +Required settings +----------------- + +Initially, you have to create at least one account to send or receive +messages (you can read messages that already exist without creating +accounts). The configuration dialog will be shown by clicking +"Configuration -> Create new account..." in the menu, or "Account" on +the toolbar. Then, fill the required settings. + +Refer to the manual supplied with this program for the general usage. + +Hidden settings +--------------- + +You can configure most of the features in Sylpheed through the preferences +dialog, but there are a few parameters which don't have user interface +(you don't need to modify them in normal use). You must edit +~/.sylpheed-2.0/sylpheedrc by an editor while Sylpheed is not running. + +allow_jisx0201_kana allow JIS X 0201 Kana (half-width kana) on + sending + 0: off 1: on [default: 0] +translate_header translate headers such as 'From:', 'To:' and + 'Subject:' + 0: off 1: on [default: 1] +enable_rules_hint enable alternating row colors for summary view + 0: off 1: on [default: 1] +bold_unread show unread messages using bold font in + summary view + 0: off 1: on [default: 1] +textview_cursor_visible show cursor in the text view + 0: off 1: on [default: 0] +mime_image_viewer specify the command to open attached image + files [default: none] +mime_audio_player specify the command to open attached audio + files [default: none] +mime_command specify the command to open MIME attachments + [default: none] +logwindow_line_limit specify the limit of line numbers of log + window + 0: unlimited n (> 0): n lines [default: 1000] +mark_as_read_on_new_window only mark messages as read when they are + opened with new window + 0: off 1: on [default: 0] + +Unlike 1.0.x, this version doesn't allow direct modification of the menu +shortcuts by default. You can use the following methods to configure them: + +1. Using GNOME 2.8 or later + Run gconf-editor from 'Applications - System Tools - Configuration Editor'. + Select 'desktop - gnome - interface' and check 'can-change-accels' in it. + +2. Using GNOME before 2.8, or other environments + Add gtk-can-change-accels = 1 to the file ~/.gtkrc-2.0 (or create a new + one, if it doesn't exist). + +3. When Sylpheed is not running, directly edit ~/.sylpheed-2.0/menurc with + an editor. + +Information +=========== + +You can check the newest version and information about Sylpheed at: + + http://sylpheed.sraoss.jp/ + +You can also download files from the SourceForce.JP project page: + + http://sourceforge.jp/projects/sylpheed/ + +The bug tracking system of Sylpheed is: + + http://sylpheed.sraoss.jp/redmine/projects/sylpheed + +The Sylpheed documentation in English and several other languages can be +obtained from: + + http://sylpheeddoc.sourceforge.net/ + +Feedback +======== + +Comments, ideas and (most of all) bug reports (and especially patches) are +very welcome. + +Subversion +========== + +You can get the newest source code from the Subversion repository. + +Move to an appropriate directory, and with the command: + + svn checkout svn://sylpheed.sraoss.jp/sylpheed/trunk + +a source tree named 'trunk' is created under the current directory. + +The subdirectory of sylpheed is divided as following: + + * trunk/ Main tree + * branches/ Miscellaneous experimental branches + * tags/ Release-tagged branches + +To update to the newest source tree, run the command: + + svn update + +at the target directory. + +-- +Hiroyuki Yamamoto diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..622264a --- /dev/null +++ b/README.rst @@ -0,0 +1,231 @@ +Implemented features and fixes not present in the official Sylpheed release +=========================================================================== + +- (fix) + PGP signature not verified properly when the message has no newline + at the end. https://sylpheed.sraoss.jp/redmine/issues/288 + +- (feature) + Make it possible to select "Show signature check result in a popup window" + only for bad signatures. + +- (feature) + Support for encrypting and storing encrypted passwords using a master password. + See README for more details. + + +Master password +=============== + +The master password feature is developed by Simeon Simeonov (sgs) +and is currently in an experimental state. + + +Motivation +---------- + +Currently Sylpheed is storing passwords in palin-text. One can always refrain +from storing passwords and let Sylpheed prompt for them, but the more accounts +one has, the more annoying this becomes. + +The goal is to have the passwords stored in a secure way and let Sylpheed only +prompt for the master password. + + +Security goals +-------------- + +- attacker (A) should not be able to derive the password from the digest + +- A should not be able to derive the master password even if she has + read and write access to the storage + +- A should not be able to determine the length of the encrypted password + even if she has read and write access to the storage + +- A should not be able to craft an edited password without obtaining the + master password + +- a warning / prompt should be given if a user accidently types in a "wrong" + master password before decryption is initiated + + +Usage in Sylpheed +----------------- + +- backup your Sylpheed profile (often $HOME/.sylpheed-2.0)! + +- start Sylpheed and open Configuration -> Common preferences...! + +- select the "Master password" tab, enable "Use master password" and + apply the changes! + +- restart Sylpheed (exit and then start Sylpheed again)! + +- you will be asked to type and verify a new master password. + +Note: +Sylpheed will automatically convert existing stored passwords, but it will not +touch your backups. You will have to remove all remnants of plain-text +passwords manually. + + +Choice of cryptographic primitives +---------------------------------- + +The primary concern when selecting cryptographic primitives was portability. +The desire was to go for primitives that are both strong and available in all +supported production distributions of OpenSSL and LibreSSL. + + +Cipher +...... + +When it comes to implementation, there are several advantages in using stream +cipher or a block cipher that behaves like a stream cipher when used in a +certain mode of operation. One is avoiding to deal with padding. + +AES-256 operating in CFB was selected for these reasons. +ChaCha20 should be considered as a replacement in the future. + + +Hash-function +............. + +Hash-functions are used for: +- key derivation +- plain-text digest + +Those operations do not have to use the same hash-function. +(See the "Encryption & decryption scheme" section for more details!) + +Key-derivation: +Since AES-256 uses a 256 bits key, we need a hash-function with at least +the same digest size or bigger. +Since the digest (which is the key itself) is considered confidential and is +stored only in memory for only a limited amount of time, SHA-256 is considered +sufficiently strong for that purpose. + +Size + plain-text + padding digest: +Since the digest is created of both the plain-text and the plain-text size, +as well as being encrypted, SHA-256 is considered sufficiently strong. +SHA-512 may increase security at the price of adding additional 32 bytes +to the encrypted password digest. + +Stronger hash-functions like SHA-3 or BLAKE2b can be considered as a +replacement in the future. + + +Master password digest +...................... + +In order to be able to decide whether the user typed a "wrong" master password, +before attempting to decrypt, Sylpheed stores a digest of the master password +in 'master_password_hash' in sylpheedrc. +100000 iterations of PBKDF2_HMAC with SHA-512 and 16 bytes salt is used. +Note that this digest is useless as a key and even if a plain-text that +produces the same digest is found, it will most probably be useless as a +master-password. + + +Encryption & decryption scheme +------------------------------ + + +Encryption +.......... + + +Input: + +- palin-text password to be encrypted (P) + +- plain-text master-password used for key derivation (M) + +- integer minimum password length (0 < L < 100) + + +Output: + +- an encrypted password digest (base64) (B) + + +Operation: + +- generate 16 bytes of random data to be used as a salt (S) + +- derive the key (K): K = SHA_256(S + M) + +- produce a 2 byte string (N) indicating the length of P + +- if the length of P < L, produce L - P bytes of random data (R), N = "%02d" + if the length of P >= L, N = "-1" + +- produce a hash digest (H): H = SHA_256(N + P + R (if the length of P < L)) + +- encrypt (E): E = AES_256_CFB_ENCRYPT(H + N + P + R (if the length of P < L), K) + +- B = mpes1:BASE64_ENCODE(S + E) + example: + mpes1:vo7lsIpD7i6byBA6+vlUoF4OVDfEe+aYRRk4FRtfJ2gMY8M43Kj6WfdfgbViIOl83bI4XEc96okhPW5Mla813aAR1gbPjDg0xmCyIbWOiUv/dg== + + +Decryption +.......... + + +Input: + +- encrypted password digest (base64) (B) + +- plain-text master-password used for key derivation (M) + + +Output: + +- palin-text password (P) + + +Operation: + +- remove the prefix (mpes1:) and base64-decode the rest of the digest: B = BASE64_DECODE(B) + +- fetch the first 16 bytes for the salt: S = B[0 : 15] + +- derive the key (K): K = SHA_256(S + M) + +- decrypt the rest of B (D): D = AES_256_CFB_DECRYPT(B[16 :], K) + +- extract the first 16 bytes for the hash digest (H): H = D[0 : 15] + +- in order to detect data-inconsistency, assert H == SHA_256(D[16 :]) + +- extract the next 2 bytes for the length of P (N): N = D[16 : 17] + +- if N == "-1" the password is the remaining bytes of D: P = D[18 :] + if N != "-1", extract the next N-bytes from D: P = D[18 : (18 + N)] + + +Limitations +----------- + +- when Sylpheed starts, the master-password is loaded into memory and remains + there as long as Sylpheed is running. Currently no strong mechanisms, + preventing someone with access to the memory from snatching it, + are implemented. + "Unloading" the master-password immediately after + account-processing (decryption) should be considered in the future. + +- currently only the 'password' and 'smtp_password' keys in accountrc + are encrypted. + A machanism that allows for any key and even folders to be encrypted + should be considered in the future. + +- currently it is not possible to select alternative ciphers, hash-functions + and modes of operation (without editing the source code). + +- currently it is not possible to change your master password without having to + set your passwords manually. + +-- +Simeon Simeonov -- cgit v1.3