add examples README

Signed-off-by: Tiago Oliveira <tfaoliveira@gmail.com>

Author: tfaoliveira

examples/README.md

@@ -0,0 +1,65 @@
+## Running the examples
+
+The directories `mlkem1024_amd64_avx2` and `mlkem768_amd64_avx2` contain example code
+(`example.c`) and a Makefile for using the formally verified and optimized Jasmin
+implementations of MLKEM.
+
+To run the example for `mlkem1024_amd64_avx2` (the same applies to `mlkem768_amd64_avx2`),
+run `make` in the corresponding directory. Then execute the example program with:
+```sh
+./example
+```
+
+The expected output is shown below.
+
+If you wish to use the available assembly code from the `src/` directory, please read
+the file `example.c` carefully.
+
+Below is the expected output from running `./example` for `mlkem1024_amd64_avx2`.
+Note that each run uses new randomness; therefore, new key pairs (and corresponding
+shared secrets) are generated on every execution.
+
+
+```
+// {"mlkem1024" : { architecture : "amd64", implementation : "avx2"} }
+uint8_t secret_key[3168] = {
+  0x99, 0x48, 0x4b, 0x00, 0xd5, 0x29, 0x06, 0x67, 0x21, 0x63, 0xa3, 0x76, 0x6d, 0x89, 0x2a, 0x56, 
+  // ...
+};
+uint8_t public_key[1568] = {
+  0xd4, 0x58, 0x1a, 0x8c, 0xd0, 0x55, 0x9f, 0xd1, 0x34, 0x58, 0x83, 0x6d, 0x74, 0x72, 0x2c, 0x9c, 
+  // ...
+};
+uint8_t ciphertext[1568] = {
+  0x47, 0x9a, 0xd3, 0x39, 0x96, 0xef, 0xc9, 0xc9, 0x6c, 0x0d, 0x79, 0x06, 0x04, 0xe1, 0x81, 0xee, 
+  // ...
+};
+uint8_t shared_secret[32] = {
+  0xc6, 0x71, 0x8f, 0x92, 0x19, 0xe7, 0x20, 0xd6, 0xf9, 0xa2, 0xfb, 0x9f, 0xba, 0x33, 0xc1, 0x7f, 
+  // ...
+};
+uint8_t derand_keypair_random_coins[64] = {
+  0x5a, 0x01, 0x7d, 0xbc, 0xec, 0x12, 0x23, 0x08, 0x99, 0x85, 0x70, 0x86, 0x09, 0x2b, 0xda, 0xd4, 
+  // ...
+};
+uint8_t derand_secret_key[3168] = {
+  0x60, 0x90, 0x5c, 0x16, 0x78, 0xb3, 0xc1, 0xe8, 0x0e, 0xb1, 0xeb, 0x38, 0x23, 0x26, 0x1b, 0x61, 
+  // ...
+};
+uint8_t derand_public_key[1568] = {
+  0xe8, 0x56, 0x0c, 0xac, 0x6a, 0x0b, 0xee, 0xd0, 0x11, 0x61, 0x5a, 0x63, 0xb9, 0xa5, 0x7a, 0x50, 
+  // ...
+};
+uint8_t derand_enc_random_coins[32] = {
+  0x82, 0xaa, 0xca, 0x96, 0x13, 0x62, 0x22, 0x0a, 0x4b, 0x00, 0xe1, 0x50, 0xcc, 0x6a, 0xc5, 0xf2, 
+  // ...
+};
+uint8_t derand_ciphertext[1568] = {
+  0x48, 0x38, 0x2b, 0x73, 0x32, 0xd3, 0x16, 0x2d, 0x49, 0x81, 0xb9, 0x8e, 0x5f, 0xec, 0x53, 0x9e, 
+  // ...
+};
+uint8_t derand_shared_secret[32] = {
+  0x44, 0xea, 0x66, 0x7e, 0xdc, 0xe0, 0x01, 0xf6, 0xdb, 0xc4, 0x5e, 0x97, 0x5e, 0x1c, 0x4d, 0xb8, 
+  // ...
+};
+```