Match CLI

Search…
Match CLI
Direct "headless" matching with an Optable DCN
What is Match CLI?
The match CLI (Command Line Interface) is a utility designed to enable a partner to execute a directional secure ID match with a company's data collaboration node (Optable DCN). The operation is performed using data from a local file which contains a list of matchable identifiers.
The result of the match attempt is learned by the receiving company's Optable DCN, while the sender executing the operation with the match CLI learns only the size of the resulting intersection (note that some "noise" is added by the receiver DCN to the resulting match size communicated to the sender, in order to protect from various information discovery attacks).
The match CLI is not to be confused with the Optable CLI utility used by Optable customers to access and manage their DCN.
While both are CLI (Command Line Interface) utilities, the match CLI is used to stand up a temporary lightweight matching node, while the Optable CLI utility is designed to access and manage all of the functionality provided by a fully-featured data collaboration node (DCN).
Why Not Just Send My Data?
Transferring your private list of identifiers to the receiver or a third-party broker leaks a significant amount of personal data. To protect against such leaks, data brokers typically request that you hash your private data prior to transfer. However, comparing hashed datasets requires sharing hash function parameters with the receiving or brokering party, leaving the door open to possible brute force attacks on your private data. In contrast, the match CLI utility performs a secure match which encrypts your data with your own private key prior to transferring it. Determining a match on fully encrypted data is possible thanks to a multi-party computation technique which is implemented by the match CLI. To learn more about how it works, see Secure Matching.
Who Should Use Match CLI?
The match CLI utility is designed to be used by partners of Optable customers who are not also using DCN, but who wish to perform secure matching with a DCN customer without transferring their private data to a third-party.
Note that if you are also an Optable customer and have access to your own DCN, you can perform matches directly with other Optable customers from your collaboration node's UI. Therefore, you should not need to use the match CLI utility.
Downloading Match CLI
The latest version of the match CLI can be downloaded from the GitHub releases page.
Note that on OS X or Linux you may need to chmod +x ./optable-match-cli before you can run the executable with ./optable-match-cli
Using Match CLI
To begin, you should have received an invitation code from an Optable DCN customer to whom you would like to send a match. Note that the invitation code expires after a few hours, so if you haven't used it to establish a connection with the partner, you may need to request a fresh one.
Step 1: Handshake With Partner
First, connect to your partner by choosing a name to identify them in subsequent commands, and using your invitation code. You should replace <partner-name> and <invite-code> below:
$ optable-match-cli partner connect <partner-name> "<invite-code>"
On success, you should see a JSON representation of the partner, similar to:
{
  "name":"my-partner",
  "description":"",
  "url":"https://partner.cloud.optable.co/admin/api/external",
  "id":"1ra9VwXR6C9GPZgrHCs2iOf9ILe",
  "private_key":"MHcCAQEEIP..."
}
Be careful to keep your private_key secret since it is used to identify and authenticate you.
Step 2: Create a Match
Next, create a descriptive name for the match in your connected partner's DCN. You can do this by running the following command, replacing <partner-name> and <match-name> accordingly:
$ optable-match-cli match create <partner-name> <match-name>
On success, you should see a JSON representation of the newly created match along with a UUID associated with the match that you can reference when you send a match in Step 4:
{"match_uuid":"1sia22TooI1o193UUL6Sh6bklzB"}
Step 3: Prepare Data to Match
You should prepare a list of type-prefixed and matchable IDs that you would like to perform a match with. See Identifier Types for the list of supported ID types, required encodings, and type prefix values to use. Note that you can mix ID types in a single match file.
Here is an example snippet of a match file containing several matchable ID types:
e:99c957463eb46684f07c2986e3d55961ad027051a1a7a5d4a1e555fd12d33b02
e:99c95c3b5d521e7175f73a698e4561a0bffbdc38701a6599ed24376b57c922f8
e:99c96da5df6a5ca3e7f370eecf13fc86b7c7f555c341dce0256ec2352b08d174
e:99c9752e9c16e62e93e99ffa8cb0b1e6b7fc1772356e455b646c4d8d728bb3ca
e:99c9c35c70f51632173302f49016c43b2f5d91e953f4505846712df96656e8fe
i4:8.8.8.8
i4:1.1.1.1
i4:192.168.3.12
Step 4: Send a Match
Finally, initiate a match attempt referring to a previously created match by its UUID and the path to your prepared data file:
$ optable-match-cli match run <partner-name> <match-uuid> <path-to-file>
Make sure to replace <partner-name>, <match-uuid>, and <path-to-file> accordingly.
Once initiated, the optable-match-cli will encrypt each of the IDs in your data file using your private key and execute a secure match protocol with your partner's Optable DCN. On successful completion, the number of matched IDs for each matched ID type will be displayed.
Example execution output follows -- note that the last line in the output displays the number of IDs by type which are in the match result:
$ optable-match-cli match run my-partner 1sia22TooI1o193UUL6Sh6bklzB ./my-data-file.dat
2021-05-18T13:23:12-04:00 INF running match 1sia22TooI1o193UUL6Sh6bklzB with a timeout of 30m0s cli=optable-match-cli
2021-05-18T13:23:12-04:00 INF loaded 3001 records from ./my-data-file.dat cli=optable-match-cli
2021-05-18T13:23:12-04:00 INF polling /match/run with a timeout of 1m0s to get match endpoint cli=optable-match-cli
2021-05-18T13:23:12-04:00 INF generated match result id 1sibwAJXyp8ptEr4W0CRIUs6deB cli=optable-match-cli
2021-05-18T13:23:12-04:00 INF still polling /match/run to get match endpoint cli=optable-match-cli
2021-05-18T13:23:18-04:00 INF still polling /match/run to get match endpoint cli=optable-match-cli
2021-05-18T13:23:23-04:00 INF still polling /match/run to get match endpoint cli=optable-match-cli
2021-05-18T13:23:23-04:00 INF got match endpoint receive-994c6fc7.match.partner.cloud.optable.co:25519 cli=optable-match-cli
2021-05-18T13:23:23-04:00 INF running dhpsi protocol on receive-994c6fc7.match.partner.cloud.optable.co:25519 cli=optable-match-cli
2021-05-18T13:27:48-04:00 INF successfully completed dhpsi protocol cli=optable-match-cli
2021-05-18T13:27:48-04:00 INF polling /match/get-result for results cli=optable-match-cli
2021-05-18T13:27:48-04:00 INF still polling /match/get-result for results cli=optable-match-cli
2021-05-18T13:27:53-04:00 INF still polling /match/get-result for results cli=optable-match-cli
2021-05-18T13:27:58-04:00 INF still polling /match/get-result for results cli=optable-match-cli
2021-05-18T13:27:59-04:00 INF got results from /match/get-result cli=optable-match-cli
{"time":"2021-05-18T17:27:49.070911Z","id":"1sibwAJXyp8ptEr4W0CRIUs6deB","state":"completed","results":{"emails":3017}}
Depending on the number of IDs in your data file, match execution may take some time. The optable-match-cli must be able to fully buffer your input data file in memory, so ensure to execute it on a suitably provisioned machine, with sufficient memory resources capable of handling the size of your match data.
Last modified 6mo ago
Copy link
Outline
What is Match CLI?
Why Not Just Send My Data?
Who Should Use Match CLI?
Downloading Match CLI
Using Match CLI