BaseTools:replace the chinese quotation mark with unicode "

[mirror_edk2.git] / BaseTools / Source / Python / Pkcs7Sign / Readme.md

# 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
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.\r
The following sample sections were used when generating test certificates in this readme.\r
    ...\r
    [ req ]\r
    default_bits        = 2048\r
    default_keyfile     = privkey.pem\r
    distinguished_name  = req_distinguished_name\r
    attributes          = req_attributes\r
    x509_extensions     = v3_ca       # The extensions to add to the self signed cert\r
    ...\r
    [ v3_ca ]\r
    # Extensions for a typical Root CA.\r
    subjectKeyIdentifier=hash\r
    authorityKeyIdentifier=keyid:always,issuer\r
    basicConstraints = critical,CA:true\r
    keyUsage = critical, digitalSignature, cRLSign, keyCertSign\r
    ...\r
    [ v3_intermediate_ca ]\r
    # Extensions for a typical intermediate CA.\r
    subjectKeyIdentifier = hash\r
    authorityKeyIdentifier = keyid:always,issuer\r
    basicConstraints = critical, CA:true\r
    keyUsage = critical, digitalSignature, cRLSign, keyCertSign\r
    ...\r
    [ usr_cert ]\r
    # Extensions for user end certificates.\r
    basicConstraints = CA:FALSE\r
    nsCertType = client, email\r
    subjectKeyIdentifier = hash\r
    authorityKeyIdentifier = keyid,issuer\r
    keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment\r
    extendedKeyUsage = clientAuth, emailProtection\r
    ...\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 -extensions v3_ca -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_intermediate_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 -extensions usr_cert -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
## Generate DSC PCD include files for Certificate\r
\r
The `BinToPcd` utility can be used to convert the binary Certificate file to a\r
text file can be included from a DSC file to set a PCD to the contents of the\r
Certificate file.\r
\r
The following 2 PCDs can be set to the PKCS7 Certificate value.  The first one\r
supports a single certificate.  The second one supports multiple certificate\r
values using the XDR format.\r
* `gEfiSecurityPkgTokenSpaceGuid.PcdPkcs7CertBuffer`\r
* `gFmpDevicePkgTokenSpaceGuid.PcdFmpDevicePkcs7CertBufferXdr`\r
\r
Generate DSC PCD include files:\r
```\r
BinToPcd.py -i TestRoot.cer -p gEfiSecurityPkgTokenSpaceGuid.PcdPkcs7CertBuffer -o TestRoot.cer.gEfiSecurityPkgTokenSpaceGuid.PcdPkcs7CertBuffer.inc\r
BinToPcd.py -i TestRoot.cer -p gFmpDevicePkgTokenSpaceGuid.PcdFmpDevicePkcs7CertBufferXdr -x -o TestRoot.cer.gFmpDevicePkgTokenSpaceGuid.PcdFmpDevicePkcs7CertBufferXdr.inc\r
```\r
\r
These files can be used in `!include` statements in DSC file PCD sections.  For example:\r
\r
* Platform scoped fixed at build PCD section\r
```\r
[PcdsFixedAtBuild]\r
  !include BaseTools/Source/Python/Pkcs7Sign/TestRoot.cer.gEfiSecurityPkgTokenSpaceGuid.PcdPkcs7CertBuffer.inc\r
```\r
\r
* Platform scoped patchable in module PCD section\r
```\r
[PcdsPatchableInModule]\r
  !include BaseTools/Source/Python/Pkcs7Sign/TestRoot.cer.gFmpDevicePkgTokenSpaceGuid.PcdFmpDevicePkcs7CertBufferXdr.inc\r
```\r
\r
* Module scoped fixed at build PCD section\r
```\r
[Components]\r
  FmpDevicePkg/FmpDxe/FmpDxe.inf {\r
    <PcdsFixedAtBuild>\r
      !include BaseTools/Source/Python/Pkcs7Sign/TestRoot.cer.gFmpDevicePkgTokenSpaceGuid.PcdFmpDevicePkcs7CertBufferXdr.inc\r
  }\r
```\r