hardcoresushi/libgocryptfs
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Cut down the text in SECURITY.md, add graphs

Browse Source
This commit is contained in:
Jakob Unterwurzacher 2015-12-01 23:02:12 +01:00
parent 6515c8d42c
commit 026ab56de4
2 changed files with 46 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
Documentation/SECURITY.md
View File

@ -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
### Metadata
* 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.
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
* 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
### File Names
* 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
* 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.
Master Key Storage
------------------
The *master key* is used to perform content and file name encryption.
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*.
Key Encryption Key (KEK).
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.
The KEK is generated from the user password using `scrypt`.
![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/master-key.svg)
File Contents
-------------
All file contents are encrypted using AES-256-GCM.
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.
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.
![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/file-content-encryption.svg)
To support sparse files, all-zero blocks are accepted and passed through
unchanged.
File Names
----------
Every directory gets a 128-bit directory IV that is stored in each
directory as `gocryptfs.diriv`.
File names are encrypted using AES-256-CBC with the directory IV.
![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/file-name-encryption.svg)

24
Documentation/master-key.svg
View File

@ -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" />

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB