deploy: 0b4e58b

ch10-00-swap-overview.html

@@ -245,13 +245,16 @@ <h3><a class="header" href="#image-creation" id="image-creation">Image Creation<
 <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>
+<p>The AEAD shall be either ChachaPoly or AES-256, depending upon which is more performant (to be updated).</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>
+<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 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 MAC relative to the encrypted blocks in the image file, and contains the 64-bit nonce seed + AAD. 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. NOTE: the key shall <em>not</em> be re-used between <code>swap.img</code> updates; it should be re-generated on every update. This does mean that the signature on the <code>xous.img</code> shall change on every update, but this is assumed to be happening already on an update.</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>
+<p>The nonce for the <code>swap.img</code> AEAD is 96 bits, where the lower 32 bits track the block offset, and the upper 64 bits are the lower 64 bits of the git commit corresponding to the <code>swap.img</code>. This 64-bit git commit is stored as a nonce seed in the unprotected header page along with the offset of the MAC + AAD data. The incorporation of the git commit helps protect against bugs in the implementation of the locally generated key. The locally generated key should not be re-used between updates, but tying the nonce to the git commit should harden against chosen ciphertext attacks in the case that the generated key happens to be re-used.</p>
+<p>The AAD shall include the ASCII characters <code>'swap'</code> in little-endian format (<code>u32</code>: <code>0x7061_7773</code>) plus any AAD specified in the header.</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

@@ -3804,13 +3804,16 @@ <h3><a class="header" href="#image-creation" id="image-creation">Image Creation<
 <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>
+<p>The AEAD shall be either ChachaPoly or AES-256, depending upon which is more performant (to be updated).</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>
+<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 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 MAC relative to the encrypted blocks in the image file, and contains the 64-bit nonce seed + AAD. 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. NOTE: the key shall <em>not</em> be re-used between <code>swap.img</code> updates; it should be re-generated on every update. This does mean that the signature on the <code>xous.img</code> shall change on every update, but this is assumed to be happening already on an update.</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>
+<p>The nonce for the <code>swap.img</code> AEAD is 96 bits, where the lower 32 bits track the block offset, and the upper 64 bits are the lower 64 bits of the git commit corresponding to the <code>swap.img</code>. This 64-bit git commit is stored as a nonce seed in the unprotected header page along with the offset of the MAC + AAD data. The incorporation of the git commit helps protect against bugs in the implementation of the locally generated key. The locally generated key should not be re-used between updates, but tying the nonce to the git commit should harden against chosen ciphertext attacks in the case that the generated key happens to be re-used.</p>
+<p>The AAD shall include the ASCII characters <code>'swap'</code> in little-endian format (<code>u32</code>: <code>0x7061_7773</code>) plus any AAD specified in the header.</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>