BaseTools/Source/Python/Pkcs7Sign/Readme.md

   1 # Step by step to generate sample self-signed X.509 certificate chain and sign data with PKCS7 structure
   2
   3 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.
   4
   5 ## How to generate a self-signed X.509 certificate chain via OPENSSL
   6 * Set OPENSSL environment.
   7
   8 NOTE: Below steps are required for Windows. Linux may already have the OPENSSL environment correctly.
   9
  10     set OPENSSL_HOME=c:\home\openssl\openssl-[version]
  11     set OPENSSL_CONF=%OPENSSL_HOME%\apps\openssl.cnf
  12
  13 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).
  14
  15 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.
  16
  17     [ CA_default ]
  18         dir = ./demoCA              # Where everything is kept
  19
  20 You may need the following steps for initialization:
  21
  22     rd ./demoCA /S/Q
  23     mkdir ./demoCA
  24     echo.>./demoCA/index.txt
  25     echo 01 > ./demoCA/serial
  26     mkdir ./demoCA/newcerts
  27
  28 OpenSSL will apply the options from the specified sections in openssl.cnf when creating certificates or certificate signing requests. Make sure your configuration in openssl.cnf is correct and rational for certificate constraints.
  29 The following sample sections were used when generating test certificates in this readme.
  30     ...
  31     [ req ]
  32     default_bits        = 2048
  33     default_keyfile     = privkey.pem
  34     distinguished_name  = req_distinguished_name
  35     attributes          = req_attributes
  36     x509_extensions     = v3_ca       # The extensions to add to the self signed cert
  37     ...
  38     [ v3_ca ]
  39     # Extensions for a typical Root CA.
  40     subjectKeyIdentifier=hash
  41     authorityKeyIdentifier=keyid:always,issuer
  42     basicConstraints = critical,CA:true
  43     keyUsage = critical, digitalSignature, cRLSign, keyCertSign
  44     ...
  45     [ v3_intermediate_ca ]
  46     # Extensions for a typical intermediate CA.
  47     subjectKeyIdentifier = hash
  48     authorityKeyIdentifier = keyid:always,issuer
  49     basicConstraints = critical, CA:true
  50     keyUsage = critical, digitalSignature, cRLSign, keyCertSign
  51     ...
  52     [ usr_cert ]
  53     # Extensions for user end certificates.
  54     basicConstraints = CA:FALSE
  55     nsCertType = client, email
  56     subjectKeyIdentifier = hash
  57     authorityKeyIdentifier = keyid,issuer
  58     keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
  59     extendedKeyUsage = clientAuth, emailProtection
  60     ...
  61
  62 * Generate the certificate chain:
  63
  64 NOTE: User MUST set a UNIQUE "Common Name" on the different certificate
  65
  66 1) Generate the Root Pair:
  67
  68 Generate a root key:
  69
  70     openssl genrsa -aes256 -out TestRoot.key 2048
  71
  72 Generate a self-signed root certificate:
  73
  74     openssl req -extensions v3_ca -new -x509 -days 3650 -key TestRoot.key -out TestRoot.crt
  75     openssl x509 -in TestRoot.crt -out TestRoot.cer -outform DER
  76     openssl x509 -inform DER -in TestRoot.cer -outform PEM -out TestRoot.pub.pem
  77
  78 2) Generate the Intermediate Pair:
  79
  80 Generate the intermediate key:
  81
  82     openssl genrsa -aes256 -out TestSub.key 2048
  83
  84 Generate the intermediate certificate:
  85
  86     openssl req -new -days 3650 -key TestSub.key -out TestSub.csr
  87     openssl ca -extensions v3_intermediate_ca -in TestSub.csr -days 3650 -out TestSub.crt -cert TestRoot.crt -keyfile TestRoot.key
  88     openssl x509 -in TestSub.crt -out TestSub.cer -outform DER
  89     openssl x509 -inform DER -in TestSub.cer -outform PEM -out TestSub.pub.pem
  90
  91 3) Generate User Key Pair for Data Signing:
  92
  93 Generate User key:
  94
  95     openssl genrsa -aes256 -out TestCert.key 2048
  96
  97 Generate User certificate:
  98
  99     openssl req -new -days 3650 -key TestCert.key -out TestCert.csr
 100     openssl ca -extensions usr_cert -in TestCert.csr -days 3650 -out TestCert.crt -cert TestSub.crt -keyfile TestSub.key
 101     openssl x509 -in TestCert.crt -out TestCert.cer -outform DER
 102     openssl x509 -inform DER -in TestCert.cer -outform PEM -out TestCert.pub.pem
 103
 104 Convert Key and Certificate for signing. Password is removed with -nodes flag for convenience in this sample.
 105
 106     openssl pkcs12 -export -out TestCert.pfx -inkey TestCert.key -in TestCert.crt
 107     openssl pkcs12 -in TestCert.pfx -nodes -out TestCert.pem
 108
 109 * Verify Data Signing & Verification with new X.509 Certificate Chain
 110
 111 1) Sign a Binary File to generate a detached PKCS7 signature:
 112
 113     openssl smime -sign -binary -signer TestCert.pem -outform DER -md sha256 -certfile TestSub.pub.pem -out test.bin.p7 -in test.bin
 114
 115 2) Verify PKCS7 Signature of a Binary File:
 116
 117     openssl smime -verify -inform DER -in test.bin.p7 -content test.bin -CAfile TestRoot.pub.pem -out test.org.bin
 118