diff options
| -rw-r--r-- | Documentation/SECURITY.md | 102 | ||||
| -rw-r--r-- | Documentation/master-key.svg | 24 |
2 files changed, 38 insertions, 88 deletions
diff --git a/Documentation/SECURITY.md b/Documentation/SECURITY.md index 4db4c24..e9e1015 100644 --- a/Documentation/SECURITY.md +++ b/Documentation/SECURITY.md @@ -1,92 +1,42 @@ GoCryptFS Security ================== -"Security" can be split into "Confidentiality" and "Integrity". The -security level gocryptfs provides for each is discussed in the next -sections. - -Confidentiality ---------------- - -Confidentiality means that information cannot be extracted from the -encrypted data unless you know the key. - -### File Contents - -* All file contents (even the last bytes) are encrypted using AES-256-GCM - * This is unbreakable in the foreseeable future. Attacks will focus on - cracking the password instead (see section "Master Key Storage"). -* Files are segmented into 4096 byte blocks -* Each block gets a fresh random 96 bit IV (none) each time it is written. - * This means that identical blocks can not be identified - -### File Names - -* File names are encrypted using AES-256-CBC with a per-directory IV -* Each directory get a random 128 bit IV on creation - * Files with the same name in different directories are encrypted to - different filenames and can not be identified -* File names are padded to multiples of 16 bytes - * This means that the exact length of the name is hidden, only length - ranges (1-16 bytes, 17-32 bytes etc.) can be determined from the encrypted - files +Master Key Storage +------------------ -### Metadata +The master key is used to perform content and file name encryption. +It is stored in `gocryptfs.conf`, encrypted with AES-256-GCM using the +Key Encryption Key (KEK). -* The size of the file is not hidden. The exact file size can be calculated - from the size of the encrypted file. -* File owner, file permissions and timestamps are not hidden. +The KEK is generated from the user password using `scrypt`. -Integrity ---------- + -Integrity means that the data cannot be modified in a meaningful way -unless you have the key. The opposite of integrity is *malleability*. +File Contents +------------- -### File Contents +All file contents are encrypted using AES-256-GCM. -* The used encryption, AES-256-GCM, is a variant of - *authenticated encryption*. Each block gets a 128 bit authentication - tag (GMAC) appended. - * This means that any modification inside a block will be detected when reading - the block and decryption will be aborted. The failure is logged and an - I/O error is returned to the user. -* Every file has a header that contains a 16-byte random *file id* -* Each block uses the file id and its block number as GCM *authentication data* - * This means the position of the blocks is protected as well. The blocks - can not be reordered or copied between different files without - causing an decryption error. -* For technical reasons (sparse files), the special "all-zero" block is - always seen as a valid block that decrypts to all-zero plaintext. - * This means that whole blocks can be zeroed out +Files are segmented into 4KB blocks. Each block gets a fresh random +96 bit IV each time it is modified. A 128-bit authentication tag (GHASH) +protects each block from modifications. -### File Names +Each file has a header containing a random 128-bit file ID. The +file ID and the block number are mixed into the GHASH as +*additional authenticated data*. The prevents blocks from being copied +between or within files. -* File names are only weakly protected against modifications. - * Changing a single byte causes a decode error in most of the - cases. The failure is logged and the file is no longer visible in the - directory. - * If no decode error is triggered, at least 16 bytes of the filename will - be corrupted (randomized). -* However, file names can always be truncated to multiples of 16 bytes. + -### Metadata +To support sparse files, all-zero blocks are accepted and passed through +unchanged. -* The file size is not protected against modifications - * However, the block integrity protection limits modifications to block - size granularity. - * This means that files can be truncated to multiples of 4096 bytes. -* Ownership, timestamp and permissions are not protected and can be changed - as usual. +File Names +---------- -Master Key Storage ------------------- +Every directory gets a 128-bit directory IV that is stored in each +directory as `gocryptfs.diriv`. -The *master key* is used to perform content and file name encryption. -It is stored in `gocryptfs.conf`, encrypted with AES-256-GCM using the -*unlock key*. +File names are encrypted using AES-256-CBC with the directory IV. -The unlock key is generated from a user password using `scrypt`. -A successful decryption of the master key means that the GMAC authentication -passed and the password is correct. The master key is then used to -mount the filesystem. + diff --git a/Documentation/master-key.svg b/Documentation/master-key.svg index 096e890..dff9a9a 100644 --- a/Documentation/master-key.svg +++ b/Documentation/master-key.svg @@ -103,8 +103,8 @@ inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="1.4" - inkscape:cx="356.2081" - inkscape:cy="-20.641831" + inkscape:cx="432.9172" + inkscape:cy="-9.3512986" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="true" @@ -123,8 +123,8 @@ id="grid4153" dotted="true" units="mm" - spacingx="7.0866142" - spacingy="7.0866143" + spacingx="3.543307" + spacingy="3.543307" originx="-14.173228" originy="-940.93176" /> </sodipodi:namedview> @@ -183,14 +183,14 @@ xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:90.10359192px;line-height:125%;font-family:Arial;-inkscape-font-specification:'Arial Bold';letter-spacing:67.72786713px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" x="66.150955" - y="98.171463" + y="96.744003" id="text4155-8" sodipodi:linespacing="125%" - transform="scale(0.99921743,1.0007832)"><tspan + transform="scale(0.99921742,1.0007832)"><tspan sodipodi:role="line" id="tspan4157-1" x="66.150955" - y="98.171463" + y="96.744003" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;font-family:sans-serif;-inkscape-font-specification:sans-serif;letter-spacing:0px">User password</tspan></text> <text xml:space="preserve" @@ -221,10 +221,10 @@ <rect style="opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" id="rect4271" - width="180.77509" - height="21.300983" - x="32.295944" - y="82.542801" /> + width="201.96851" + height="21.259884" + x="21.259844" + y="81.49601" /> <rect style="opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" id="rect3336-9-4-2" @@ -254,7 +254,7 @@ sodipodi:nodetypes="cc" /> <path style="opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow1Mend-9)" - d="M 216.95674,93.498458 285.25749,80.265566" + d="M 226.5996,93.141315 285.25749,80.265566" id="path4296-9" inkscape:connector-curvature="0" sodipodi:nodetypes="cc" /> |
