From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail.saout.de ([127.0.0.1]) by localhost (mail.saout.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id JFZaBAGD9uvE for ; Sun, 4 Sep 2011 20:22:02 +0200 (CEST) Received: from smtp.meme.com (janus.meme.com [69.17.73.118]) by mail.saout.de (Postfix) with ESMTP for ; Sun, 4 Sep 2011 20:22:01 +0200 (CEST) Received: from mofo.meme.com (unknown [192.168.1.2]) by smtp.meme.com (Postfix) with ESMTP id 8C205A061 for ; Sun, 4 Sep 2011 13:13:55 -0500 (CDT) Received: from mofo (localhost.localdomain [127.0.0.1]) by mofo.meme.com (Postfix) with ESMTP id 619E743D00 for ; Sun, 4 Sep 2011 13:13:55 -0500 (CDT) Date: Sun, 04 Sep 2011 13:13:55 -0500 From: "Karl O. Pinc" Message-Id: <1315160035.32720.2@mofo> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-w5z/UcFDWJ4As/3NA2gk" Subject: [dm-crypt] Editing patch to LUKS on-disk format specification 1.2 List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: dm-crypt@saout.de --=-w5z/UcFDWJ4As/3NA2gk Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Hi, Reading over=20 http://cryptsetup.googlecode.com/svn-history/r500/wiki/LUKS-standard/ on-disk-format.pdf LUKS On-Disk Format Specification Version 1.2 I found a number of typos and, to me, some sentence structure needing editing. Attached is a patch of the output to: ps2ascii on-disk-format.pdf on-disk-format.txt In case it helps I'm also appending wdiff output. (Look for the {+foo+} [-bar-] sorts of strings.) I didn't start reading with an eye to making corrections, these are just the ones I noticed. I couldn't find the source document in the svn cryptsetup repo.... While reading I also noted, FWIW, that in Appendex A the constants LUKS_DIGESTSIZE LUKS_SALTSIZE LUKS_NUMKEYS are undefined. (My only other comment is that I found the hyphens in the pseudo code variable names to be quite distracting because the look like minus signs.) Regards, Karl Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein --=-w5z/UcFDWJ4As/3NA2gk Content-Type: text/x-patch; charset=us-ascii; name=on-disk-format.patch Content-Disposition: attachment; filename=on-disk-format.patch Content-Transfer-Encoding: quoted-printable --- on-disk-format.txt 2011-09-04 12:48:00.000000000 -0500 +++ on-disk-format.txt.patched 2011-09-04 13:05:28.000000000 -0500 @@ -167,7 +167,7 @@ but can be changed exactly as described in the remarks above. A C referenc= e implementation using SHA1 is available from [Fru05a]. =20 -s p l i -m a t e r i a l =3D A F s p l i t ( u n s p l i t -m a t e r i a = l , l e n g t h , s t r i p e s ) +s p l i t -m a t e r i a l =3D A F s p l i t ( u n s p l i t -m a t e r i = a l , l e n g t h , s t r i p e s ) u n s p l i t -m a t e r i a l =3D AFmerge ( s p l i t -m a t e r i a l , = l e n g t h , s t r i p e s ) =20 Notice that the result of AFsplit, split-material, is stripes-times as lar= ge as @@ -198,9 +198,9 @@ =20 3. THE PARTITION HEADER 5 =20 -The input to H1(d), namely d, is partitioned into individual data junks. -The partitioning repeataly takes a data vector with the size |P | as di wi= th the -finally block (possibly shorter than |P |) dn. The transformation happens = as +The input to H1(d), namely d, is partitioned into individual data hunks. +The partitioning repeatedly takes a data vector with the size |P | as di w= ith the +final block (possibly shorter than |P |) dn. The transformation happens as follows: =20 pi =3D P (i || di) (5) @@ -318,7 +318,7 @@ slot entries in the phdr. The information about the bulk data start is wri= tten into the payload-offset field of the phdr. These values will not change du= ring the lifetime of a LUKS partition and are simply cached for safety reasons = as a -miscalculation of these values can cause data corruption (f.i. an incorrec= t start +miscalculation of these values can cause data corruption (e.g. an incorrec= t start of the bulk data can overwrite key material, same is true in reverse). =20 The master key is checksummed, so a correct master key can be detected. @@ -383,14 +383,14 @@ =20 4. LUKS OPERATIONS 9 4.2 Adding new passwords -To add a password to a LUKS partition, one has to possess an unencrypted -copy of the master key. Either this is, because the initialisation process= is still -in progress, or the user has supplied a correct password for an existing k= ey slot, -which master key could therefore be recovered. This operation is sketched = in +To add a password to a LUKS partition one has to possess an +unencrypted copy of the master key; either initialization must still +be in progress or the master key must be recovered using a valid +password to an existing key slot. The latter operation is sketched in Figure 4. =20 -Assuming we have a good copy of the master key in memory, the next step -is to fetch a salt from a random source, and the choice of a password iter= ation +Assuming we have a good copy of the master key in memory the next steps +are to fetch a salt from a random source and to choose a password iteratio= n count7. This information is written into a free - that is disabled - key s= lot of the phdr. =20 @@ -444,7 +444,7 @@ =20 ks . i t e r a t i o n -count =3D PBKDF2-I t e r a t i o n s P e r S e c o= n d * =20 -i n t e nt e d P a s s w o r d C h e c k i n g T i m e ( i n s e c o n d s= ) +i n t e n d e d P a s s w o r d C h e c k i n g T i m e ( i n s e c o n d = s ) =20 ks . s a l t =3D g e n e r a t e random v e c t o r , l e n g t h : LUKS S= ALTSIZE =20 --=-w5z/UcFDWJ4As/3NA2gk Content-Type: text/plain; charset=us-ascii; name=on-disk-format.wdiff Content-Disposition: attachment; filename=on-disk-format.wdiff Content-Transfer-Encoding: quoted-printable LUKS On-Disk Format Specification Version 1.2 Clemens Fruhwirth April 11, 2011 Document History Version Author Date Changes 1.0 clemens 22.01.2005 more clear distinction between raw data and string data by adding a byte[] data type for LUKS magic, salt and checksum data. 1.0.1 clemens 15.01.2006 corrected the hash-spec length in Figure 1 from 64 to 32 bytes as implied by offset calculation and all other assumptions in this document. 1.1 clemens 18.02.2006 Added precise AFsplit specification. Removed lrw-pla= in mode spec as the LRW standardization process is not about to be finished any time soon; will be reintroduced when a normative documentat= ion is released by SISWG. Extended introduction text. Thanks to Sarah Dean for = providing valuable feedback with respect to the AFsplit specification. 1.1.1 clemens 08.12.2008 Clarify IV reference point for decrypt/encrypt. Th= anks to Michael Gorven for this suggestion. 1.2 mbroz 11.04.2011 Fix hash block size/digest size AF comment. Clarify ma= ster key digest iteration count. Add XTS mode reference. Some minor typo fixes. Add reference to NIST SP 800-132. 1=0C 1. OVERVIEW 2 Introduction LUKS is short for "Linux Unified Key Setup". It has initially been develope= d to remedy the unpleasantness a user experienced that arise from deriving th= e encryption setup from changing user space, and forgotten command line argum= ents. The result of this changes are an unaccessible encryption storage. Th= e reason for this to happen was, a unstandardised way to read, process and se= t up encryption keys, and if the user was unlucky, he upgraded to an incompatibl= e version of user space tools that needed a good deal of knowledge to use wit= h old encryption volumes, see [Fru03]. LUKS has been invented to standardise key setup. But the project became bigger as anticipated, because standards creation involves decision making, which in turn demands for a justification of these decision. An overspring = of this effort can be found as TKS1 [Fru04], a design model for secure key processi= ng from entropy-weak sources1. LUKS is also treaded extensivly in Chapters 5 a= nd 6 in "New Methods in Hard Disk Encryption", which provides a theoretic base for the security of PBKDF2 passwords and anti-forensic information splittin= g. See [Fru05b]. LUKS is the proof-of-concept implementation for TKS1. In LUKS 1.0, the implementation switched to TKS2, a varient of TKS1, introduced in [Fru05b]. Additionally to the security provided by the TKS1 model, LUKS gives the use= r the ability to associate more than one password with an encrypted partition= . Any of these passwords can be changed or revoked in a secure manner. This document specifies the structure, syntax and semantic of the partition header and the key material. The LUKS design can be used with any cipher or cipher mode, but for compatibility reasons, LUKS standarises cipher name= s and cipher modes. While the reference implementation is using dm-crypt, Linux' kernel facilit= y for bulk data encryption, it is not tied to it in any particular way. Next to the reference implementation which works on Linux, there is a Windo= ws implementation named FreeOTFE provided by Sarah Dean, see http://www.freeotfe.org. 1 Overview A rough overall disk layout follows: LUKS phdr KM1 KM2 . . . KM8 bulk data A LUKS partition starts with the LUKS partition header (phdr) and is followed by key material (labelled KM1, KM2 . . . KM8 in figure). After the key material, the bulk data is located, which is encrypted by the master ke= y. The phdr contains information about the used cipher, cipher mode, the key length, a uuid and a master key checksum. Also, the phdr contains information about the key slots. Every key slot is associated with a key material section after the phdr. When a key slot is active, the key slot stores an encrypted copy of the master key in its k= ey material section. This encrypted copy is locked by a user password. Supplyi= ng 1such as a user password=0C 2. PREREQUISITES 3 this user password unlocks the decryption for the key material, which store= s the master key. The master key in turn unlocks the bulk data. For a key slo= t, all parameters how to decrypt its key material with a given user password a= re stored in the phdr (f.e. salt, iteration depth). A partition can have as many user passwords as there are key slots. To access a partition, the user has to supply only one of these passwords. If = a password is changed, the old copy of the master key encrypted by the old password must be destroyed. Peter Gutmann has shown in [Gut96], how data destruction shall be done to maximise the chance, that no traces are left o= n the disk. Usually the master key comprises only 16 or 32 bytes. This small amount of data can easily be remapped as a whole to a reserved area. This action is taken by modern hard disk firmware, when a sector is likely to be= come unreadable due to mechanical wear. The original sectors become unaccessible and any traces of key data can't be purged if necessary. To counter this problem, LUKS uses the anti-forensic information splitter to artificially inflate the volume of the key, as with a bigger data set th= e probability that the whole data set is remapped drops exponentially. The = inflated encrypted master key is stored in the key material section. These sections = are labelled as "KMx" in the figure above. 2 Prerequisites 2.1 Block encryption system Instead of using cipher implementations like AES or Twofish internally, LUK= S reuses the block encryption facility used for the bulk data. The following = syntax is used in the pseudocode: enc-da t a =3D e n c r y p t ( c i p h e r -name , c i p h e r -mode , key = , o r i g i n a l , o r i g i n a l -l e n g t h ) o r i g i n a l =3D d e c r y p t ( c i p h e r -name , c i p h e r -mode ,= key , enc-data , o r i g i n a l -l e n g t h ) If the encryption primitive requires a certain block size, incomplete block= s are padded with zero. The zeros are stripped upon decryptions.2 2.2 Cryptographic hash A cryptographic hash is necessary for the following two prerequisites. In PBKDF2 a pseudo-random function is needed, and for AFsplitting a diffusion function is needed. The pseudo-random function needs to be parameterisable, therefore the hash function is used in a HMAC setup [BCK97]. The following syntaxes may omit the hash-spec parameter, because the following pseudo code does not need a great variation of this parameter. Th= e parameter can be obtained from the partition header and will not change, on= ce initialised. 2These primitives are also used for key material en/decryption. The key mat= erial is always aligned to sector boundaries. If the block size of the underlaying e= ncryption primitive is larger than one sector, the pseudocode of section 4.1 has to be changed = respectively.=0C 2. PREREQUISITES 4 2.3 PBKDF2 LUKS needs to process password from entropy-weak sources like keyboard input. PKCS #5's password based key derive function 2 (PBKDF2) has been defined for the purpose to enhance the security properties of entropy-weak password, see [Kal97]. Therefore, LUKS depends on a working implementation of PBKDF2. LUKS uses SHA1 per default as the pseudorandom function (PRF) but any other hash function can be put in place by setting the hashsp= ec field. In the pseudo code, the following syntax is used: r e s u l t =3D PBKDF2( password , s a l t , i t e r a t i o n -count , d e r i v e d -key-l e n g t h ) Notice that the result of this function depends on the current setting of h= ashspec but the parameter has been omitted. Think of hash-spec as sort of a= n environment variable. 2.4 AF-Splitter LUKS uses anti-forensic information splitting as specified in [Fru05b]. The underlaying diffusion function shall be SHA1 for the reference implementati= on, but can be changed exactly as described in the remarks above. A C reference implementation using SHA1 is available from [Fru05a]. s p l i {+t+} -m a t e r i a l =3D A F s p l i t ( u n s p l i t -m a t e r= i a l , l e n g t h , s t r i p e s ) u n s p l i t -m a t e r i a l =3D AFmerge ( s p l i t -m a t e r i a l , l= e n g t h , s t r i p e s ) Notice that the result of AFsplit, split-material, is stripes-times as larg= e as the original, that is length * stripes bytes. Notice that the length parame= ter is the length of the original content and not the length of the split-material= array. When D is the unsplit material, H is a diffusion function, and n is the str= ipe number, AFsplit returns s1; s2 : : : sn where s1 : : : sn-1 are randomly ch= osen while sn is computed according to: d0 =3D 0 (1) dk =3D H(dk-1 \Phi sk) (2) sn =3D dn-1 \Phi D (3) To reverse the process, AFmerge computes dn-1 and recovers D from: D =3D dn-1 \Phi sn (4) 2.4.1 H1 H1 is a hash function with an underlaying hash function P .3 H1 can operate on a variable amount of data, hence it is constructed for hash extension. T= he underlaying hash function is SHA1, we use it solely in LUKS. We use |P | to denote the digest size of P , for SHA1 it is 160 bit. 3H1's function definition stems from an implementation error that I'm respo= nsible for. Do not try to analyse it, the structure given here is specified according t= o this implementation error and hence is a mistake itself. H2 is the correct hash extension as or= iginally envisioned.=0C 3. THE PARTITION HEADER 5 The input to H1(d), namely d, is partitioned into individual data [-junks.-= ] {+hunks.+} The partitioning [-repeataly-] {+repeatedly+} takes a data vector with the = size |P | as di with the [-finally-] {+final+} block (possibly shorter than |P |) dn. The transformation happens= as follows: pi =3D P (i || di) (5) The end of the last block pn is cropped, so that its length is |dn|. The in= teger i has to be delivered to the hash as an unsigned 32-bit integer in big-endi= en format. 2.4.2 H2 All remarks for H1 apply, except pi =3D P (i || d) (6) Notice the missing subscript of d in contrast to (5). This version will be = used in future LUKS revisions.4 3 The partition header 3.1 Version 1 The LUKS partition header has the layout as described in Figure 1. It start= s at sector 0 of the partition. LUKS uses 3 primitive data types in its heade= r, * unsigned integer, 16 bit, stored in big endian * unsigned integer, 32 bit, stored in big endian * char[], a string stored as null terminated sequence of 8-bit characters5 * byte[], a sequence of bytes, treated as binary. Further, there is an aggregated data type key slot, which elements are desc= ribed in Figure 2. A reference definition as C struct for phdr is available in the appendix. 3.2 Forward compatibility LUKS' forward compatibility centers around the on-disk format. Future versi= ons are required to be able to correctly interpret older phdr versions. Fut= ure versions are not required to be able to generate old versions of the phdr. 4The transition has not happend yet. It is likely that the transition will = occour in conjunction with a version nummer bump to Version 2. Do not use H2 until th= en. 5also known as C string=0C 3. THE PARTITION HEADER 6 start offset field name length data type description 0 magic 6 byte[] magic for LUKS partition header, see LUKS MAGIC 6 version 2 uint16 t LUKS version 8 cipher-name 32 char[] cipher name specification 40 cipher-mode 32 char[] cipher mode specification 72 hash-spec 32 char[] hash specification 104 payload-offset 4 uint32 t start offset of the bulk data (in sectors) 108 key-bytes 4 uint32 t number of key bytes 112 mk-digest 20 byte[] master key checksum from PBKDF2 132 mk-digest-salt 32 byte[] salt parameter for master key PBKDF2 164 mk-digest-iter 4 uint32 t iterations parameter for master key PBKDF2 168 uuid 40 char[] UUID of the partition 208 key-slot-1 48 key slot key slot 1 256 key-slot-2 48 key slot key slot 2 . . . . . . . . . . . . . . . 544 key-slot-8 48 key slot key slot 8 592 total phdr size Figure 1: PHDR layout offset field name length data type description 0 active 4 unit32 t state of keyslot, enabled/disabled 4 iterations 4 uint32 t iteration parameter for PBKDF2 8 salt 32 byte[] salt parameter for PBKDF2 40 key-material-offset 4 uint32 t start sector of key material 44 stripes 4 uint32 t number of anti-forensic stripes Figure 2: key slot layout=0C 4. LUKS OPERATIONS 7 A LUKS implementation encountering a newer phdr version should not try to interpret it, and return an error. Of course, an error should be returne= d, if the phdr's magic is not present. 4 LUKS operations 4.1 Initialisation The initialisation process takes a couple of parameters. First and most imp= ortant, the master key. This key is used for the bulk data. This key must b= e created from an entropy strong (random) source, as the overcoming of entrop= y weak keys is one of LUKS' main objectives. For the following remarks, the pseudo code is available as Figure 3. Further, the user specifices the cipher setup details that are stored in th= e cipher-name and cipher-mode fields. Although no LUKS operation manipulates = these two strings, it is likely that the LUKS implementation will have to convert it into something suitable for the underlaying cipher system, as= the interface is not likely to be as ideal as described in Section 2.1. The overall disk layout depends on the length of the key material sections following the phdr. While the phdr is always constant in size, the key mate= rial section size depends on the length of the master key and the number of stri= pes used by the anti-forensic information splitter. The exact disk layout is ge= nerated by computing the size for the phdr and a key material section in se= ctors rounded up. Then the disk is filled sector-wise by phdr first, and followin= g key material section 1 till key material section 8. After the eight key mat= erial section, the bulk data starts. After determining the exact key layout and boundaries between phdr, key material and bulk data, the key material locations are written into the key slot entries in the phdr. The information about the bulk data start is writ= ten into the payload-offset field of the phdr. These values will not change dur= ing the lifetime of a LUKS partition and are simply cached for safety reasons a= s a miscalculation of these values can cause data corruption [-(f.i.-] {+(e.g.+= } an incorrect start of the bulk data can overwrite key material, same is true in reverse). The master key is checksummed, so a correct master key can be detected. To future-proof the checksumming, a hash is not only applied once but multi= ple times. In fact, the PBKDF2 primitive is reused. The master key is feed into the PBKDF2 process as if it were a user password. After the iterative hashi= ng, the random chosen salt, the iteration count6 and result are stored in the p= hdr. Although everything is correctly initialised up to this point, the initiali= sation process should not stop here. Without an active key slot the partiti= on is useless. At least one key slot should be activated from the master key stil= l in memory. 6Master key iteration count was set to 10 in previous revisions of LUKS. Fo= r new devices the iteration count should be determined by benchmarking with suggested min= imum of 1000 iterations.=0C 4. LUKS OPERATIONS 8 masterKeyLength =3D d e f i n e d by u s e r masterKey =3D g e n e r a t e random v e c t o r , l e n g t h : masterKeyL= eng th phdr . magic =3D LUKS MAGIC phdr . v e r s i o n =3D 1 phdr . c i p h e r -name =3D as s u p p l i e d by u s e r phdr . c i p h e r -mode =3D as s u p p l i e d by u s e r phdr . key-b y t e s =3D masterKey phdr . mk-d i g e s t -s a l t =3D g e n e r a t e random v e c t o r , l e n g t h : LUKS SALTSIZE // benchmarked a c c o r d i n g t o u s e r i n p u t // ( i n o l d e r v e r s i o n s f i x e d t o 10) phdr . mk-d i g e s t -i t e r a t i o n -co unt =3D as above phdr . mk-d i g e s t =3D PBKDF2( masterKey , phdr . mk-d i g e s t -s a l t , phdr . mk-d i g e s t -i t e r a t i o n -count , LUKS DIGESTSIZE ) s t r i p e s =3D LUKS STRIPES o r u s e r d e f i n e d // i n t e g e r d i v i s i o n s , r e s u l t rounded down : b a s e O f f s e t =3D ( s i z e o f phdr )/ SECTOR SIZE + 1 k e y M a t e r i a l S e c t o r s =3D ( s t r i p e s * masterKeyLength )= / SECTOR SIZE + 1 f o r each k e y s l o t i n phdr a s ks { ks . a c t i v e =3D LUKS KEY DISABLED ks . s t r i p e s =3D s t r i p e s ks . key-m a t e r i a l -o f f s e t =3D b a s e O f f s e t b a s e O f f s e t =3D b a s e O f f s e t + k e y M a t e r i a l S e c t= o r s } phdr . pa y loa d -o f f s e t =3D b a s e O f f s e t phdr . uu i d =3D g e n e r a t e u u i d w r i t e phdr t o d i s k Figure 3: Pseudo code for partition initialisation=0C 4. LUKS OPERATIONS 9 4.2 Adding new passwords To add a password to a LUKS [-partition,-] {+partition+} one has to possess= an unencrypted copy of the master [-key. Either this is, because the initialis= ation process is-] {+key; either initialization must+} still {+be+} in [-progress,-] {+progress+} or the [-user has supplied-] {+master = key must be recovered using+} a [-correct-] {+valid+} password [-for-] {+to+} an existing key [-slot, which master key could therefore be recovered. This-] {+slot. The latter+}= operation is sketched in Figure 4. Assuming we have a good copy of the master key in [-memory,-] {+memory+} th= e next [-step is-] {+steps are+} to fetch a salt from a random [-source,-] {+source+} and [-the choice= of-] {+to choose+} a password iteration count7. This information is written into a free - that is disabled - key sl= ot of the phdr. The user password is entered and processed by PBKDF2. The master key is then split by the AFsplitter into a number of stripes. The number of stripe= s is determined by the stripes field already stored in the key slot. The split r= esult is written into the key material section, but encrypted. The encryption uses t= he same cipher setup as the bulk data (cipher type, cipher mode, ...), but whi= le for the bulk data the master key is used, the key material section is keyed= by the result of the PBKDF2. 4.3 Master key recovery To access the payload bulk data, the master key has to be recovered. Compar= e the pseudo code in Figure 5. First, the user supplies a password. Then the password is processed by PBKDF2 for every active key slot individually and an attempt is made to recover the master key. The recovery is successful, when a master key candi= date correctly checksums against the master key checksum stored in the phdr. Bef= ore this can happen, the master key candidate is read from storage, decrypted a= nd after decryption processed by the anti-forensic information splitter in rev= erse gear, that is AFmerge. When the checksumming of the master key succeeds for one key slot, the correct user key was given and the partition is successfully opened. 4.4 Password revocation The key material section is wiped according to Peter Gutmann's data erasure principals [Gut96]. To wipe the sectors containing the key material, start = from the sector as recorded in key slot's key-material-offset field, and proceed= for phdr.key-bytes * ks.stripes bytes. 7The iteration count should be determined by benchmarking with suggested mi= nimum of 1000 iterations.=0C 4. LUKS OPERATIONS 10 masterKey =3D must be a v a i l a b l e , e i t h e r be c a u s e i t i s = s t i l l i n memory from i n i t i a l i s a t i o n o r b e c a u s e i t has been r e c o v e r e d by a c o r r e c t pas swo rd masterKeyLength =3D phdr . key-b y t e s e m p t y K e y S l o t I nd e x =3D f i n d i n a c t i v e key s l o t i = n d e x i n phdr by s c a n n i n g t he k e y s l o t . a c t i v e f i e l d f o r LUKS KEY DISABLED . k e y s l o t ks =3D phdr . k e y s l o t s [ e m p t y K e y S l o t In de= x ] PBKDF2-I t e r a t i o n s P e r S e c o n d =3D benchmark s ys tem ks . i t e r a t i o n -count =3D PBKDF2-I t e r a t i o n s P e r S e c o = n d * i n t e [-nt-] {+n d+} e d P a s s w o r d C h e c k i n g T i m e ( i n s = e c o n d s ) ks . s a l t =3D g e n e r a t e random v e c t o r , l e n g t h : LUKS SA= LTSIZE s p l i t K e y =3D A F s p l i t ( masterKey , // s o u r c e masterKeyLength , // s o u r c e l e n g t h ks . s t r i p e s ) // number o f s t r i p e s s p l i t K e y L e n g t h =3D ma sterKeyLength * ks . s t r i p e s pwd =3D r e a d pas sw or d from u s e r i n p u t pwd-PBKDF2ed =3D PBKDF2( password , ks . s a l t , ks . i t e r a t i o n -count masterKeyLength ) // key s i z e i s t h e same // a s f o r t h e b u l k dat a e nc r y p t e dK ey =3D e n c r y p t ( phdr . c i p h e r -name , // c i = p h e r name phdr . c i p h e r -mode , // c i p h e r mode pwd-PBKDF2ed , // key s p l i t K e y , // c o n t e n t s p l i t K e y L e n g t h ) // c o n t e n t l e n g t h w r i t e t o p a r t i t i o n ( e nc ry pte dK ey , // s o u r c e ks . key-m a t e r i a l -o f f s e t , // s e c t o r number s p l i t K e y L e n g t h ) // l e n g t h i n b y t e s ks . a c t i v e =3D LUKS KEY ACTIVE // mark key as a c t i v e i n phdr updat e k e y s l o t ks i n phdr Figure 4: Pseudo code for key creation=0C 4. LUKS OPERATIONS 11 r e a d phdr from d i s k check f o r c o r r e c t LUKS MAGIC and c o m p a t i b l e v e r s i o n = number masterKeyLength =3D phdr . key-b y t e s pwd =3D r e a d pas sw or d from u s e r i n p u t f o r each a c t i v e k e y s l o t i n phdr do a s k s { pwd-PBKDF2ed =3D PBKDF2( pwd , ks . s a l t , ks . i t e r a t i o n -count masterKeyLength ) r e a d from p a r t i t i o n ( encr y ptedK ey , // d e s t i n a t i o n ks . key-m a t e r i a l -o f f s e t , // s e c t o r number masterKeyLength * ks . s t r i p e s ) // number o f b y t e s s p l i t K e y =3D d e c r y p t ( phdr . c i p h e r S p e c , // c i p h= e r s p e c . pwd-PBKDF2ed , // key encr y pte dK ey , // c o n t e n t e n c r y p t e d ) // c o n t e n t l e n g t h m a s t e r K ey Ca nd id a t e =3D AFmerge ( s p l i t K e y , ma s ter k = ey Leng th , ks . s t r i p e s ) MKCandidate-PBKDF2ed =3D PBKDF2( m as ter Key Candidate , phdr . mk-d i g e s t -s a l t , phdr . mk-d i g e s t -i t e r , LUKS DIGEST SIZE ) i f e q u a l ( MKCandidate-PBKDF2ed , phdr . mk-d i g e s t ) { b r e a k l o o p and r e t u r n m a s t e r K ey Ca nd id a t e a s c o r r e c t m a st er key } } r e t u r n e r r o r , pas swo rd do es not match any k e y s l o t Figure 5: Pseudo code for master key recovery=0C 5. CONSTANTS 12 4.5 Password changing The password changing is a synthetic operating of "master key recovery", "n= ew password adding", and "old password revocation". 5 Constants All strings and characters are to be encoded in ASCII. Symbol Value Description LUKS MAGIC {'L','U','K','S', 0xBA,0xBE} partition header starts with magic LUKS DIGESTSIZE 20 length of master key checksum LUKS SALTSIZE 32 length of the PBKDF2 salts LUKS NUMKEYS 8 number of key slots LUKS KEY DISABLED 0x0000DEAD magic for disabled key slot in keyblock[i].active LUKS KEY ENABLED 0x00AC71F3 magic for enabled key slot in keyblock[i].active LUKS STRIPES 4000 number of stripes for AFsplit. See [Fru05b] for rationale.=0C BIBLIOGRAPHY 13 Bibliography [BCK97] Mihir Bellare, Ran Canetti, and Hugo Krawczyk. The HMAC papers. http://www.cs.ucsd.edu/users/mihir/papers/hmac.html, 1996-1997. [Fru03] Clemens Fruhwirth. Cryptoloop 2.4.22 to cryptoloop 2.5.x migration guide. http://clemens.endorphin.org/Cryptoloop_Migration_Guide, 2003. [Fru04] Clemens Fruhwirth. TKS1 - An anti-forensic, two level, and iterated key setup scheme. http://clemens.endorphin.org/publications, 2004. [Fru05a] Clemens Fruhwirth. Fruhwirth's Cryptography Website. http://clemens.endorphin.org/cryptography, 2005. [Fru05b] Clemens Fruhwirth. New methods in hard disk encryption. http://clemens.endorphin.org/publications, 2005. [Gut96] Peter Gutmann. Secure Deletion of Data from Magnetic and Solid-State Memory. http://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html, 1996. [Kal97] Burt Kaliski. RFC 2898; PKCS #5: Password-Based Cryptography Specification Version 2.0. http://www.faqs.org/rfcs/rfc2898.html, 1996-1997. [TBBC10] Meltem Snmez Turan, Elaine Barker, William Burr, and Lily Chen. Recommendation for password-based key derivation, part 1: Storag= e applications. NIST SP 800-132, http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf, 2010.=0C APPENDIX A. PHDR AS C STRUCT 14 A PHDR as C struct #d e f i n e LUKS MAGIC L 6 #d e f i n e LUKS CIPHERNAME L 32 #d e f i n e LUKS CIPHERMODE L 32 #d e f i n e LUKS HASHSPEC L 32 #d e f i n e UUID STRING L 40 s t r u c t l u k s p h d r { c h a r magic [ LUKS MAGIC L ] ; u i n t 1 6 t v e r s i o n ; c h a r cipherName [ LUKS CIPHERNAME L ] ; c h a r cipherMode [ LUKS CIPHERMODE L ] ; c h a r hashSpec [ LUKS HASHSPEC L ] ; u i n t 3 2 t p a y l o a d O f f s e t ; u i n t 3 2 t k e y B y t e s ; c h a r mkDigest [ LUKS DIGESTSIZE ] ; c h a r m k D i g e s t S a l t [ LUKS SALTSIZE ] ; u i n t 3 2 t m k D i g e s t I t e r a t i o n s ; c h a r u u i d [ UUID STRING L ] ; s t r u c t { u i n t 3 2 t a c t i v e ; /* parameters f o r PBKDF2 p r o c e s s i n g */ u i n t 3 2 t p a s s w o r d I t e r a t i o n s ; c h a r p a s s w o r d S a l t [ LUKS SALTSIZE ] ; /* parameters f o r AF s t o r e / l o a d */ u i n t 3 2 t k e y M a t e r i a l O f f s e t ; u i n t 3 2 t s t r i p e s ; } k e y b l o c k [ LUKS NUMKEYS ] ; } ; B Cipher and Hash specification registry Even if the cipher-name and cipher-mode strings are not interpreted by any LUKS operation, they must have the same meaning for all implementations to achieve compatibility among different LUKS-based implementations. LUKS has to ensure that the underlaying cipher system can utilise the cipher nam= e and cipher mode strings, and as these strings might not always be native to= the cipher system, LUKS might need to map them into something appropriate. Valid cipher names are listed in Table 1. Valid cipher modes are listed in Table 2. By contract, cipher modes using IVs and tweaks must start from the all-zero IV/tweak. This applies for all calls to the encrypt/decrypt primitives especially when handling key materi= al. Further, these IVs/tweaks cipher modes usually cut the cipher stream into independent blocks by reseeding tweaks/IVs at sector boundaries. The all-ze= ro=0C APPENDIX B. CIPHER AND HASH SPECIFICATION REGISTRY 15 cipher name normative document aes Advanced Encryption Standard - FIPS PUB 197 twofish Twofish: A 128-Bit Block Cipher http://www.schneier.com/paper-twofi= sh-paper.html serpent http://www.cl.cam.ac.uk/~rja14/serpent.html cast5 RFC 2144 cast6 RFC 2612 Table 1: Valid cipher names mode description ecb The cipher output is used directly. cbc-plain The cipher is operated in CBC mode. The CBC chaining is cut every sector, and reinitialised with the sector number as initial vector (converted to 32-bit and to little-endian). This mode is specified in [Fru05b], Chapter 4. cbc-essiv:hash The cipher is operated in ESSIV mode using hash for generating the IV key for the original key. For instance, when using sha256 as hash, the cipher mode spec is "cbcessiv:sha256". ESSIV= is specified in [Fru05b], Chapter 4. xts-plain64 http://grouper.ieee.org/groups/1619/email/pdf00086.pdf, plain64 is 64-bit version of plain initial vector Table 2: Valid cipher modes hash-spec string normative document sha1 RFC 3174 - US Secure Hash Algorithm 1 (SHA1) sha256 SHA variant according to FIPS 180-2 sha512 SHA variant according to FIPS 180-2 ripemd160 http://www.esat.kuleuven.ac.be/~bosselae/ripemd160.html Table 3: Valid hash specifications IV/tweak requirement for the first encrypted/decrypted block is equivalent = to the requirement that the first block is defined to rest at sector 0. Table 3 lists valid hash specs for hash-spec field. A compliant implementat= ion does not have to support all cipher, cipher mode or hash specifications= .=0C --=-w5z/UcFDWJ4As/3NA2gk--