committedderecshare.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";

/*
 * A DeRec share that is committed and ready to be given to a helper to store.
 * During recovery, this protobuf message is returned.
 * The commitment involves a Merkle tree.  The hash of the share given to
 * each helper is one leaf in the tree.  Each leaf hash and internal hash
 * is a SHA-384 hash. The Merkle path from a leaf to the root (which is the
 * siblings of all nodes along that route) is called merklePath.
 * The root hash is called a "commitment".
 */
message CommittedDeRecShare {
  /*
   * Protobuf serialization of DeRecShare.
   */
  bytes deRecShare = 1;

  /** The Merkle root */
  bytes commitment = 2;

  /* one leaf or interior node. isLeft is true if it's a left child */
  message SiblingHash {
    bool isLeft = 1;
    bytes hash = 2;
  }

  /* The bottom-up Merkle path */
  repeated SiblingHash merklePath = 3;
}


/*
 * The information to share with a helper.
 * The sharer first generates a random AES-256 key k, and uses that
 * to AES-GCM encrypt the secret. A random polynomial f is generated
 * such that f(0)=k, and is evaluated at a random x value for the
 * intended helper.  The share contains y, where f(x) = y.
 * This should be done in GF(p), where p is the smallest 256-bit prime.
 * The order of the polynomial is the threshold for how many helpers are needed
 * to recover it.
 * This also includes the secretId and share version number, because they
 * should be serialized along with this, in order for them all to be signed
 * together.
 */
message DeRecShare {
  /*
   * The result of taking the secret to be shared, serializing it,
   * then encrypting it with a random AES-256 key.
   */
  bytes encryptedSecret = 1;

  /*
   * This is a random 256-bit integer, 2's complement, big endian.
   */
  bytes x = 2;

  /*
   * This is f(x)
   */
  bytes y = 3;

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

  /*
   * version number for the share;
   * note that helper is entitled to ignore any
   * StoreShareRequestMessage with a version less
   * than or equal to the last seen version
   */
  int32 version = 5;
}