derecmessage.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 "google/protobuf/timestamp.proto";
import "pair.proto";
import "unpair.proto";
import "storeshare.proto";
import "verify.proto";
import "getshare.proto";
import "secretidsversions.proto";
import "error.proto";

package org.derecalliance.derec.protobuf;

/*
 * Every message in the protocol (other than ContactMessage) consists
 * of sending this protobuf message.
 *
 * This protobuf message is protobuf serialized to a binary byte array, then
 * signed with the sender's private signature key, then encrypted with the
 * receiver's public encryption key.  The OpenPGP format is used for the
 * signed-then-encrypted message. The sender then sends the concatenation of 
 * the keyID of the recipient, followed by the signed-then-encrypted message. 
 * The keyID is a 32-bit signed integer (big endian), used to identify which
 * encryption key the recipient should use to decrypt the message.
 * 
 * This message will usually contain only a single DeRecMessage. If it contains
 * more, then it is equivalent to sending them individually, in the
 * given order.
 *
 * This can contain multiple individual requests or responses, and they will be
 * guaranteed to arrive in order and together, to allow atomic execution of
 * several requests at once, such updating a version, then immediately asking
 * for a listing of all known versions.
 */
message DeRecMessage {
  /*
   * DeRec protocol version number
   */
  int32 protocolVersionMajor = 1;
  int32 protocolVersionMinor = 2;

  /*
   * SHA-384 hash of sender public key (used to identify the sender and key)
   */
  bytes sender = 3;

  /*
   * SHA-384 hash of receiver's public key
   * (used to prevent signature-replacement attacks)
   */
  bytes receiver = 4;

  /*
   * Secret ID (any length from 1 to 16 bytes)
   * Must be unique for each secret created by a sharer.
   */
  bytes secretId = 5;

  /*
   * UTC timestamp for when the sender created this message
   */
  google.protobuf.Timestamp timestamp = 6;

  /*
   * message body is one of several possible DeRec messages
   */
  MessageBodies messageBodies = 7;

  message MessageBodies {
    oneof messages {
      HelperMessageBodies helperMessageBodies = 1;
      SharerMessageBodies sharerMessageBodies = 2;
    }
  }

  /**
   * message body is one of several possible DeRec messages from a sharer
   */
  message SharerMessageBodies {
    repeated SharerMessageBody sharerMessageBody= 1;
  }

  message SharerMessageBody {
    oneof body {
      PairRequestMessage pairRequestMessage = 1;
      UnpairRequestMessage unpairRequestMessage = 2;
      StoreShareRequestMessage storeShareRequestMessage = 3;
      VerifyShareRequestMessage verifyShareRequestMessage = 4;
      GetSecretIdsVersionsRequestMessage getSecretIdsVersionsRequestMessage = 5;
      GetShareRequestMessage getShareRequestMessage = 6;
    }
  }
  message HelperMessageBodies {
    repeated HelperMessageBody helperMessageBody= 1;
  }

  message HelperMessageBody {
    oneof body {
      PairResponseMessage pairResponseMessage = 1;
      UnpairResponseMessage unpairResponseMessage = 2;
      StoreShareResponseMessage storeShareResponseMessage = 3;
      VerifyShareResponseMessage verifyShareResponseMessage = 4;
      GetSecretIdsVersionsResponseMessage getSecretIdsVersionsResponseMessage = 5;
      GetShareResponseMessage getShareResponseMessage = 6;
      ErrorResponseMessage errorResponseMessage = 7;
    }
  }
}