frostfs-api/session/service.proto

syntax = "proto3";

package frost.fs.session;

import "refs/types.proto";
import "session/types.proto";

// `SessionService` allows to establish a temporary trust relationship between
// two peer nodes and generate a `SessionToken` as the proof of trust to be
// attached in requests for further verification. Please see corresponding
// section of FrostFS Technical Specification for details.
service SessionService {
  // Open a new session between two peers.
  //
  // Statuses:
  // - **OK** (0, SECTION_SUCCESS):
  // session has been successfully opened;
  // - Common failures (SECTION_FAILURE_COMMON).
  rpc Create(CreateRequest) returns (CreateResponse);
}

// Information necessary for opening a session.
message CreateRequest {
  // Session creation request body
  message Body {
    // Session initiating user's or node's key derived `OwnerID`
    frost.fs.refs.OwnerID owner_id = 1;
    // Session expiration `Epoch`
    uint64 expiration = 2;
  }
  // Body of a create session token request message.
  Body body = 1;

  // Carries request meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.session.RequestMetaHeader meta_header = 2;

  // Carries request verification information. This header is used to
  // authenticate the nodes of the message route and check the correctness of
  // transmission.
  frost.fs.session.RequestVerificationHeader verify_header = 3;
}

// Information about the opened session.
message CreateResponse {
  // Session creation response body
  message Body {
    // Identifier of a newly created session
    bytes id = 1;

    // Public key used for session
    bytes session_key = 2;
  }

  // Body of create session token response message.
  Body body = 1;

  // Carries response meta information. Header data is used only to regulate
  // message transport and does not affect request execution.
  frost.fs.session.ResponseMetaHeader meta_header = 2;

  // Carries response verification information. This header is used to
  // authenticate the nodes of the message route and check the correctness of
  // transmission.
  frost.fs.session.ResponseVerificationHeader verify_header = 3;
}