From d5bef93e3b36a8acdab0c49e7e2c41b34453a7b9 Mon Sep 17 00:00:00 2001
From: Chris Conlon <chris@wolfssl.com>
Date: Tue, 23 Oct 2018 10:47:56 -0600
Subject: [PATCH] update PKCS#7/CMS README, add debugging notes

---
 .gitignore      | 16 ++++++++++++++++
 pkcs7/README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/.gitignore b/.gitignore
index a3105355..1468aeb1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -108,6 +108,22 @@ ecc/ecc-sign
 ecc/ecc-stack
 ecc/ecc-verify
 pkcs7/pkcs7-verify
+pkcs7/authEnvelopedData-kari
+pkcs7/authEnvelopedData-ktri
+pkcs7/authEnvelopedData-ori
+pkcs7/authEnvelopedData-pwri
+pkcs7/encryptedData
+pkcs7/*.der
+pkcs7/envelopedData-kari
+pkcs7/envelopedData-ktri
+pkcs7/envelopedData-pwri
+pkcs7/envelopedData-ori
+pkcs7/signedData
+pkcs7/signedData-FirmwarePkgData
+pkcs7/signedData-EncryptedFirmwarePkgData
+pkcs7/signedData-CompressedFirmwarePkgData
+pkcs7/signedData-EncryptedCompressedFirmwarePkgData
+
 *.dSYM
 certmanager/certloadverifybuffer
 certmanager/certverify
diff --git a/pkcs7/README.md b/pkcs7/README.md
index 0fe7833a..8dc38f84 100644
--- a/pkcs7/README.md
+++ b/pkcs7/README.md
@@ -45,6 +45,57 @@ make
 sudo make install
 ```
 
+Most of the examples listed below output a DER-encoded version of the
+PKCS#7/CMS bundle that was generated. These DER-encoded files can be used to
+do further analysis, or debugging with external tools.  Two helpful tools
+for doing this include the `openssl cms` application and the `dumpasn1` app.
+
+Debugging with `dumpasn1` ([dumpasn1 source file](https://www.cs.auckland.ac.nz/~pgut001/dumpasn1.c))
+
+```
+$ dumpasn1 encryptedData.der
+ 0  80: SEQUENCE {
+ 2   9:   OBJECT IDENTIFIER encryptedData (1 2 840 113549 1 7 6)
+13  67:   [0] {
+15  65:     SEQUENCE {
+17   1:       INTEGER 0
+20  60:       SEQUENCE {
+22   9:         OBJECT IDENTIFIER data (1 2 840 113549 1 7 1)
+33  29:         SEQUENCE {
+35   9:           OBJECT IDENTIFIER aes256-CBC (2 16 840 1 101 3 4 1 42)
+46  16:           OCTET STRING 08 83 47 90 5D 9F D6 AA DC 25 CE B2 87 9A 10 CF
+      :           }
+64  16:         [0] 3C 22 EA 61 64 FB 21 30 77 8A CE B0 5A A7 35 DE
+      :         }
+      :       }
+      :     }
+      :   }
+
+0 warnings, 0 errors.
+```
+
+Debugging with `openssl cms`
+
+```
+$ openssl cms -inform der -in envelopedData.der -cmsout -print -noout
+CMS_ContentInfo: 
+  contentType: pkcs7-encryptedData (1.2.840.113549.1.7.6)
+  d.encryptedData: 
+    version: <ABSENT>
+    encryptedContentInfo: 
+      contentType: pkcs7-data (1.2.840.113549.1.7.1)
+      contentEncryptionAlgorithm: 
+        algorithm: aes-256-cbc (2.16.840.1.101.3.4.1.42)
+        parameter: OCTET STRING:
+          0000 - 08 83 47 90 5d 9f d6 aa-dc 25 ce b2 87 9a 10   ..G.]....%.....
+          000f - cf                                             .
+        encryptedContent: 
+          0000 - 3c 22 ea 61 64 fb 21 30-77 8a ce b0 5a a7 35   <".ad.!0w...Z.5
+          000f - de                                             .
+  unprotectedAttrs:
+    <EMPTY>
+```
+
 ## Examples Description and Usage
 
 ### pkcs7-verify