From d29a4de26d0e3f31f467bcc9167b9758fad774f8 Mon Sep 17 00:00:00 2001 From: Jakob Unterwurzacher Date: Sun, 17 Sep 2017 11:57:16 +0200 Subject: Update both forward and reverse mode crypto docs They were written before HKDF was introduced. Improve graphics as well --- docs/forward_mode_crypto.md | 14 +- docs/img/file-content-encryption.svg | 166 +++--- docs/img/reverse-derivePathIV.svg | 344 +++++++---- docs/img/reverse-file-content-encryption.svg | 839 +++++++++++++-------------- docs/reverse_mode_crypto.md | 65 ++- 5 files changed, 774 insertions(+), 654 deletions(-) diff --git a/docs/forward_mode_crypto.md b/docs/forward_mode_crypto.md index e9b4f47..67cbaf6 100644 --- a/docs/forward_mode_crypto.md +++ b/docs/forward_mode_crypto.md @@ -38,12 +38,14 @@ File Contents All file contents are encrypted using AES-256-GCM (Galois/Counter Mode). -Files are segmented into 4KB blocks. Each block gets a fresh random +Files are segmented into 4KiB blocks. Each block gets a fresh random 128 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 +file ID and the block number are concatenated +(source code [ref](https://github.com/rfjakob/gocryptfs/blob/master/internal/contentenc/content.go#L124)) +and mixed into the GHASH as *additional authenticated data*. The prevents blocks from being copied between or within files. @@ -66,8 +68,8 @@ encryption. ![](img/file-name-encryption.svg) The Base64 encoding limits the usable filename length to 176 characters. -Filenames that are longer than that (longer than 255 characters in Base64- -encoded form) use long file name handling (since gocryptfs v0.9). +Filenames that are longer than that (longer than 255 characters in +Base64-encoded form) use long file name handling, introduced in gocryptfs v0.9. Long File Name Handling ----------------------- @@ -96,5 +98,5 @@ for filenames that are <= 176 characters, incurs no extra disk accesses for opening a file with a long name, and just one extra file read for each long-name file on readdir(1). -Because the hash is only taken from the encrypted file name, there is no -security penalty for using long names. +Because the hash is only taken from the encrypted file name that is public +anyway, there is no security penalty for using long names. diff --git a/docs/img/file-content-encryption.svg b/docs/img/file-content-encryption.svg index 6f054eb..dfde974 100644 --- a/docs/img/file-content-encryption.svg +++ b/docs/img/file-content-encryption.svg @@ -19,40 +19,40 @@ + id="marker13917" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Mend"> + style="fill:#000000;fill-opacity:0.99607843;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:0.99607843" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + id="path13915" /> + id="path13669" /> + + + + id="path8951" /> + inkscape:document-rotation="0" + inkscape:guide-bbox="true"> + + @@ -388,34 +415,17 @@ id="path8425" inkscape:connector-curvature="0" /> - - - N IV AAD - + + + cat + + diff --git a/docs/img/reverse-derivePathIV.svg b/docs/img/reverse-derivePathIV.svg index 622cec1..65e8e0a 100644 --- a/docs/img/reverse-derivePathIV.svg +++ b/docs/img/reverse-derivePathIV.svg @@ -9,12 +9,12 @@ xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="144.88924mm" - height="40.864796mm" - viewBox="0 0 513.38705 144.79651" + width="146.88574mm" + height="61.163269mm" + viewBox="0 0 520.46128 216.72024" id="svg2" version="1.1" - inkscape:version="0.91 r13725" + inkscape:version="0.92+devel unknown" sodipodi:docname="reverse-derivePathIV.svg"> @@ -28,8 +28,8 @@ inkscape:isstock="true"> @@ -43,8 +43,8 @@ inkscape:isstock="true"> @@ -58,8 +58,8 @@ inkscape:isstock="true"> @@ -73,8 +73,8 @@ inkscape:isstock="true"> @@ -88,8 +88,8 @@ inkscape:isstock="true"> @@ -103,11 +103,43 @@ inkscape:isstock="true"> + + + + + + + inkscape:snap-page="false" + inkscape:document-rotation="0"> + originx="-189.45444" + originy="-752.75882" /> @@ -162,201 +195,189 @@ inkscape:label="Layer 1" inkscape:groupmode="layer" id="layer1" - transform="translate(-187.87518,-173.18251)"> - - - - + transform="translate(-189.45445,-82.883014)"> + + + + + + + + - + y="272.83463" + style="font-size:60px;line-height:1.25">  SHA256(path + \0 + ) - + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00295734px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:end;letter-spacing:0px;text-anchor:end">SHA256(path + \0 + TruncateTruncateto 128 bits derivePathIV: - "DIRIV""DIRIV""FILEID""BLOCK0IV" + y="262.20465" + style="font-size:10px;line-height:1.25">  DirIVDirIVFileIDBlock0IV + id="flowPara5263" + style="font-size:10px;line-height:1.25">  Plaintext path + + File name encryption + + + + encryptedpath + + ) + diff --git a/docs/img/reverse-file-content-encryption.svg b/docs/img/reverse-file-content-encryption.svg index 89eb3ab..40cc2d5 100644 --- a/docs/img/reverse-file-content-encryption.svg +++ b/docs/img/reverse-file-content-encryption.svg @@ -9,9 +9,9 @@ xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="213.51266mm" - height="90.3311mm" - viewBox="0 0 756.54092 320.07084" + width="182.72755mm" + height="77.163986mm" + viewBox="0 0 647.45982 273.41571" id="svg2" version="1.1" inkscape:version="0.92+devel unknown" @@ -23,20 +23,20 @@ orient="auto" refY="0" refX="0" - id="marker15863" + id="marker12596" style="overflow:visible" inkscape:isstock="true"> + style="fill:#000000;fill-opacity:0.99607843;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:0.99607843" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path12498" /> + inkscape:stockid="Arrow1Mend"> - - - + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path8609" /> + inkscape:stockid="Arrow1Mend"> + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path4424" /> + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path8951" /> + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path8951-6" /> + inkscape:stockid="Arrow1Mend" + inkscape:collect="always"> + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path15496-0" /> - - - + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path12390-6" /> + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path8951-6-1" /> + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path12390-6-9" /> + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path15496-0-5" /> + originx="-8.1588869" + originy="-624.40413" /> + + + + + + + + + @@ -312,7 +325,7 @@ image/svg+xml - + @@ -320,176 +333,134 @@ inkscape:label="Layer 1" inkscape:groupmode="layer" id="layer1" - transform="translate(48.888352,-107.88726)"> + transform="translate(-8.1588805,-154.54238)"> + x="498.61414" + y="179.82323" /> + x="506.50458" + y="192.34044" /> - "5qbHc9O.../7GMW91..." + x="506.50458" + y="265.31494" /> File ID + x="573.16339" + y="207.36388" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00295734px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">File ID Block N + x="573.46008" + y="257.81741" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00295734px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">Block N IV + x="572.78247" + y="281.78592" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00295734px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">IV authentication tag + x="573.65417" + y="308.02335" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-variant-east-asian:normal;font-feature-settings:normal;text-indent:0;text-align:center;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:0px;word-spacing:0px;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:middle;white-space:normal;shape-padding:0;opacity:1;vector-effect:none;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1">Ciphertext +authenticationtag Ciphertext +  -   ... ... - Plaintextfilecontent - + x="506.50458" + y="286.57477" /> AES-SIV - IV AAD + + + + + File Name Encryption - "Photos/Team.jpg" - + id="tspan4157-9-7-0-0" + x="344.1413" + y="233.00304" + style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:15.00250003px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Bold';text-align:center;letter-spacing:0px;text-anchor:middle;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal">Block0IV + - encrypted path + style="opacity:1;fill:#b0b0b0;fill-opacity:1;stroke:none;stroke-width:0.99999994;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect4273-2-5" + width="141.24979" + height="228.70485" + x="15.245495" + y="180.69168" /> + + + x="85.355354" + y="322.6373" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00295734px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle" + id="tspan16685">plaintextblock N - + id="tspan4157-9-8-2-6" + x="85.853493" + y="279.63336" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00295734px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle;stroke-width:0.99999994px">Block N derivePathIV + id="tspan8336-8-9" + x="-259.94525" + y="86.970665" + style="font-size:15.00295734px;line-height:1.25;stroke-width:0.99999994px">... FileID + id="tspan8336-8-2" + x="-389.71329" + y="86.970665" + style="font-size:15.00295734px;line-height:1.25;stroke-width:0.99999994px">... + + Block0IV + id="tspan4157-9-7-0-0-2" + x="214.68965" + y="271.35034" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00295734px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:end;letter-spacing:0px;text-anchor:end;stroke-width:0.99999994px">N - - - - - + sodipodi:nodetypes="cc" /> + BlockIV + FileID + FileID - - - - + sodipodi:nodetypes="cc" /> + Plaintext file + Ciphertext file + style="opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.9999997;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3336-9-4-2-0-1-3-3-0-8-2" + width="34.75692" + height="21.259842" + x="281.88644" + y="288.16638" + ry="10.629921" /> + cat - diff --git a/docs/reverse_mode_crypto.md b/docs/reverse_mode_crypto.md index e7af8b5..679644a 100644 --- a/docs/reverse_mode_crypto.md +++ b/docs/reverse_mode_crypto.md @@ -8,62 +8,63 @@ To make reverse mode useful, it uses deterministic encryption using AES-SIV instead of AES-GCM. The differences with respect to the "normal" (forward) mode as detailed -on the [Security](security) page are listed below. +on the [Cryptograhy](forward_mode_crypto.md) page are listed below. Derived Keys ------------ -The derived file content key is 64 bytes wide instead of 32 bytes -as in forward mode -(source code [ref](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/cryptocore/cryptocore.go#L111)) -. +As in forward mode, the file content key is derived from the master key +using HKDF-SHA256. Is is 64 bytes wide instead of 32 bytes +(source code [ref](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/cryptocore/cryptocore.go#L111)). +for use with AES-SIV-512. -File Contents -------------- +Derived IVs +----------- + +All values that are random in forward mode (Dir IV, File ID, Block IV) +are instead deterministically derived from the encrypted path. +The encrypted path is concatenated with a null byte and a +purpose string (one of "DIRIV", "FILEID", "BLOCK0IV"). The extended string +is hashed with SHA256 and truncated to 128 bits (source code +[ref](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/pathiv/pathiv.go#L26)): -File contents are encrypted using AES-SIV-512 (RFC5297). The 512-bit -AES-SIV key is derived from the 256-bit master key by hashing it with -SHA512. +![](img/reverse-derivePathIV.svg) -All values that are random in forward mode (File ID, Block IV) -are instead deterministically derived from the encrypted path, -essentially using a salted hash (detailed in the section *DerivePathIV*). -As all derived values are explicitely stored in the ciphertext file, -decryption does not depend on knowledge of the derivation. +All derived values are explicitely stored in the ciphertext, +so that decryption requires no knowledge of the derivation +algorithm. +File Contents +------------- + +File contents are encrypted using AES-SIV-512 (RFC5297). The encryption process is shown in the diagram below. ![](img/reverse-file-content-encryption.svg) Notes: -1. The IV is passed to AES-SIV as described in section 3 of RFC5297 -2. The block number N is contained in the IV as well as in the AAD - (but AAD and IV are not identical) +1. The IV is passed to AES-SIV as described in + [RFC5297 section 3](https://tools.ietf.org/html/rfc5297#section-3) + as an additional component of the associated data + (source code [ref](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/siv_aead/siv_aead.go#L60)). +2. The block number N is mixed into the IV as well as into the AAD. Either one or the other would suffice, but this construction simplifies - the decryption process by keeping it identical to forward mode. + the decryption process by keeping it largely identical to forward mode. The "duplication" is considered to not have - any security impact because S2V (RFC5297 section 2.4) hashes IV and - AAD independently before XORing them together. + any security impact because IV and AAD contain 128 bits of + pseudo-random data each (FileID and Block0IV) and S2V + ([RFC5297 section 2.4](https://tools.ietf.org/html/rfc5297#section-2.4)) + hashes the components independently before XORing them together. File Names ---------- File name encryption is identical to forward mode, with the exception that the directory IV (stored in `gocryptfs.diriv`) is not random. -It is deterministically derived, using *DerivePathIV*, from the encrypted +It is deterministically derived from the encrypted path to the directory. Because the encrypted path to the root directory is "" (the empty string), this means that the directory IV in the root directory is always `0xa8f7bac432ddc1cb3dc74e684d6ae48b = SHA256("\0DIRIV")`. - -DerivePathIV: Derive IVs from Encrypted Paths ----------------------------------------------- - -The *DerivePathIV* function concatenates the encrypted path with a null byte and a -salt string (one of "DIRIV", "FILEID", "BLOCK0IV"). This is -hashed with SHA256 and truncated to 128 bits (source code -[ref](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/pathiv/pathiv.go#L26)). - -![](img/reverse-derivePathIV.svg) -- cgit v1.2.3