BaseTools/Pkcs7: Add readme.md
authorJiewen Yao <jiewen.yao@intel.com>
Sat, 29 Oct 2016 12:51:56 +0000 (20:51 +0800)
committerJiewen Yao <jiewen.yao@intel.com>
Fri, 4 Nov 2016 14:30:43 +0000 (22:30 +0800)
Add readme.md to describe the X.509 certificate generation.

Cc: Yonghong Zhu <yonghong.zhu@intel.com>
Cc: Liming Gao <liming.gao@intel.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Qin Long <qin.long@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Jiewen Yao <jiewen.yao@intel.com>
Reviewed-by: Qin Long <qin.long@intel.com>
BaseTools/Source/Python/Pkcs7Sign/Readme.md [new file with mode: 0644]

diff --git a/BaseTools/Source/Python/Pkcs7Sign/Readme.md b/BaseTools/Source/Python/Pkcs7Sign/Readme.md
new file mode 100644 (file)
index 0000000..c904907
--- /dev/null
@@ -0,0 +1,84 @@
+# Step by step to generate sample self-signed X.509 certificate chain and sign data with PKCS7 structure\r
+\r
+This readme demonstrates how to generate 3-layer X.509 certificate chain (RootCA -> IntermediateCA -> SigningCert) with OpenSSL commands, and user MUST set a UNIQUE Subject Name ("Common Name") on these three different certificates.\r
+\r
+## How to generate a self-signed X.509 certificate chain via OPENSSL\r
+* Set OPENSSL environment.\r
+\r
+NOTE: Below steps are required for Windows. Linux may already have the OPENSSL environment correctly.\r
+\r
+    set OPENSSL_HOME=c:\home\openssl\openssl-[version]\r
+    set OPENSSL_CONF=%OPENSSL_HOME%\apps\openssl.cnf\r
+\r
+When a user uses OpenSSL (req or ca command) to generate the certificates, OpenSSL will use the openssl.cnf file as the configuration data (can use “-config path/to/openssl.cnf” to describe the specific config file).\r
+\r
+The user need check the openssl.cnf file, to find your CA path setting, e.g. check if the path exists in [ CA_default ] section.\r
+\r
+    [ CA_default ]\r
+        dir = ./demoCA              # Where everything is kept\r
+\r
+You may need the following steps for initialization:\r
+\r
+    rd ./demoCA /S/Q\r
+    mkdir ./demoCA\r
+    echo "" > ./demoCA/index.txt\r
+    echo 01 > ./demoCA/serial\r
+    mkdir ./demoCA/newcerts\r
+\r
+* Generate the certificate chain:\r
+\r
+NOTE: User MUST set a UNIQUE "Common Name" on the different certificate\r
+\r
+1) Generate the Root Pair:\r
+\r
+Generate a root key:\r
+\r
+    openssl genrsa -aes256 -out TestRoot.key 2048\r
+\r
+Generate a self-signed root certificate:\r
+\r
+    openssl req -new -x509 -days 3650 -key TestRoot.key -out TestRoot.crt\r
+    openssl x509 -in TestRoot.crt -out TestRoot.cer -outform DER\r
+    openssl x509 -inform DER -in TestRoot.cer -outform PEM -out TestRoot.pub.pem\r
+\r
+2) Generate the Intermediate Pair:\r
+\r
+Generate the intermediate key:\r
+\r
+    openssl genrsa -aes256 -out TestSub.key 2048\r
+\r
+Generate the intermediate certificate:\r
+\r
+    openssl req -new -days 3650 -key TestSub.key -out TestSub.csr\r
+    openssl ca -extensions v3_ca -in TestSub.csr -days 3650 -out TestSub.crt -cert TestRoot.crt -keyfile TestRoot.key\r
+    openssl x509 -in TestSub.crt -out TestSub.cer -outform DER\r
+    openssl x509 -inform DER -in TestSub.cer -outform PEM -out TestSub.pub.pem\r
+\r
+3) Generate User Key Pair for Data Signing:\r
+\r
+Generate User key:\r
+\r
+    openssl genrsa -aes256 -out TestCert.key 2048\r
+\r
+Generate User certificate:\r
+\r
+    openssl req -new -days 3650 -key TestCert.key -out TestCert.csr\r
+    openssl ca -in TestCert.csr -days 3650 -out TestCert.crt -cert TestSub.crt -keyfile TestSub.key`\r
+    openssl x509 -in TestCert.crt -out TestCert.cer -outform DER\r
+    openssl x509 -inform DER -in TestCert.cer -outform PEM -out TestCert.pub.pem\r
+\r
+Convert Key and Certificate for signing. Password is removed with -nodes flag for convenience in this sample.\r
+\r
+    openssl pkcs12 -export -out TestCert.pfx -inkey TestCert.key -in TestCert.crt\r
+    openssl pkcs12 -in TestCert.pfx -nodes -out TestCert.pem\r
+\r
+* Verify Data Signing & Verification with new X.509 Certificate Chain\r
+\r
+1) Sign a Binary File to generate a detached PKCS7 signature:\r
+\r
+    openssl smime -sign -binary -signer TestCert.pem -outform DER -md sha256 -certfile TestSub.pub.pem -out test.bin.p7 -in test.bin\r
+\r
+2) Verify PKCS7 Signature of a Binary File:\r
+\r
+    openssl smime -verify -inform DER -in test.bin.p7 -content test.bin -CAfile TestRoot.pub.pem -out test.org.bin\r
+\r