deploy: af8f8fe

ch10-00-swap-overview.html

@@ -234,6 +234,24 @@ <h2><a class="header" href="#encryption-method" id="encryption-method">Encryptio
 <h2><a class="header" href="#swap-implementation" id="swap-implementation">Swap Implementation</a></h2>
 <p>Swap is a kernel feature that is enabled with the flag <code>swap</code>.</p>
 <p>Swap is intended to be implemented using an off-chip SPI RAM device. While it is most performant if it is a memory mapped RAM, it does not need to be; the <code>swapper</code> shall be coded with a HAL that can also handle SPI devices that are accessible only through a register interface.</p>
+<h3><a class="header" href="#image-creation" id="image-creation">Image Creation</a></h3>
+<p><code>swap</code> configured builds cannot assume that all the static code can fit inside the secure FLASH within a microcontroller.
+Thus, the image creator must take regions marked as <code>IniS</code> and locate them in a &quot;detached blob&quot; from the main <code>xous.img</code>.</p>
+<p>The security properties of the two images are thus:</p>
+<ul>
+<li><code>xous.img</code> is assumed to be written into a secure on-chip FLASH region, and is unencrypted by default.</li>
+<li><code>swap.img</code> is assumed to be written to an off-chip SPI FLASH memory, and is untrusted by default.</li>
+</ul>
+<p>A simple bulk signature check on <code>swap.img</code>, like that used on <code>xous.img</code>, is not going to cut it in an adversarial
+environment, because of the TOCTOU inherent in doing a hash-and-check and then bulk-copy over a slow bus like SPI.
+Thus, the following two-phase scheme is introduced for distributing <code>swap.img</code>.</p>
+<ol>
+<li>In phase 1, <code>swap.img</code> is encrypted using an AEAD to a &quot;well-known-key&quot; of <code>0</code>, where each block in FLASH encrypts a page of data, and the AAD/MAC are stored in an appendix to the <code>swap.img</code>. The first page is an unprotected directory that defines the expected offset of all the AAD/MAC relative to the encrypted blocks in the image file. The problem of whether to accept an update is outside the scope of this spec: it's assumed that if an update is delivered, it's updated with some signature tied to a certificate in a transparency log that is confirmed by the user at update time. This does mean there is a potential TOCTOU of the bulk update data versus signing at update time, but we assume that the update is done as an atomic operation by the user in a &quot;safe&quot; environment, and that an adversary cannot force an update of the <code>swap.img</code> that meets the requirements of phase 2 without user consent.</li>
+<li>In phase 2, <code>swap.img</code> is re-encrypted to a locally generated key, which is based on a key stored only in the device and derived with the help of a user-supplied password. This prevents adversaries from forcing an update to <code>swap.img</code> without a user's explicit consent.</li>
+</ol>
+<p>In order to support this scheme, an additional kernel argument known as <code>Skey</code> is added. The image creator sets this to a 256-bit &quot;all zero&quot; key initially for distribution and initial device image creation. Once the device is provisioned with a root key, the provisioning routine shall also update the kernel arguments (which are stored inside the secure FLASH region) with the new key, and re-encrypt the <code>swap</code> detached blob in SPI FLASH to the unique device key before rebooting.</p>
+<p>If followed correctly, a device is distributed &quot;naive&quot; and malleable, but once the keying ceremony is done, it should be hard to intercept and/or modify blocks inside <code>swap.img</code>, since the block-by-block read-in and authentication check provides a strong guarantee of consistency even in the face of an adversary that can freely MITM the SPI bus.</p>
+<p>This is different from the detached-signature with unencrypted body taken for on-chip FLASH, which is a faster, easier method, but only works if the path to FLASH memory is assumed to be trusted.</p>
 <h3><a class="header" href="#boot-setup-loader" id="boot-setup-loader">Boot Setup: Loader</a></h3>
 <p>The loader gets new responsibilities when <code>swap</code> is enabled:</p>
 <ul>

print.html

@@ -3793,6 +3793,24 @@ <h2><a class="header" href="#encryption-method" id="encryption-method">Encryptio
 <h2><a class="header" href="#swap-implementation" id="swap-implementation">Swap Implementation</a></h2>
 <p>Swap is a kernel feature that is enabled with the flag <code>swap</code>.</p>
 <p>Swap is intended to be implemented using an off-chip SPI RAM device. While it is most performant if it is a memory mapped RAM, it does not need to be; the <code>swapper</code> shall be coded with a HAL that can also handle SPI devices that are accessible only through a register interface.</p>
+<h3><a class="header" href="#image-creation" id="image-creation">Image Creation</a></h3>
+<p><code>swap</code> configured builds cannot assume that all the static code can fit inside the secure FLASH within a microcontroller.
+Thus, the image creator must take regions marked as <code>IniS</code> and locate them in a &quot;detached blob&quot; from the main <code>xous.img</code>.</p>
+<p>The security properties of the two images are thus:</p>
+<ul>
+<li><code>xous.img</code> is assumed to be written into a secure on-chip FLASH region, and is unencrypted by default.</li>
+<li><code>swap.img</code> is assumed to be written to an off-chip SPI FLASH memory, and is untrusted by default.</li>
+</ul>
+<p>A simple bulk signature check on <code>swap.img</code>, like that used on <code>xous.img</code>, is not going to cut it in an adversarial
+environment, because of the TOCTOU inherent in doing a hash-and-check and then bulk-copy over a slow bus like SPI.
+Thus, the following two-phase scheme is introduced for distributing <code>swap.img</code>.</p>
+<ol>
+<li>In phase 1, <code>swap.img</code> is encrypted using an AEAD to a &quot;well-known-key&quot; of <code>0</code>, where each block in FLASH encrypts a page of data, and the AAD/MAC are stored in an appendix to the <code>swap.img</code>. The first page is an unprotected directory that defines the expected offset of all the AAD/MAC relative to the encrypted blocks in the image file. The problem of whether to accept an update is outside the scope of this spec: it's assumed that if an update is delivered, it's updated with some signature tied to a certificate in a transparency log that is confirmed by the user at update time. This does mean there is a potential TOCTOU of the bulk update data versus signing at update time, but we assume that the update is done as an atomic operation by the user in a &quot;safe&quot; environment, and that an adversary cannot force an update of the <code>swap.img</code> that meets the requirements of phase 2 without user consent.</li>
+<li>In phase 2, <code>swap.img</code> is re-encrypted to a locally generated key, which is based on a key stored only in the device and derived with the help of a user-supplied password. This prevents adversaries from forcing an update to <code>swap.img</code> without a user's explicit consent.</li>
+</ol>
+<p>In order to support this scheme, an additional kernel argument known as <code>Skey</code> is added. The image creator sets this to a 256-bit &quot;all zero&quot; key initially for distribution and initial device image creation. Once the device is provisioned with a root key, the provisioning routine shall also update the kernel arguments (which are stored inside the secure FLASH region) with the new key, and re-encrypt the <code>swap</code> detached blob in SPI FLASH to the unique device key before rebooting.</p>
+<p>If followed correctly, a device is distributed &quot;naive&quot; and malleable, but once the keying ceremony is done, it should be hard to intercept and/or modify blocks inside <code>swap.img</code>, since the block-by-block read-in and authentication check provides a strong guarantee of consistency even in the face of an adversary that can freely MITM the SPI bus.</p>
+<p>This is different from the detached-signature with unencrypted body taken for on-chip FLASH, which is a faster, easier method, but only works if the path to FLASH memory is assumed to be trusted.</p>
 <h3><a class="header" href="#boot-setup-loader" id="boot-setup-loader">Boot Setup: Loader</a></h3>
 <p>The loader gets new responsibilities when <code>swap</code> is enabled:</p>
 <ul>