From 14690280131f48d8bf7758e42080434d31a314ff Mon Sep 17 00:00:00 2001 From: Martin Turon Date: Tue, 28 Jun 2022 05:09:21 -0700 Subject: [PATCH] [doc] Add reference section for all chip-cert commands and options. (#20015) * [doc] Add reference section for all chip-cert commands and options. * [chip-cert] Add space between copyright authors in version string. * [spell] Fix spelling of 'written'. --- src/tools/chip-cert/Cmd_PrintCert.cpp | 2 +- src/tools/chip-cert/README.md | 574 ++++++++++++++++++++++++++ src/tools/chip-cert/chip-cert.h | 6 +- 3 files changed, 578 insertions(+), 4 deletions(-) diff --git a/src/tools/chip-cert/Cmd_PrintCert.cpp b/src/tools/chip-cert/Cmd_PrintCert.cpp index 5460e0014a2682..298606136660cd 100644 --- a/src/tools/chip-cert/Cmd_PrintCert.cpp +++ b/src/tools/chip-cert/Cmd_PrintCert.cpp @@ -49,7 +49,7 @@ const char * const gCmdOptionHelp = " -o, --out\n" "\n" " The output printed certificate file name. If not specified\n" - " or if specified - then output is writen to stdout.\n" + " or if specified - then output is written to stdout.\n" "\n" ; diff --git a/src/tools/chip-cert/README.md b/src/tools/chip-cert/README.md index 89931de5a370fa..e9beeb35bd9f5c 100644 --- a/src/tools/chip-cert/README.md +++ b/src/tools/chip-cert/README.md @@ -1,5 +1,28 @@ # CHIP Certificate Tool +## Table of Contents + +- [CHIP Certificate Tool](#chip-certificate-tool) + - [Table of Contents](#table-of-contents) + - [Introduction](#introduction) + - [Directory Structure](#directory-structure) + - [/src/tools/chip-cert](#srctoolschip-cert) + - [Usage Examples](#usage-examples) + - [Operational Certificates Usage Examples](#operational-certificates-usage-examples) + - [Attestation Certificates Usage Examples](#attestation-certificates-usage-examples) + - [Command Reference](#command-reference) + - [help](#help) + - [gen-cert](#gen-cert) + - [convert-cert](#convert-cert) + - [convert-key](#convert-key) + - [resign-cert](#resign-cert) + - [validate-cert](#validate-cert) + - [print-cert](#print-cert) + - [gen-att-cert](#gen-att-cert) + - [validate-att-cert](#validate-att-cert) + - [gen-cd](#gen-cd) + - [version](#version) + ## Introduction CHIP Certificate Tool (chip-cert) provides command line interface (CLI) utility @@ -117,3 +140,554 @@ attestation certificate chain that was just created: ``` openssl verify -CAfile Chip-PAA-Cert.pem -untrusted Chip-PAI-Cert.pem Chip-DAC-Cert.pem ``` + +## Command Reference + +This section provides details on the various command line parameters that can be +passed to the `chip-cert` tool. + +### help + +``` +$ ./out/debug/standalone/chip-cert help +Usage: chip [ ] + +Commands: + + gen-cert -- Generate a CHIP certificate. + + convert-cert -- Convert a certificate between CHIP and X509 form. + + convert-key -- Convert a private key between CHIP and PEM/DER form. + + resign-cert -- Resign a CHIP certificate using a new CA key. + + validate-cert -- Validate a CHIP certificate chain. + + print-cert -- Print a CHIP certificate. + + gen-att-cert -- Generate a CHIP attestation certificate. + + validate-att-cert -- Validate a CHIP attestation certificate chain. + + gen-cd -- Generate a CHIP certification declaration signed message. + + version -- Print the program version and exit. +``` + +### gen-cert + +``` +$ ./out/debug/standalone/chip-cert gen-cert -h +Usage: chip-cert gen-cert [ ] + +Generate a CHIP certificate + +COMMAND OPTIONS + + -t, --type + + Certificate type to be generated. Valid certificate type values are: + r - root certificate + c - CA certificate + n - node certificate + f - firmware signing certificate + + -i, --subject-chip-id + + Subject DN CHIP Id attribute in hexadecimal format with upto 8 octets with or without '0x' prefix. + - for Root certificate it is ChipRootId + - for intermediate CA certificate it is ChipICAId + - for Node certificate it is ChipNodeId. The value should be in a range [1, 0xFFFFFFEFFFFFFFFF] + - for Firmware Signing certificate it is ChipFirmwareSigningId + + -f, --subject-fab-id + + Subject DN Fabric Id attribute in hexadecimal format with upto 8 octets with or without '0x' prefix. + The value should be different from 0. + + -a, --subject-cat + + Subject DN CHIP CASE Authentication Tag in hexadecimal format with upto 4 octets with or without '0x' prefix. + The version subfield (lower 16 bits) should be different from 0. + + -c, --subject-cn-u + + Subject DN Common Name attribute encoded as UTF8String. + + -p, --path-len-constraint + + Path length constraint to be included in the basic constraint extension. + If not specified, the path length constraint is not included in the extension. + + -x, --future-ext-sub + + NID_subject_alt_name extension to be added to the list of certificate extensions. + + -2, --future-ext-info + + NID_info_access extension to be added to the list of certificate extensions. + + -C, --ca-cert + + File containing CA certificate to be used to sign the new certificate. + + -K, --ca-key + + File containing CA private key to be used to sign the new certificate. + + -k, --key + + File containing the public and private keys for the new certificate. + If not specified, a new key pair will be generated. + + -o, --out + + File to contain the new certificate. + + -O, --out-key + + File to contain the public/private key for the new certificate. + This option must be specified if the --key option is not. + + -F, --out-format + + Specifies format of the output certificate and private key. + If not specified, the default base-64 encoded CHIP format is used. + Supported format parametes are: + x509-pem - X.509 PEM format + x509-der - X.509 DER format + chip - raw CHIP TLV format + chip-b64 - base-64 encoded CHIP TLV format (default) + + -V, --valid-from --
[ :: ] + + The start date for the certificate's validity period. If not specified, + the validity period starts on the current day. + + -l, --lifetime + + The lifetime for the new certificate, in whole days. Use special value + 4294967295 to indicate that certificate doesn't have well defined + expiration date + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### convert-cert + +``` +$ ./out/debug/standalone/chip-cert convert-cert -h +Usage: chip-cert convert-cert [ ] + +Convert a certificate between CHIP and X509 forms. + +ARGUMENTS + + + + The input certificate file name, or - to read from stdin. The + format of the input certificate is auto-detected and can be any + of: X.509 PEM, X.509 DER, CHIP base-64 or CHIP raw TLV. + + + + The output certificate file name, or - to write to stdout. + +COMMAND OPTIONS + + -p, --x509-pem + + Output certificate in X.509 PEM format. + + -x, --x509-der + + Output certificate in X.509 DER format. + + -c, --chip + + Output certificate in raw CHIP TLV format. + + -b --chip-b64 + + Output certificate in CHIP TLV base-64 encoded format. + This is the default. + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### convert-key + +``` +$ ./out/debug/standalone/chip-cert convert-key -h +Usage: chip-cert convert-key [ ] + +Convert a private key between CHIP and PEM/DER forms. +ARGUMENTS + + + + The input private key file name, or - to read from stdin. The + format of the input key is auto-detected and can be any + of: PEM, DER, CHIP base-64 or CHIP raw. + + + + The output private key file name, or - to write to stdout. + +COMMAND OPTIONS + + -p, --x509-pem + + Output the private key in SEC1/RFC-5915 PEM format. + + -x, --x509-der + + Output the private key in SEC1/RFC-5915 DER format. + + -c, --chip + + Output the private key in raw CHIP serialized format. + + -b, --chip-b64 + + Output the private key in base-64 encoded CHIP serialized format. + This is the default. + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### resign-cert + +``` +$ ./out/debug/standalone/chip-cert resign-cert -h +Usage: chip-cert resign-cert [ ] + +Resign a CHIP certificate using a new CA certificate/key. + +COMMAND OPTIONS + + -c, --cert + + File containing the certificate to be re-signed. + + -o, --out + + File to contain the re-signed certificate. + + -C, --ca-cert + + File containing CA certificate to be used to re-sign the certificate. + + -K, --ca-key + + File containing CA private key to be used to re-sign the certificate. + + -s, --self + + Generate a self-signed certificate. + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### validate-cert + +``` +$ ./out/debug/standalone/chip-cert validate-cert -h +Usage: chip-cert validate-cert [ ] + +Validate a chain of CHIP certificates. + +ARGUMENTS + + + + A file containing the certificate to be validated. + +COMMAND OPTIONS + + -c, --cert + + A file containing an untrusted CHIP certificate to be used during + validation. Usually, it is Intermediate CA certificate. + + -t, --trusted-cert + + A file containing a trusted CHIP certificate to be used during + validation. Usually, it is trust anchor root certificate. + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### print-cert + +``` +$ ./out/debug/standalone/chip-cert print-cert -h +Usage: chip-cert print-cert [] + +Print a CHIP certificate. + +ARGUMENTS + + + + A file containing a CHIP certificate. + +COMMAND OPTIONS + + -o, --out + + The output printed certificate file name. If not specified + or if specified - then output is written to stdout. + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### gen-att-cert + +``` +$ ./out/debug/standalone/chip-cert gen-att-cert -h +Usage: chip-cert gen-att-cert [ ] + +Generate a CHIP certificate + +COMMAND OPTIONS + + -t, --type + + Attestation certificate type to be generated. Valid certificate type values are: + a - product attestation authority certificate + i - product attestation intermediate certificate + d - device attestation certificate + + -c, --subject-cn + + Subject DN Common Name attribute encoded as UTF8String. + + -V, --subject-vid + + Subject DN CHIP VID attribute (in hex). + + -P, --subject-pid + + Subject DN CHIP PID attribute (in hex). + + -a, --vid-pid-as-cn + + Encode Matter VID and PID parameters as Common Name attributes in the Subject DN. + If not specified then by default the VID and PID fields are encoded using + Matter specific OIDs. + + -C, --ca-cert + + File containing CA certificate to be used to sign the new certificate. + + -K, --ca-key + + File containing CA private key to be used to sign the new certificate. + + -k, --key + + File containing the public and private keys for the new certificate (in an X.509 PEM format). + If not specified, a new key pair will be generated. + + -o, --out + + File to contain the new certificate (in an X.509 PEM format). + + -O, --out-key + + File to contain the public/private key for the new certificate (in an X.509 PEM format). + This option must be specified if the --key option is not. + + -f, --valid-from --
[ :: ] + + The start date for the certificate's validity period. If not specified, + the validity period starts on the current day. + + -l, --lifetime + + The lifetime for the new certificate, in whole days. Use special value + 4294967295 to indicate that certificate doesn't have well defined + expiration date + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### validate-att-cert + +``` +$ ./out/debug/standalone/chip-cert validate-att-cert -h +Usage: chip-cert validate-att-cert [ ] + +Validate a chain of CHIP attestation certificates + +COMMAND OPTIONS + + -d, --dac + + A file containing Device Attestation Certificate (DAC) to be + validated. The DAC is provided in the DER encoded format. + + -i, --pai + + A file containing Product Attestation Intermediate (PAI) Certificate. + The PAI is provided in the DER encoded format. + + -a, --paa + + A file containing trusted Product Attestation Authority (PAA) Certificate. + The PAA is provided in the DER encoded format. + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### gen-cd + +``` +$ ./out/debug/standalone/chip-cert gen-cd -h +Usage: chip-cert gen-cd [ ] + +Generate CD CMS Signed Message + +COMMAND OPTIONS + + -K, --key + + File containing private key to be used to sign the Certification Declaration. + + -C, --cert + + File containing certificate associated with the private key that is used + to sign the Certification Declaration. The Subject Key Identifier in the + certificate will be included in the signed Certification Declaration message. + + -O, --out + + File to contain the signed Certification Declaration message. + + -f, --format-version + + Format Version. + + -V, --vendor-id + + Vendor Id (VID) in hex. + + -p, --product-id + + Product Id (PID) in hex. Maximum 100 PID values can be specified. + Each PID value should have it's own -p or --product-id option selector. + + -d, --device-type-id + + Device Type Id in hex. + + -c, --certificate-id + + Certificate Id encoded as UTF8 string. + + -l, --security-level + + Security Level in hex. + + -i, --security-info + + Security Information in hex. + + -n, --version-number + + Version Number in hex. + + -t, --certification-type + + Certification Type. Valid values are: + 0 - Development and Test (default) + 1 - Provisional + 2 - Official + + -o, --dac-origin-vendor-id + + DAC Origin Vendor Id in hex. + + -r, --dac-origin-product-id + + DAC Origin Product Id in hex. + + -a, --authorized-paa-cert + + File containing PAA certificate authorized to sign PAI which signs the DAC + for a product carrying this CD. This field is optional and if present, only specified + PAAs will be authorized to sign device's PAI for the lifetime of the generated CD. + Maximum 10 authorized PAA certificates can be specified. + Each PAA should have its own -a (--authorized-paa-cert) option selector. + The certificate can be in DER or PEM Form. + Note that only the Subject Key Identifier (SKID) value will be extracted + from the PAA certificate and put into CD Structure. + +HELP OPTIONS + + -h, --help + Print this output and then exit. + + -v, --version + Print the version and then exit. +``` + +### version + +Displays the version of the tool and copyright information. + +``` +$ ./out/debug/standalone/chip-cert version +chip 0.0.0 +Copyright (c) 2021-2022 Project CHIP Authors +``` diff --git a/src/tools/chip-cert/chip-cert.h b/src/tools/chip-cert/chip-cert.h index 681e9ad01d664c..e9889cc0210f2c 100644 --- a/src/tools/chip-cert/chip-cert.h +++ b/src/tools/chip-cert/chip-cert.h @@ -76,9 +76,9 @@ using chip::ASN1::OID; #endif #define COPYRIGHT_STRING \ - "Copyright (c) 2021-2022 Project CHIP Authors" \ - "Copyright (c) 2019 Google LLC." \ - "Copyright (c) 2013-2017 Nest Labs, Inc." \ + "Copyright (c) 2021-2022 Project CHIP Authors. " \ + "Copyright (c) 2019 Google LLC. " \ + "Copyright (c) 2013-2017 Nest Labs, Inc. " \ "All rights reserved.\n" enum