1 files changed, 86 insertions, 0 deletions
diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst
index 1621ff30ca..b2fc665e47 100644
--- a/tools/binman/entries.rst
+++ b/tools/binman/entries.rst
@@ -468,6 +468,92 @@ updating the EC on startup via software sync.
 
 
 
+.. _etype_encrypted:
+
+Entry: encrypted: Externally built encrypted binary blob
+--------------------------------------------------------
+
+This entry provides the functionality to include information about how to
+decrypt an encrypted binary. This information is added to the
+resulting device tree by adding a new cipher node in the entry's parent
+node (i.e. the binary).
+
+The key that must be used to decrypt the binary is either directly embedded
+in the device tree or indirectly by specifying a key source. The key source
+can be used as an id of a key that is stored in an external device.
+
+Using an embedded key
+~~~~~~~~~~~~~~~~~~~~~
+
+This is an example using an embedded key::
+
+    blob-ext {
+        filename = "encrypted-blob.bin";
+    };
+
+    encrypted {
+        algo = "aes256-gcm";
+        iv-filename = "encrypted-blob.bin.iv";
+        key-filename = "encrypted-blob.bin.key";
+    };
+
+This entry generates the following device tree structure form the example
+above::
+
+    data = [...]
+    cipher {
+        algo = "aes256-gcm";
+        key = <0x...>;
+        iv = <0x...>;
+    };
+
+The data property is generated by the blob-ext etype, the cipher node and
+its content is generated by this etype.
+
+Using an external key
+~~~~~~~~~~~~~~~~~~~~~
+
+Instead of embedding the key itself into the device tree, it is also
+possible to address an externally stored key by specifying a 'key-source'
+instead of the 'key'::
+
+    blob-ext {
+        filename = "encrypted-blob.bin";
+    };
+
+    encrypted {
+        algo = "aes256-gcm";
+        iv-filename = "encrypted-blob.bin.iv";
+        key-source = "external-key-id";
+    };
+
+This entry generates the following device tree structure form the example
+above::
+
+    data = [...]
+    cipher {
+        algo = "aes256-gcm";
+        key-source = "external-key-id";
+        iv = <0x...>;
+    };
+
+Properties
+~~~~~~~~~~
+
+Properties / Entry arguments:
+    - algo: The encryption algorithm. Currently no algorithm is supported
+            out-of-the-box. Certain algorithms will be added in future
+            patches.
+    - iv-filename: The name of the file containing the initialization
+                   vector (in short iv). See
+                   https://en.wikipedia.org/wiki/Initialization_vector
+    - key-filename: The name of the file containing the key. Either
+                    key-filename or key-source must be provided.
+    - key-source: The key that should be used. Either key-filename or
+                  key-source must be provided.
+
+
+
 .. _etype_fdtmap:
 
 Entry: fdtmap: An entry which contains an FDT map