doc: chip_tool: pairing and commissioner flags

Updated the CHIP Tool guide with information about pairing and
commissioner flags.

Signed-off-by: Grzegorz Ferenc <[email protected]>

docs/guides/chip_tool_guide.md

@@ -489,6 +489,8 @@ Usage:
 
 ```
 
+<hr>
+
 ### Getting the list of commands supported for a specific cluster
 
 To print the list of commands supported by a specific cluster, use the following
@@ -539,6 +541,8 @@ Usage:
 
 ```
 
+<hr>
+
 ### Getting the list of attributes supported for a specific cluster
 
 To get the list of attributes for a specific cluster, use the following command
@@ -583,6 +587,8 @@ Usage:
 [1647417857.914110][404444:404444] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:120: Error 0x0000002F
 ```
 
+<hr>
+
 ### Getting the list of command options
 
 To get the list of parameters for a specific command, use the following command
@@ -668,6 +674,50 @@ The following flags are available:
     Here, _<onoff\>_ is a `[0/1]` flag, which when set to `1` prints the trace
     data with automation logs to the console.
 
+<hr>
+
+### Commissioner name and ID flags
+
+All CHIP Tool commands can be used together with the following commissioner-related flags:
+
+- `--commissioner-name`
+- `--commissioner-nodeid`
+
+These flags let you inform the Matter device about which commissioner it must interact with.
+They are especially useful in scenarios where you are working with more than one fabric, but you can also use it with a single commissioner.
+
+#### `--commissioner-name` flag
+
+As per the CHIP Tool implementation, the commissioners are required to have the following names: `alpha` for the first one, `beta` for the second one, `gamma` for the third one, `4` for the fourth one, `5` for the fifth one, and so on.
+
+If you don't use this flag, the CHIP Tool assumes that the command is meant for the `alpha` commissioner.
+
+**Example of commands:**
+
+```
+$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 1 '0,0,1,0,0,0' --keepSubscriptions true
+$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 2 '0,0,1,0,0,0' --keepSubscriptions true --commissioner-name beta
+$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 3 '0,0,1,0,0,0' --keepSubscriptions true --commissioner-name gamma
+```
+
+#### `--commissioner-nodeid` flag
+
+Each commissioner has a node ID that you can use instead of its name when providing the commissioning flags.
+
+If you don't use this flag, the CHIP Tool assumes that the command is meant for the `alpha` commissioner with the default node ID `112233`.
+
+**Example of commands:**
+
+```
+chip-tool pairing ble-thread 12378411096372871992 hex:0e08000000000001000035060004001fffe00708fd6be52118a6b9000410205c6257d29b2115d3065fdb6e855f830c0402a0f7f8000300000d0102adda02081111111122224589051000aa22dd445566778899aabbccddeeff030a4f70656e546872656164 20202021 3840 --commissioner-name alpha --commissioner-nodeid 123321
+```
+
+```
+any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 3 '0,0,1,0,0,0' --keepSubscriptions true --commissioner-name gamma --commissioner-nodeid 123321
+```
+
+<hr>
+
 ### Running a test suite against a paired peer device
 
 The CHIP Tool allows to run a set of tests, already compiled in the tool,
@@ -693,6 +743,8 @@ against a paired Matter device.
 See the [Examples](#running-testclusters-test) section for an example of how to
 run a test from the test suite.
 
+<hr>
+
 ### Parsing the setup payload
 
 The CHIP Tool offers a utility for parsing the Matter onboarding setup payload
@@ -722,6 +774,8 @@ Here, _<payload\>_ is the ID of the payload to be parsed.
     $ ./chip-tool payload parse-setup-payload 34970112332
     ```
 
+<hr>
+
 ### Parsing additional data payload
 
 To parse additional data payload, use the following command pattern:
@@ -734,6 +788,8 @@ In this command:
 
 -   _<payload\>_ is the ID of the payload with additional data to be parsed.
 
+<hr>
+
 ### Discover actions
 
 The `discover` command can be used to resolve node ID and discover available
@@ -778,25 +834,55 @@ following command:
 $ ./chip-tool discover commissioners
 ```
 
+<hr>
+
 ### Pairing
 
-The `pairing` command supports different means regarding Matter device
-commissioning procedure.
+The `pairing` command supports different methods for Matter device
+commissioning procedure. The three most common methods are described in the
+[Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
+section and are the following:
 
-Thread and Wi-Fi commissioning use cases are described in the
-[Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
-section.
+- `ble-thread` - For Thread commissioning; described under [Commissioning into a Thread network over Bluetooth LE](#commissioning-into-a-thread-network-over-bluetooth-le).
+- `ble-wifi` - For Wi-Fi commissioning; described under [Commissioning into a Wi-Fi network over Bluetooth LE](#commissioning-into-a-wi-fi-network-over-bluetooth-le)
+- `onnetwork` - For commissioning the device when it is already present in an IP network; described under [Commissioning with setup PIN code](#commissioning-with-setup-pin-code)
 
-To list all `pairing` sub-commands, run the following command:
+To list all `pairing` sub-commands and commissioning methods, run the following command:
 
 ```
 $ ./chip-tool pairing
 ```
 
+#### Attestation-related flags
+
+The `pairing` commissioning command can be run with several flags that allow you to modify attestation-related settings:
+
+- `--paa-trust-store-path` - Use to provide path to the directory that contains the information about Product Attestation Authority (PAA) certificate.
+  The path can be absolute or relative to the current working directory.
+  With this flag, the CHIP Tool looks for the PAA certificate that matches the PAI and the DAC certificates programmed on the device.
+  Without this flag, the CHIP Tool uses the test PAA certificate.
+
+- `--cd-trust-store-path` - Use to provide path to the directory that contains the information about Certificate Declaration.
+  The path can be absolute or relative to the current working directory.
+  With this flag, the CHIP tool looks for the CD that matches other attestation data on the device.
+  Without this flag, the CHIP Tool uses the test CD.
+
+- `--only-allow-trusted-cd-keys` - Use to only allow trusted CD verifying keys (disallow test keys).
+  If the flag is not provided or it is provided with the value `0` ("false"), untrusted CD verifying keys are allowed.
+  If it is provided with the value `1` ("true", `--only-allow-trusted-cd-keys 1`), test keys are disallowed and CD used for attestation will not be accepted.
+  This setting is parsing CD for an `int` enumeration that sets the test status of CD.
+
+- `--bypass-attestation-verifier` - Use to bypass the attestation verifier.
+  If the flag is not provided or it is provided with the value `0` ("false"), the attestation verifier is not bypassed.
+  If it is provided with the value `1` ("true", `--bypass-attestation-verifier 1`), the commissioning will continue in case of the attestation verification failure.
+  The failure can be caused by errors in Certification Declaration, the PAA or the PAI certificates, or in the Device Attestation Certificate. This option can be useful is you want to quickly commission a device with the PAI and the DAC certificates that are based on an unknown PAI certificate, or when using a CD to which we don't have access (for example it is part of an officially certified device).
+
+<hr>
+
 ### Interacting with Data Model clusters
 
 As mentioned in the
-[Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
+[Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
 section, executing the `chip-tool` command with a particular cluster name lists
 all operations supported for this cluster, as in the following command pattern:
 
@@ -910,6 +996,8 @@ Complete the following steps to
 Read the [CHIP Test Suits](../../src/app/tests/suites/README.md) page for more
 information about how the test suite is structured.
 
+<hr>
+
 ### Multi-admin scenario
 
 Multi-admin feature allows you to join Matter device to several Matter fabrics