요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
Integrity tree
verity.rst:164-236Verified boot의 rooted trust에서 block별 SHA-256 tree와 depth-ordered on-disk hash block을 검증하는 흐름을 설명합니다.
Status and tools
verity.rst:237-265Valid·Corruption status와 dmsetup, veritysetup format·create 예제를 보존합니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
=========
dm-verity
=========
Device-Mapper's "verity" target provides transparent integrity checking of
block devices using a cryptographic digest provided by the kernel crypto API.
This target is read-only.
Construction Parameters
=======================
::
<version> <dev> <hash_dev>
<data_block_size> <hash_block_size>
<num_data_blocks> <hash_start_block>
<algorithm> <digest> <salt>
[<#opt_params> <opt_params>]
<version>
This is the type of the on-disk hash format.
0 is the original format used in the Chromium OS.
The salt is appended when hashing, digests are stored continuously and
the rest of the block is padded with zeroes.
1 is the current format that should be used for new devices.
The salt is prepended when hashing and each digest is
padded with zeroes to the power of two.
<dev>
This is the device containing data, the integrity of which needs to be
checked. It may be specified as a path, like /dev/sdaX, or a device number,
<major>:<minor>.
<hash_dev>
This is the device that supplies the hash tree data. It may be
specified similarly to the device path and may be the same device. If the
same device is used, the hash_start should be outside the configured
dm-verity device.
<data_block_size>
The block size on a data device in bytes.
Each block corresponds to one digest on the hash device.
<hash_block_size>
The size of a hash block in bytes.
<num_data_blocks>
The number of data blocks on the data device. Additional blocks are
inaccessible. You can place hashes to the same partition as data, in this
case hashes are placed after <num_data_blocks>.
<hash_start_block>
This is the offset, in <hash_block_size>-blocks, from the start of hash_dev
to the root block of the hash tree.
<algorithm>
The cryptographic hash algorithm used for this device. This should
be the name of the algorithm, like "sha1".
<digest>
The hexadecimal encoding of the cryptographic hash of the root hash block
and the salt. This hash should be trusted as there is no other authenticity
beyond this point.
<salt>
The hexadecimal encoding of the salt value.
<#opt_params>
Number of optional parameters. If there are no optional parameters,
the optional parameters section can be skipped or #opt_params can be zero.
Otherwise #opt_params is the number of following arguments.
Example of optional parameters section:
1 ignore_corruption
ignore_corruption
Log corrupted blocks, but allow read operations to proceed normally.
restart_on_corruption
Restart the system when a corrupted block is discovered. This option is
not compatible with ignore_corruption and requires user space support to
avoid restart loops.
panic_on_corruption
Panic the device when a corrupted block is discovered. This option is
not compatible with ignore_corruption and restart_on_corruption.
restart_on_error
Restart the system when an I/O error is detected.
This option can be combined with the restart_on_corruption option.
panic_on_error
Panic the device when an I/O error is detected. This option is
not compatible with the restart_on_error option but can be combined
with the panic_on_corruption option.
ignore_zero_blocks
Do not verify blocks that are expected to contain zeroes and always return
zeroes instead. This may be useful if the partition contains unused blocks
that are not guaranteed to contain zeroes.
use_fec_from_device <fec_dev>
Use forward error correction (FEC) to recover from corruption if hash
verification fails. Use encoding data from the specified device. This
may be the same device where data and hash blocks reside, in which case
fec_start must be outside data and hash areas.
If the encoding data covers additional metadata, it must be accessible
on the hash device after the hash blocks.
Note: block sizes for data and hash devices must match. Also, if the
verity <dev> is encrypted the <fec_dev> should be too.
fec_roots <num>
Number of generator roots. This equals to the number of parity bytes in
the encoding data. For example, in RS(M, N) encoding, the number of roots
is M-N.
fec_blocks <num>
The number of encoding data blocks on the FEC device. The block size for
the FEC device is <data_block_size>.
fec_start <offset>
This is the offset, in <data_block_size> blocks, from the start of the
FEC device to the beginning of the encoding data.
check_at_most_once
Verify data blocks only the first time they are read from the data device,
rather than every time. This reduces the overhead of dm-verity so that it
can be used on systems that are memory and/or CPU constrained. However, it
provides a reduced level of security because only offline tampering of the
data device's content will be detected, not online tampering.
Hash blocks are still verified each time they are read from the hash device,
since verification of hash blocks is less performance critical than data
blocks, and a hash block will not be verified any more after all the data
blocks it covers have been verified anyway.
root_hash_sig_key_desc <key_description>
This is the description of the USER_KEY that the kernel will lookup to get
the pkcs7 signature of the roothash. The pkcs7 signature is used to validate
the root hash during the creation of the device mapper block device.
Verification of roothash depends on the config DM_VERITY_VERIFY_ROOTHASH_SIG
being set in the kernel. The signatures are checked against the builtin
trusted keyring by default, or the secondary trusted keyring if
DM_VERITY_VERIFY_ROOTHASH_SIG_SECONDARY_KEYRING is set. The secondary
trusted keyring includes by default the builtin trusted keyring, and it can
also gain new certificates at run time if they are signed by a certificate
already in the secondary trusted keyring.
try_verify_in_tasklet
If verity hashes are in cache and the IO size does not exceed the limit,
verify data blocks in bottom half instead of workqueue. This option can
reduce IO latency. The size limits can be configured via
/sys/module/dm_verity/parameters/use_bh_bytes. The four parameters
correspond to limits for IOPRIO_CLASS_NONE, IOPRIO_CLASS_RT,
IOPRIO_CLASS_BE and IOPRIO_CLASS_IDLE in turn.
For example:
<none>,<rt>,<be>,<idle>
4096,4096,4096,4096
Theory of operation
===================
dm-verity is meant to be set up as part of a verified boot path. This
may be anything ranging from a boot using tboot or trustedgrub to just
booting from a known-good device (like a USB drive or CD).
When a dm-verity device is configured, it is expected that the caller
has been authenticated in some way (cryptographic signatures, etc).
After instantiation, all hashes will be verified on-demand during
disk access. If they cannot be verified up to the root node of the
tree, the root hash, then the I/O will fail. This should detect
tampering with any data on the device and the hash data.
Cryptographic hashes are used to assert the integrity of the device on a
per-block basis. This allows for a lightweight hash computation on first read
into the page cache. Block hashes are stored linearly, aligned to the nearest
block size.
If forward error correction (FEC) support is enabled any recovery of
corrupted data will be verified using the cryptographic hash of the
corresponding data. This is why combining error correction with
integrity checking is essential.
Hash Tree
---------
Each node in the tree is a cryptographic hash. If it is a leaf node, the hash
of some data block on disk is calculated. If it is an intermediary node,
the hash of a number of child nodes is calculated.
Each entry in the tree is a collection of neighboring nodes that fit in one
block. The number is determined based on block_size and the size of the
selected cryptographic digest algorithm. The hashes are linearly-ordered in
this entry and any unaligned trailing space is ignored but included when
calculating the parent node.
The tree looks something like:
alg = sha256, num_blocks = 32768, block_size = 4096
::
[ root ]
/ . . . \
[entry_0] [entry_1]
/ . . . \ . . . \
[entry_0_0] . . . [entry_0_127] . . . . [entry_1_127]
/ ... \ / . . . \ / \
blk_0 ... blk_127 blk_16256 blk_16383 blk_32640 . . . blk_32767
On-disk format
==============
The verity kernel code does not read the verity metadata on-disk header.
It only reads the hash blocks which directly follow the header.
It is expected that a user-space tool will verify the integrity of the
verity header.
Alternatively, the header can be omitted and the dmsetup parameters can
be passed via the kernel command-line in a rooted chain of trust where
the command-line is verified.
Directly following the header (and with sector number padded to the next hash
block boundary) are the hash blocks which are stored a depth at a time
(starting from the root), sorted in order of increasing index.
The full specification of kernel parameters and on-disk metadata format
is available at the cryptsetup project's wiki page
https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity
Status
======
V (for Valid) is returned if every check performed so far was valid.
If any check failed, C (for Corruption) is returned.
Example
=======
Set up a device::
# dmsetup create vroot --readonly --table \
"0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\
"4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
"1234000000000000000000000000000000000000000000000000000000000000"
A command line tool veritysetup is available to compute or verify
the hash tree or activate the kernel device. This is available from
the cryptsetup upstream repository https://gitlab.com/cryptsetup/cryptsetup/
(as a libcryptsetup extension).
Create hash on the device::
# veritysetup format /dev/sda1 /dev/sda2
...
Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
Activate the device::
# veritysetup create vroot /dev/sda1 /dev/sda2 \
4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Read-only block integrity target
1-8Device-Mapper의 `verity` target은 kernel crypto API가 제공하는 cryptographic digest를 사용해 block device의 integrity를 투명하게 검사합니다. 이 target은 read-only입니다.
Data와 hash tree를 신뢰하는 root digest까지 검증한 뒤에만 block을 반환합니다.
Construction parameter와 hash format
9-77dm-verity table의 construction parameter 형식은 다음과 같습니다.
::
<version> <dev> <hash_dev>
<data_block_size> <hash_block_size>
<num_data_blocks> <hash_start_block>
<algorithm> <digest> <salt>
[<#opt_params> <opt_params>]`version`은 on-disk hash format type입니다. Version 0은 Chromium OS에서 사용한 원래 format입니다. Hashing할 때 salt를 뒤에 붙이고 digest를 연속해서 저장하며 block의 나머지는 zero로 padding합니다.
Version 1은 새 device에 사용해야 하는 현재 format입니다. Hashing할 때 salt를 앞에 붙이고 각 digest를 2의 거듭제곱 크기까지 zero padding합니다.
`dev`는 integrity를 검사할 data device입니다. `/dev/sdaX` 같은 path 또는 `<major>:<minor>` device number로 지정할 수 있습니다. `hash_dev`는 hash tree data를 제공하는 device이며 같은 방식으로 지정하고 data device와 같아도 됩니다. 같은 device를 사용한다면 `hash_start`는 구성된 dm-verity device 범위 밖이어야 합니다.
`data_block_size`는 data device의 byte 단위 block size이며 각 block은 hash device의 digest 하나에 대응합니다. `hash_block_size`는 hash block의 byte 단위 크기입니다.
`num_data_blocks`는 data device의 data block 수입니다. 그 이후 block에는 접근할 수 없습니다. Data와 같은 partition에 hash를 둘 수도 있으며 이 경우 hash는 `<num_data_blocks>` 뒤에 배치합니다.
`hash_start_block`은 `hash_dev` 시작에서 hash tree root block까지의 offset을 `<hash_block_size>` block 단위로 나타냅니다. `algorithm`은 device에서 사용하는 cryptographic hash algorithm 이름으로 `sha1` 같은 값을 사용합니다.
`digest`는 root hash block과 salt의 cryptographic hash를 hexadecimal로 encoding한 값입니다. 이 지점 이후에는 다른 authenticity가 없으므로 이 hash를 신뢰할 수 있어야 합니다. `salt`는 salt value의 hexadecimal encoding입니다.
`#opt_params`는 optional parameter 수입니다. Optional parameter가 없으면 section 전체를 생략하거나 0을 지정할 수 있습니다. 그렇지 않으면 뒤에 오는 argument 수를 지정합니다. 예를 들어 다음은 optional argument 하나입니다.
Example of optional parameters section:
1 ignore_corruptionData geometry, hash tree 위치와 신뢰 root를 table에 고정합니다.
Corruption과 I/O error policy
78-103`ignore_corruption`은 손상된 block을 log하지만 read operation이 정상적으로 계속되게 합니다.
`restart_on_corruption`은 손상 block을 발견하면 system을 restart합니다. `ignore_corruption`과 호환되지 않으며 restart loop를 막을 userspace 지원이 필요합니다.
`panic_on_corruption`은 손상 block을 발견하면 device를 panic시킵니다. `ignore_corruption`, `restart_on_corruption`과 호환되지 않습니다.
`restart_on_error`는 I/O error를 감지하면 system을 restart하며 `restart_on_corruption`과 함께 사용할 수 있습니다.
`panic_on_error`는 I/O error를 감지하면 device를 panic시킵니다. `restart_on_error`와 호환되지 않지만 `panic_on_corruption`과 함께 사용할 수 있습니다.
`ignore_zero_blocks`는 zero를 포함할 것으로 예상되는 block을 검증하지 않고 항상 zero를 반환합니다. Partition에 unused block이 있으며 그 block이 실제 zero임을 보장할 수 없을 때 유용할 수 있습니다.
Corruption과 I/O error에 대한 continue, restart, panic 동작을 선택합니다.
FEC와 최초 read 검증
104-140`use_fec_from_device <fec_dev>`는 hash verification이 실패했을 때 forward error correction(FEC)으로 corruption을 복구하며 지정 device의 encoding data를 사용합니다. Data/hash block과 같은 device를 사용할 수 있지만 이 경우 `fec_start`는 data와 hash area 밖이어야 합니다.
Encoding data가 추가 metadata까지 cover한다면 hash block 뒤의 hash device에서 그 metadata에 접근할 수 있어야 합니다. Data device와 hash device의 block size는 같아야 합니다. Verity `<dev>`가 encrypted되어 있다면 `<fec_dev>`도 encrypt해야 합니다.
`fec_roots <num>`은 generator root 수이며 encoding data의 parity byte 수와 같습니다. 예를 들어 RS(M, N) encoding에서 root 수는 `M-N`입니다.
`fec_blocks <num>`은 FEC device의 encoding data block 수이며 FEC block size는 `<data_block_size>`입니다. `fec_start <offset>`은 FEC device 시작에서 encoding data 시작까지의 offset을 `<data_block_size>` block 단위로 나타냅니다.
`check_at_most_once`는 data device에서 data block을 읽을 때마다가 아니라 최초 read에서만 검증합니다. Memory 또는 CPU가 제한된 system에서 dm-verity overhead를 줄이지만 online tampering은 검출하지 못하고 offline tampering만 검출하므로 security level이 낮아집니다.
Hash block은 hash device에서 읽을 때마다 계속 검증합니다. Hash block verification은 data block보다 performance-critical하지 않고, 해당 hash block이 cover하는 모든 data block을 검증한 뒤에는 그 hash block 자체도 더는 검증되지 않기 때문입니다.
Integrity 실패 뒤 복구 data를 읽을 위치와 Reed-Solomon parity를 지정합니다.
복구된 data도 원래 cryptographic integrity tree로 다시 확인해야 합니다.
Root signature와 bottom-half 검증
141-163`root_hash_sig_key_desc <key_description>`은 kernel이 root hash의 PKCS#7 signature를 얻기 위해 lookup할 `USER_KEY` description입니다. Device-mapper block device 생성 중 이 signature로 root hash를 검증합니다.
Root hash 검증은 kernel에 `DM_VERITY_VERIFY_ROOTHASH_SIG`가 설정되어 있어야 합니다. 기본적으로 signature는 builtin trusted keyring으로 검사하며 `DM_VERITY_VERIFY_ROOTHASH_SIG_SECONDARY_KEYRING`이 설정되면 secondary trusted keyring을 사용합니다.
Secondary trusted keyring은 기본적으로 builtin trusted keyring을 포함합니다. 이미 secondary trusted keyring에 있는 certificate가 서명했다면 runtime에 새 certificate도 추가할 수 있습니다.
`try_verify_in_tasklet`은 verity hash가 cache에 있고 I/O size가 제한을 넘지 않을 때 workqueue 대신 bottom half에서 data block을 검증하여 I/O latency를 줄일 수 있습니다.
Size limit은 `/sys/module/dm_verity/parameters/use_bh_bytes`에서 구성합니다. 네 parameter는 순서대로 `IOPRIO_CLASS_NONE`, `IOPRIO_CLASS_RT`, `IOPRIO_CLASS_BE`, `IOPRIO_CLASS_IDLE`의 limit입니다. 예시는 다음과 같습니다.
For example:
<none>,<rt>,<be>,<idle>
4096,4096,4096,4096Trusted keyring으로 root를 인증하고 작은 cached I/O는 bottom half에서 검증할 수 있습니다.
Verified boot에서의 동작
164-187dm-verity는 verified boot path의 일부로 설정하도록 설계되었습니다. tboot 또는 trustedgrub을 사용하는 boot부터 known-good USB drive나 CD에서 boot하는 방식까지 포함할 수 있습니다.
dm-verity device를 구성할 때 caller는 cryptographic signature 등의 방법으로 이미 인증된 것으로 기대합니다. Device를 만든 뒤 disk access 중 모든 hash를 on-demand로 검증합니다. Tree의 root node인 root hash까지 검증할 수 없으면 I/O가 실패합니다. 이 방식은 device의 data와 hash data에 대한 tampering을 모두 탐지해야 합니다.
Cryptographic hash는 block별 device integrity를 증명하는 데 사용됩니다. Page cache로 처음 읽을 때 가벼운 hash 계산만 수행할 수 있습니다. Block hash는 가장 가까운 block size 경계에 맞춰 linear하게 저장합니다.
FEC가 활성화되면 corruption에서 복구한 모든 data는 대응 data의 cryptographic hash로 검증됩니다. 그래서 error correction과 integrity checking을 결합하는 것이 필수입니다.
Boot-time authenticity에서 runtime block integrity까지 신뢰가 이어집니다.
Hash tree 구조
188-215Tree의 각 node는 cryptographic hash입니다. Leaf node이면 disk의 data block 하나에 대한 hash를 계산하고 intermediary node이면 여러 child node에 대한 hash를 계산합니다.
Tree의 각 entry는 block 하나에 들어가는 인접 node collection입니다. Node 수는 block size와 선택한 cryptographic digest algorithm size로 결정됩니다. Hash는 entry 안에서 linear order로 배치합니다. Alignment되지 않은 trailing space는 사용하지 않지만 parent node를 계산할 때는 포함합니다.
원문의 예시는 `alg = sha256`, `num_blocks = 32768`, `block_size = 4096`입니다. 4096-byte block에 SHA-256 digest 128개가 들어가므로 root 아래 entry와 leaf entry가 각각 최대 128개 child를 cover합니다.
원문의 ASCII 그림을 level과 cover range로 다시 구성했습니다.
Root에서 한 branch를 따라가면 entry index가 data block range를 좁힙니다.
On-disk hash block layout
216-236Verity kernel code는 on-disk verity metadata header를 읽지 않습니다. Header 바로 뒤의 hash block만 읽습니다. Verity header의 integrity는 userspace tool이 검증해야 합니다.
대안으로 header를 생략하고, command line 자체가 검증되는 rooted chain of trust에서 dmsetup parameter를 kernel command line으로 전달할 수 있습니다.
Header 바로 뒤에서 sector number를 다음 hash block boundary까지 padding한 위치에 hash block이 놓입니다. Hash block은 root에서 시작해 depth별로 저장하고 각 depth 안에서는 index가 증가하는 순서로 정렬합니다.
Kernel parameter와 on-disk metadata format 전체 specification은 cryptsetup project wiki `https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity`에서 확인할 수 있습니다.
Kernel은 userspace가 인증한 header 다음의 depth-ordered hash block을 사용합니다.
Status code
237-241지금까지 수행한 모든 check가 valid이면 `V`(Valid)를 반환합니다. Check 하나라도 실패하면 `C`(Corruption)를 반환합니다.
누적 integrity check 결과를 한 글자로 보고합니다.
dmsetup과 veritysetup 예제
242-265`dmsetup`으로 read-only verity device를 설정합니다. Table에는 data·hash device, 4096-byte block geometry, SHA-256 root digest와 salt가 포함됩니다.
Set up a device::
# dmsetup create vroot --readonly --table \
"0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\
"4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
"1234000000000000000000000000000000000000000000000000000000000000"`veritysetup` command line tool은 hash tree를 계산·검증하거나 kernel device를 활성화합니다. `https://gitlab.com/cryptsetup/cryptsetup/`의 cryptsetup upstream repository에서 libcryptsetup extension으로 제공합니다.
Device에 hash tree를 생성합니다.
Create hash on the device::
# veritysetup format /dev/sda1 /dev/sda2
...
Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076계산한 root hash로 device를 활성화합니다.
Activate the device::
# veritysetup create vroot /dev/sda1 /dev/sda2 \
4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076Format 단계에서 만든 root hash를 신뢰 경로로 전달해 runtime device를 활성화합니다.
Construction
verity.rst:1-163Data·hash geometry와 trusted root digest, corruption/error policy, FEC와 root signature option을 정리합니다.