pair.proto

/*
 * Copyright (c) DeRec Alliance and its Contributors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";
import "communicationinfo.proto";
import "parameterrange.proto";
import "result.proto";

package org.derecalliance.derec.protobuf;
/*
 * Is the sender of this message (i.e., the responder) a
 * helper, or a sharer that is not in recovery mode, or a sharer that is
 * in recovery mode?
 */
enum SenderKind {
  SHARER_NON_RECOVERY = 0;
  SHARER_RECOVERY = 1;
  HELPER = 2;
}

/*
* ----------------------------------------------------------------------------
* Pairing protocol
* First message sent from the pairing initiator to the pairing
* responder. There would earlier have been communication of the information
* in a ContactMessage that was sent from the responder to the initiator by some
* other means. For example, the responder could display a QR code that the
* initiator scanned.
* The initiator can be helper or sharer, and
* the responder can be sharer or helper.
* ----------------------------------------------------------------------------
*/
message PairRequestMessage {
  /*
   * The kind of the sender of this message (i.e., the responder)
   */
  SenderKind senderKind = 1;

  /*
   * public key (PEM encoded - RFC 7468) used for signing messages from the initiator
   */
  string publicSignatureKey = 3;

  /*
   * public key (PEM encoded - RFC 7468) used for encrypting messages to the initiator
   */
  string publicEncryptionKey = 4;

/**
  * A number used to later identify the publicEncryptionKey. 
  * When any message is later sent to this initiator, and it is encrypted
  * with the publicEncryptionKey, this identifier is also sent, so the recipient 
  * knows which key to use to decrypt it. If the recipient creates multiple 
  * keys for multiple pairings, then they should remember the publicKeyId that
  * they chose for each one, so they won't have to try all the keys during decryption. 
  */
 int32 publicKeyId = 5;

  /*
   * sender’s app-readable contact information,
   * such as name, phone number, etc.
   */
  CommunicationInfo communicationInfo = 6;

  /*
   * 64-bit (random) nonce to identify the pairing session
   */
  int64 nonce = 7;

  /*
   * The parameter range for the sender.
   */
  ParameterRange parameterRange = 8;
}

/*
 * Response, which is identical to the request, except without the
 * public encryption key, because it already happened during contact.
 */
message PairResponseMessage {
  /** the success or failure of processing the request */
  Result result = 1;


  /*
   * The kind of the sender of this message (i.e., the responder)
   */
  SenderKind senderKind = 2;

  /*
   * public signature key (PEM encoded) of the responder
   */
  string publicSignatureKey = 3;

  /*
   * app-readable contact information (e.g. name, phone number, etc.)
   */
  CommunicationInfo communicationInfo = 4;

  /*
   * 64-bit (random) nonce to identify the pairing session;
   * this is the same value as sent in the pairing request
   */
  int64 nonce = 5;

  /*
   * The parameter range for the sender.
   */
  ParameterRange parameterRange = 6;
}