# 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)
- [Building](#building)
- [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)
- [gen-cd example](#gen-cd-example)
- [print-cd](#print-cd)
- [print-cd example](#print-cd-example)
- [version](#version)
## Introduction
CHIP Certificate Tool (chip-cert) provides command line interface (CLI) utility
used for generating and manipulating CHIP certificates and CHIP private keys
material.
## Directory Structure
### /src/tools/chip-cert
This directory contains various command handler for the 'chip-cert' tool that:
- generate CHIP certificate
- convert CHIP certificate format
- convert CHIP private key format
- validate CHIP certificate chain
- resign CHIP certificate
- print CHIP certificate
- generate CHIP attestation certificates
## Usage Examples
Specify 'help' option for the detailed 'chip-cert' tool usage instructions:
```
./chip-cert help
```
Specify '--help' option for detail instructions on usage of each command:
```
./chip-cert gen-cert --help
```
### Building
The `chip-cert` tool will be built when `gn_build.sh` is run. To build just the
`chip-cert` tool locally:
```
. ./scripts/activate.sh
gn gen out/host
ninja -C out/host chip-cert
./out/host/chip-cert help
```
## Operational Certificates Usage Examples
Example command that can be used to generate CHIP root certificate and private
key:
```
./chip-cert gen-cert --type r --subject-chip-id CACACACA00000001 --valid-from "2020-10-15 14:23:43" --lifetime 7305 --out-key Chip-Root-Key.pem --out Chip-Root-Cert.pem --out-format x509-pem
```
The root certificate/key output of last command can then be used to generate
CHIP Intermediate CA (ICA) certificate and private key:
```
./chip-cert gen-cert --type c --subject-chip-id CACACACA00000002 --valid-from "2020-10-15 14:23:43" --lifetime 7305 --ca-key Chip-Root-Key.pem --ca-cert Chip-Root-Cert.pem --out-key Chip-ICA-Key.pem --out Chip-ICA-Cert.pem --out-format x509-pem
```
The generated ICA certificate/key can then be used to sign multiple CHIP Node
certificates:
```
./chip-cert gen-cert --type n --subject-chip-id DEDEDEDE0000001D --subject-fab-id FAB000000000001D --valid-from "2020-10-15 14:23:43" --lifetime 7305 --ca-key Chip-ICA-Key.pem --ca-cert Chip-ICA-Cert.pem --out-key Chip-Node-Key.chip-b64 --out Chip-Node-Cert.chip-b64 --out-format chip-b64
```
Note that in the last example the generated Node certificate and private key are
stored in base-64 encoded CHIP native format and not in PEM format as in the
previous examples.
The following example generates Node certificate, where the CA cert/key and the
Node key are provided as a command line arguments:
```
./chip-cert gen-cert --type n --subject-chip-id DEDEDEDE0000001E --subject-fab-id FAB000000000001D --valid-from "2020-10-15 14:23:43" --lifetime 7305 --ca-key 30770201010420C31A9FD24F91B28F3553C6DD0BC05DFB264FB19DE4A293457FF61CF08656F795A00A06082A8648CE3D030107A144034200046909160652E60035DEAFF5EE4DCED6E451BB171D39972874193CBDEA79E2C81198A8CA5151F0FC086556B8D63610E9DDB237DA1AFAC7378838897FA46A776BE5 --ca-cert FTABCEV4XDq64xZcJAIBNwMnFAEAAADKysrKGCYE7xcbJyYFbrW5TDcGJxMEAAAAysrKyicVHQAAAAAAsPoYJAcBJAgBMAlBBGkJFgZS5gA13q/17k3O1uRRuxcdOZcodBk8vep54sgRmKjKUVHw/AhlVrjWNhDp3bI32hr6xzeIOIl/pGp3a+U3CjUBKQEkAgAYJAJgMAQUTMntCbE2MN9jRhRZ0bmiX4LtcIYwBRTwPNuYHS2KwOmYp5Apx6b9P/ztyBgwC0D8Ieqk5XNVp4h3De3CAlndmNqPzT/yGQFkgjozuBz41efPVctoPODsGq6zKv/0RIO45obJNN8X1pGQrtv/9JVSGA== --key 04F1C53AFB1761A75FF07437018E5B76BC75F852904DC7C4607839A5D953140FFE253626FB737647F1043F61D91B5EC0D3B42A7A25FA209CAB7ACD1A76CA46ECD2 --out Chip-Node02-Cert.chip-b64 --out-format chip-b64
```
Note that in the last example, to illustrate the fact that multiple key/cert
formats are supported, the CA private key is in the X509 Hex format, the CA
certificate is in the CHIP TLV base64 format and the Node public key is in the
CHIP TLV Hex format.
Now the 'chip-cert' tool can be used to validate generated Node certificate:
```
./chip-cert validate-cert Chip-Node-Cert.chip-b64 -c Chip-ICA-Cert.pem -t Chip-Root-Cert.pem
```
Typically, CA services generate certificates in a standard X.509 PEM format.
They can then use this 'chip-cert' tool to convert certificate into raw CHIP TLV
format before provisioning device with operational credentials:
```
./chip-cert convert-cert Chip-ICA-Cert.pem Chip-ICA-Cert.chip --chip
```
Developers can use this tool to print the content of a CHIP certificate in a
human friendly/readable form:
```
./chip-cert print-cert Chip-ICA-Cert.chip
```
### Attestation Certificates Usage Examples
Example command that can be used to generate Product Attestation Authority (PAA)
certificate and private key:
```
./chip-cert gen-att-cert --type a --subject-cn "Matter Development PAA 01" --valid-from "2020-10-15 14:23:43" --lifetime 7305 --out-key Chip-PAA-Key.pem --out Chip-PAA-Cert.pem
```
The PAA certificate/key output of last command can then be used to generate the
Product Attestation Intermediate (PAI) certificate and private key:
```
./chip-cert gen-att-cert --type i --subject-cn "Matter Development PAI 01" --subject-vid FFF1 --valid-from "2020-10-15 14:23:43" --lifetime 7305 --ca-key Chip-PAA-Key.pem --ca-cert Chip-PAA-Cert.pem --out-key Chip-PAI-Key.pem --out Chip-PAI-Cert.pem
```
The generated PAI certificate/key can then be used to sign multiple Device
Attestation Certificates (DAC):
```
./chip-cert gen-att-cert --type d --subject-cn "Matter Development DAC 01" --subject-vid FFF1 --subject-pid 0123 --valid-from "2020-10-15 14:23:43" --lifetime 7305 --ca-key Chip-PAI-Key.pem --ca-cert Chip-PAI-Cert.pem --out-key Chip-DAC-Key.pem --out Chip-DAC-Cert.pem
```
Now the 'chip-cert' tool can be used to validate generated Node certificate:
```
./chip-cert validate-att-cert --dac Chip-DAC-Cert.pem --pai Chip-PAI-Cert.pem --paa Chip-PAA-Cert.pem
```
The equivalent openssl command line tool can also be used to verify the
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 or string containing CA certificate to be used to sign the new certificate.
-K, --ca-key
File or string containing CA private key to be used to sign the new certificate.
-k, --key
File or string 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.
If specified '-' then output is written to stdout.
-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.
If specified '-' then output is written to stdout.
-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 raw format
x509-hex - X.509 DER hex encoded format
chip - raw CHIP TLV format
chip-b64 - base-64 encoded CHIP TLV format (default)
chip-hex - hex encoded CHIP TLV format
-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 operational certificate between CHIP and X.509 formats.
ARGUMENTS
File or string containing certificate to be converted.
The format of the input certificate is auto-detected and can be any of:
X.509 PEM, X.509 DER, X.509 HEX, CHIP base-64, CHIP raw TLV or CHIP HEX.
The output certificate file name, or '-' to write to stdout.
COMMAND OPTIONS
-p, --x509-pem
Output certificate in X.509 PEM format.
-d, --x509-der
Output certificate in X.509 DER format.
-X, --x509-hex
Output certificate in X.509 DER hex encoded format.
-c, --chip
Output certificate in raw CHIP TLV format.
-x, --chip-hex
Output certificate in CHIP TLV hexadecimal 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 private/public key between CHIP and X.509 formats.
ARGUMENTS
File or string containing private/public key to be converted.
The format of the input key is auto-detected and can be any of:
X.509 PEM, X.509 DER, X.509 HEX, CHIP base-64, CHIP raw TLV or CHIP HEX.
Note: the private key formats include both private and public keys, while
the public key formats include only public keys. Therefore, conversion from any
private key format to public key is supported but conversion from public key
to private CANNOT be done.
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.
-d, --x509-der
Output the private key in SEC1/RFC-5915 DER format.
-x, --x509-hex
Output the private key in SEC1/RFC-5915 DER hex encoded format.
-P, --x509-pubkey-pem
Output the public key in SEC1/RFC-5915 PEM format.
-c, --chip
Output the private key in raw CHIP serialized format.
-x, --chip-hex
Output the private key in hex encoded CHIP serialized format.
-b, --chip-b64
Output the private key in base-64 encoded CHIP serialized format.
This is the default.
-e, --chip-hex
Output the private key in hex encoded CHIP serialized format.
-C, --chip-pubkey
Output the raw public key.
-B, --chip-pubkey-b64
Output the public key in base-64 encoded format.
-E, --chip-pubkey-hex
Output the public key in hex encoded format.
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 or string containing the certificate to be re-signed.
-o, --out
File to contain the re-signed certificate.
If specified '-' then output is written to stdout.
-C, --ca-cert
File or string containing CA certificate to be used to re-sign the certificate.
-K, --ca-key
File or string 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
File or string containing the certificate to be validated.
The formats of all input certificates are auto-detected and can be any of:
X.509 PEM, X.509 DER, X.509 HEX, CHIP base-64, CHIP raw TLV or CHIP HEX.
COMMAND OPTIONS
-c, --cert
File or string containing an untrusted CHIP certificate to be used during
validation. Usually, it is Intermediate CA certificate (ICAC).
-t, --trusted-cert
File or string containing a trusted CHIP certificate to be used during
validation. Usually, it is trust anchor root certificate (RCAC).
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 operational certificate.
ARGUMENTS
File or string 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 Attestation 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 or string containing CA certificate to be used to sign the new certificate.
-K, --ca-key
File or string containing CA private key to be used to sign the new certificate.
-k, --key
File or string 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).
If specified '-' then output is written to stdout.
-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.
If specified '-' then output is written to stdout.
-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
File or string containing Device Attestation Certificate (DAC) to be validated.
The DAC format is auto-detected and can be any of: X.509 PEM, DER or HEX formats.
-i, --pai
File or string containing Product Attestation Intermediate (PAI) Certificate.
The PAI format is auto-detected and can be any of: X.509 PEM, DER or HEX formats.
-a, --paa
File or string containing trusted Product Attestation Authority (PAA) Certificate.
The PAA format is auto-detected and can be any of: X.509 PEM, DER or HEX formats.
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 or string containing private key to be used to sign the Certification Declaration.
-C, --cert
File or string 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.
If specified '-' then output is written to stdout.
-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.
```
#### gen-cd example
An example of generating a Certificate Declaration (CD) follows:
```
./chip-cert gen-cd -C credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem -K credentials/test/certification-declaration/Chip-Test-CD-Signing-Key.pem --out cd.bin -f 1 -V FFF1 -p 8000 -d 0016 -c "ZIG0000000000000000" -l 0 -i 0 -n 0001 -t 0
```
The binary output of the CMS signed CD is written to `cd.bin`.
- Replace -V FFF1 with your VID in uppercase hex with zero padding
- Replace -p 8000 with your PID in uppercase hex with zero padding
- Replace -d 0016 with your primary device type in uppercase hex with zero
padding
NOTE: `dac-origin-vendor-id` and `dac-origin-product-id` are not included in
this example.
### print-cd
```
$ ./out/debug/standalone/chip-cert print-cd -h
Usage: chip-cert print-cd []
Print a CHIP certification declaration (CD) content.
ARGUMENTS
File or string containing a CHIP CMS Signed CD message.
COMMAND OPTIONS
-o, --out
The output printed CD content 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.
```
#### print-cd example
An example of printing a Certificate Declaration (CD), which is provided as a
command line argument in a hex format:
```
./chip-cert print-cd 3081f506092a864886f70d010702a081e73081e4020103310d300b0609608648016503040201305006092a864886f70d010701a0430441152400012501f2ff360205018005028018250334122c04135a494732303134325a423333303030322d3234240500240600250794262408002509f1ff250a008018317e307c020103801462fa823359acfaa9963e1cfa140addf504f37160300b0609608648016503040201300a06082a8648ce3d04030204483046022100926296f7578158be7c459388336ca7383766c9eedd9855cbda6f4cf6bdf43211022100e0dbf4a2bcec4ea274baf0dea208b3365c6ed544086d101afdaf079a2c23e0de
```
### 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
```