From e255452d4591ad500b1392560f3a9b29e09b6960 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joachim=20Stro=CC=88mbergson?= <joachim@secworks.se>
Date: Fri, 6 Jul 2018 14:18:26 +0200
Subject: Updated README with status and information about the implementation.

---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 46 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index c17c542..41430f1 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,59 @@
 keywrap
 =======
 ## Introduction ##
-
 This core implememts AES KEY WRAP as defined in [RFC
 3394](https://tools.ietf.org/html/rfc3394) and the keywrap with padding
 according to [RFC 5694](https://tools.ietf.org/html/rfc5649)
 
-The user/host system writes data to be wrapped/unwrapped to the core as
-well as the wrapping key. The core then handles the wrapping/unwrapping
-operation independently. When operation has completed the result can be
-read back.
+The core supports wrap/unwrap of objects up to 32 kbits in size. The
+core supports 128 and 256 bit keys.
 
 
 ## Status ##
-First attempt at implementation of key wrap completed. Compiles ok, lint
-ok and goes through ISE synthesis ok. Not functionally debugged with
-simulation. Does Not Work.
+First complete version developed. The core does work.
+
+The core has been simulated with two different simulators and
+linted.
+
+The core has been implemented for Xilinx Artix7-t200 using ISE with the
+following results:
+
+Regs:    2906 (1%)
+Slices:  1991 (5%)
+RamB36E: 32 (8%)
+Clock:   100+ MHz
+
+
+## Implementation details
+The core implements the wrap block processing part of the AES Key Wrap
+as specified in chapter 2.1.1 of RFC 3394:
+
+   For j = 0 to 5
+           For i=1 to n
+               B = AES(K, A | R[i])
+               A = MSB(64, B) ^ t where t = (n*j)+i
+               R[i] = LSB(64, B)
+
+The core does not perform the calculation of the magic value, which is
+the initial value of A. The core also does not perform padding om the
+message to an even 8 byte block.
+
+This means that SW needs to generate the 64-bit initial value of A and
+perform padding as meeded.
+
+(Similarly, the core implements the unwrap processng as specifie in
+chapter 2.2.2 of RFC 3394.)
 
-Some ISE results:
 
-Regs:       2857
-Slice LUTs: 3627
-RAMB36:     32
+### API
+Objects to be processed are written in word order (MSB words). The
+caller writes the calculated magic value to the A regsisters in word
+order. The caller also needs to write the number of blocks (excluding
+magic block) into the RLEN register. Finally the caller needs to write
+the wrapping key.
 
-Meets timing for 100 MHz clock.
+Due to address space limitations in the Cryptech cores (with 8-bit
+address space) the object storage is divided into banks (bank
+0..3). Each bank supports 4096 bits. For objects lager than 4096 bits,
+it is the callers responsibilty to switch banks when reading and writing
+to the storage.
-- 
cgit v1.2.3