From 3bdfac5b4d4a6f3b1348b007f2bd98449b2cd86d Mon Sep 17 00:00:00 2001 From: Jakob Unterwurzacher Date: Sat, 16 Sep 2017 16:08:12 +0200 Subject: Update forward mode crypto description for derived keys --- docs/forward_mode_crypto.md | 30 +- docs/img/derived-keys.svg | 569 +++++++++++++++++++++++++++ docs/img/file-content-encryption.svg | 213 +++++----- docs/img/file-name-encryption.svg | 131 +++--- docs/img/longnames.svg | 85 ++-- docs/img/master-key.svg | 330 ++++++++++------ docs/img/reverse-file-content-encryption.svg | 154 ++++---- docs/reverse_mode_crypto.md | 18 +- 8 files changed, 1101 insertions(+), 429 deletions(-) create mode 100644 docs/img/derived-keys.svg diff --git a/docs/forward_mode_crypto.md b/docs/forward_mode_crypto.md index 894f894..e9b4f47 100644 --- a/docs/forward_mode_crypto.md +++ b/docs/forward_mode_crypto.md @@ -1,9 +1,14 @@ -gocryptfs Security -================== +gocryptfs Cryptography +====================== gocryptfs builts upon well-known cryptographic primitives: scrypt for key derivation, AES-GCM for file content encryption and, as a world's -first for encrypted filesystems, EME for file name encryption. +first for encrypted filesystems, +EME wide-block encryption for file name encryption. + +This page describes **forward mode**, the default mode of operation, where +the files are stored encrypted on disk and the mounted filesystem provides +a plaintext view. Master Key Storage ------------------ @@ -18,6 +23,16 @@ the master key is decrypted: ![](img/master-key.svg) +Derived Keys +------------ + +Since gocryptfs v1.3, separate keys are derived from the master key for +file content and file name encryption. HKDF-SHA256 is used for the +derivation (source code: [ref1](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/cryptocore/hkdf.go) +[ref2](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/cryptocore/cryptocore.go#L66)). + +![](img/derived-keys.svg) + File Contents ------------- @@ -67,6 +82,15 @@ file, `gocryptfs.longname.[hash].name`. ![](img/longnames.svg) +Example directory listing containing an 1 MiB encrypted file with a long name: + +``` + Size Name + 16 gocryptfs.diriv + 1056786 gocryptfs.longname.nONaEDDZOrwtQdXPH1SxSFkPtOc8srIyB82ZuduqG10 + 299 gocryptfs.longname.nONaEDDZOrwtQdXPH1SxSFkPtOc8srIyB82ZuduqG10.name +``` + This method for storing long file names has zero performance impact 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 diff --git a/docs/img/derived-keys.svg b/docs/img/derived-keys.svg new file mode 100644 index 0000000..d2515b0 --- /dev/null +++ b/docs/img/derived-keys.svg @@ -0,0 +1,569 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + HKDF + Master key + + Content key + + File name key + + + HKDF + "AES-GCM file content encryption" + "EME filename encryption" + Infostring + + + + + + + + + + diff --git a/docs/img/file-content-encryption.svg b/docs/img/file-content-encryption.svg index 38a6f6b..6f054eb 100644 --- a/docs/img/file-content-encryption.svg +++ b/docs/img/file-content-encryption.svg @@ -14,7 +14,7 @@ viewBox="0 0 648.94201 263.97642" id="svg2" version="1.1" - inkscape:version="0.91 r13725" + inkscape:version="0.92+devel unknown" sodipodi:docname="file-content-encryption.svg"> @@ -109,7 +109,7 @@ @@ -137,17 +137,17 @@ borderopacity="1.0" inkscape:pageopacity="0.0" inkscape:pageshadow="2" - inkscape:zoom="1.4" - inkscape:cx="209.93662" - inkscape:cy="128.77455" + inkscape:zoom="1.979899" + inkscape:cx="325.88995" + inkscape:cy="143.0543" inkscape:document-units="px" inkscape:current-layer="layer1" - showgrid="true" + showgrid="false" showguides="false" inkscape:window-width="1920" inkscape:window-height="1016" inkscape:window-x="0" - inkscape:window-y="27" + inkscape:window-y="0" inkscape:window-maximized="1" fit-margin-top="2" fit-margin-left="2" @@ -155,7 +155,8 @@ fit-margin-bottom="2" inkscape:snap-bbox="true" inkscape:bbox-nodes="false" - inkscape:snap-bbox-midpoints="false"> + inkscape:snap-bbox-midpoints="false" + inkscape:document-rotation="0"> myfile.txt + 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">Ciphertext file File ID + 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 + 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 + 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 + 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">authentication tag Ciphertext +Ciphertext + + 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="tspan10041">  + y="272.83463" + style="font-size:60px;line-height:1.25">  ... + y="600.54089" + style="font-size:15.00295734px;line-height:1.25">... ... + y="600.54089" + style="font-size:15.00295734px;line-height:1.25">... Plaintext + 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">Plaintext AES-256-GCM + 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">AES-256-GCM /dev/urandom + 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">/dev/urandom N + y="213.29985" + 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;letter-spacing:0px;fill:#000000;fill-opacity:1">N Master key + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">Content key IV + 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;letter-spacing:0px;fill:#aa00d4">IV AAD + x="351.90231" + y="260.49326" + 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;letter-spacing:0px;fill:#37abc8">AAD + + + diff --git a/docs/img/file-name-encryption.svg b/docs/img/file-name-encryption.svg index 49eed5c..755ddab 100644 --- a/docs/img/file-name-encryption.svg +++ b/docs/img/file-name-encryption.svg @@ -12,7 +12,7 @@ viewBox="0 0 677.77079 155.50895" height="43.888088mm" width="191.28198mm" - inkscape:version="0.91 r13725" + inkscape:version="0.92+devel unknown" sodipodi:docname="file-name-encryption.svg"> + inkscape:current-layer="svg2" + inkscape:document-rotation="0" /> image/svg+xml - + @@ -195,36 +196,33 @@ id="rect4267-1" width="180.79115" height="21.25984" - x="480.00861" + x="479.25827" y="35.399475" /> Directory X + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">Directory X gocryptfs.diriv + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">gocryptfs.diriv AES-256-EME + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">AES-256-EME "letter.doc" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">"letter.doc" lrpyui0m-ypX4u0J[...] + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">lrpyui0m-ypX4u0J[...] Master key + 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;text-align:center;letter-spacing:0px;text-anchor:middle">File name key Base64 + x="313.0022" + y="83.762749" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">Base64 >255? + 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;text-align:center;letter-spacing:0px;text-anchor:middle">>255? no + 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;text-align:center;letter-spacing:0px;text-anchor:middle">no long file name handling + x="404.82153" + y="141.46291" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">long file name handling diff --git a/docs/img/longnames.svg b/docs/img/longnames.svg index c6022ba..68272da 100644 --- a/docs/img/longnames.svg +++ b/docs/img/longnames.svg @@ -12,7 +12,7 @@ viewBox="0 0 687.79717 138.28399" height="39.026821mm" width="194.11165mm" - inkscape:version="0.91 r13725" + inkscape:version="0.92+devel unknown" sodipodi:docname="longnames.svg"> + inkscape:current-layer="svg2" + inkscape:document-rotation="0" /> Directory X + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">Directory X gocryptfs.longname.[hash].name SHA256 + x="240.99684" + y="28.779612" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">SHA256 Base64 + x="348.76529" + y="28.779612" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.00342369px;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">Base64 lrpyui0m-ypX4u0J[...] in .name file [hash] gocryptfs.longname.[hash] file content + + + + + + + + + + + + + + + + + + + + + + id="path4495" /> + style="overflow:visible" + id="marker13890" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Mend"> + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + id="path13892" /> + fit-margin-bottom="2" + inkscape:document-rotation="0" + inkscape:guide-bbox="true"> + + @@ -193,105 +302,99 @@ y="14.30587" /> gocryptfs.conf + x="124.03606" + y="-8.8435535" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">gocryptfs.conf User password + x="354.80963" + y="-37.796406" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">User password Scrypt parameters + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">scrypt parameters + x="291.94489" + y="-53.149628" /> Scrypt + x="354.47162" + y="29.070705" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">scrypt AES-256-GCM + x="355.54291" + y="115.34568" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">AES-256-GCM Master key + x="518.06982" + y="115.37775" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">Master key IV + 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;letter-spacing:0px;fill:#aa00d4;text-anchor:middle;text-align:center;">IV Encrypted master key + 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">Encrypted master key IV + 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;letter-spacing:0px;text-anchor:middle;text-align:center;">IV authentication tag + 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">authentication tag Ciphertext +Ciphertext + + 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="tspan10041">  - KEK + x="385.48105" + y="74.279709" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;letter-spacing:0px">KEK + + diff --git a/docs/img/reverse-file-content-encryption.svg b/docs/img/reverse-file-content-encryption.svg index 20e7e39..89eb3ab 100644 --- a/docs/img/reverse-file-content-encryption.svg +++ b/docs/img/reverse-file-content-encryption.svg @@ -14,7 +14,7 @@ viewBox="0 0 756.54092 320.07084" id="svg2" version="1.1" - inkscape:version="0.91 r13725" + inkscape:version="0.92+devel unknown" sodipodi:docname="reverse-file-content-encryption.svg"> @@ -263,18 +263,18 @@ borderopacity="1.0" inkscape:pageopacity="0.0" inkscape:pageshadow="2" - inkscape:zoom="1" - inkscape:cx="355.10654" - inkscape:cy="79.441174" + inkscape:zoom="2" + inkscape:cx="368.72619" + inkscape:cy="71.713405" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" showguides="true" - inkscape:window-width="960" + inkscape:window-width="1920" inkscape:window-height="1016" inkscape:window-x="0" - inkscape:window-y="27" - inkscape:window-maximized="0" + inkscape:window-y="0" + inkscape:window-maximized="1" fit-margin-top="2" fit-margin-left="2" fit-margin-right="2" @@ -282,7 +282,8 @@ inkscape:snap-bbox="true" inkscape:bbox-nodes="false" inkscape:snap-bbox-midpoints="false" - inkscape:guide-bbox="true"> + inkscape:guide-bbox="true" + inkscape:document-rotation="0"> + id="guide16693" + inkscape:locked="false" /> + id="guide17163" + inkscape:locked="false" /> @@ -309,7 +312,7 @@ image/svg+xml - + @@ -341,122 +344,116 @@ y="280.31494" /> "5qbHc9O.../7GMW91..." + 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;letter-spacing:0px">"5qbHc9O.../7GMW91..." File ID + 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;letter-spacing:0px">File ID Block N + 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;letter-spacing:0px">Block N IV + 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;letter-spacing:0px">IV authentication tag + 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;letter-spacing:0px">authentication tag Ciphertext +Ciphertext + + 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;letter-spacing:0px" + id="tspan10041">  + y="272.83463" + style="font-size:60px;line-height:1.25">  ... + y="594.10767" + style="font-size:15.00295734px;line-height:1.25">... ... + y="594.10767" + style="font-size:15.00295734px;line-height:1.25">... Plaintextfilecontent AES-SIV + 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;letter-spacing:0px">AES-SIV SHA512(Master key) + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:sans-serif;text-align:center;letter-spacing:0px;text-anchor:middle">Content key IV + 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;letter-spacing:0px;fill:#aa00d4">IV AAD + 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;letter-spacing:0px;fill:#37abc8;fill-opacity:0.99607843">AAD File Name Encryption + 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;letter-spacing:0px">File Name Encryption "Photos/Team.jpg" + 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;letter-spacing:0px">"Photos/Team.jpg" encrypted path + + 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">+ N + 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;letter-spacing:0px;fill:#000000;fill-opacity:1">N derivePathIV + 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:start;letter-spacing:0px;text-anchor:start">derivePathIV FileID + 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">FileID Block0IV + 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">Block0IV