package com.seagate.kinetic.proto

Get desktop application:
View/edit binary Protocol Buffers messages

• optional Command.Header header = 1

  message header

• optional Command.Body body = 2

  message body

• optional Command.Status status = 3

  operation status

algorithm

Used in: KeyValue, Versioned.Metadata

• INVALID_ALGORITHM = -1

  Must come first, so default is invalid

• SHA1 = 1

  see NIST

• SHA2 = 2

  see NIST

• SHA3 = 3

  see NIST. The length of the tag determined the length of the hash

• CRC32C = 4

• CRC64 = 5

• CRC32 = 6

  7-99 are reserved. 100-inf are private algorithms.

This is included in the END_BATCH and END_BATCH_RESPONSE.

Used in: Body

• optional int32 count = 1

  set by the client library in END_BATCH request message. the total number of operations in the batch

• repeated int64 sequence = 2

  set by the drive in END_BATCH_RESPONSE message. If a batch is committed successfully, all sequence Ids of those commands (PUT/DELETE) performed in the batch are added in the END_BATCH_RESPONSE message.

• optional int64 failedSequence = 3

  This field is set by the drive if a batch commit failed. The first failed operation sequence in the batch is set as value.

message body

Used in: Command

• optional KeyValue keyValue = 1

  key/value op

• optional Range range = 2

  range operation

• optional Setup setup = 3

  set up operation

• optional P2POperation p2pOperation = 4

  Peer to Peer operations.

• optional GetLog getLog = 6

  GetLog

• optional Security security = 7

  set up security

• optional PinOperation pinOp = 8

  Perform Pin-based operations

• optional Batch batch = 9

  batch operation This is included in the END_BATCH and END_BATCH_RESPONSE.

get log

Used in: Body

• repeated GetLog.Type types = 1

• repeated GetLog.Utilization utilizations = 2

• repeated GetLog.Temperature temperatures = 3

• optional GetLog.Capacity capacity = 4

• optional GetLog.Configuration configuration = 5

• repeated GetLog.Statistics statistics = 6

• optional bytes messages = 7

• optional GetLog.Limits limits = 8

• optional GetLog.Device device = 9

These capacities are in bytes.

Used in: GetLog

• optional uint64 nominalCapacityInBytes = 4

  1-3 are reserved

• optional float portionFull = 5

Used in: GetLog

• optional string vendor = 5

  name of the vendor. Should be "Seagate"

• optional string model = 6

  The model of the device. "Simulator" for the simulator.

• optional bytes serialNumber = 7

  Device Serial number (SN)

• optional bytes worldWideName = 14

  Device world wide name (WWN)

• optional string version = 8

  This is the vendor specific version of the software on the device in dot notation if this is not set or ends with "x" this is test code.

• optional string compilationDate = 12

• optional string sourceHash = 13

• optional string protocolVersion = 15

  This is the version of the protocol (.proto file) that the device uses. This is not the highest or lowest version that is supported, just the version that was compiled.

• optional string protocolCompilationDate = 16

• optional string protocolSourceHash = 17

• repeated Configuration.Interface interface = 9

  the interfaces for this device. one per interface.

• optional int32 port = 10

  these are the port numbers for the software

• optional int32 tlsPort = 11

18, 19 are reserved.

Used in: Configuration

• optional string name = 1

• optional bytes MAC = 2

• optional bytes ipv4Address = 3

• optional bytes ipv6Address = 4

The Device GetLog message is to ask the device to send back the log of a certain name in the value field. The limit of each log is 1m byte. Proprietary names should be prefaced by the vendor name so that name collisions do not happen in the future. An example could be names that start with “com.WD” would be for Western Digital devices. If the name is not found, the get log returns NOT_FOUND. There can be only one Device in the list of logs that can be retrieved.!

Used in: GetLog

• optional bytes name = 1

Used in: GetLog

• optional uint32 maxKeySize = 1

• optional uint32 maxValueSize = 2

• optional uint32 maxVersionSize = 3

• optional uint32 maxTagSize = 4

• optional uint32 maxConnections = 5

• optional uint32 maxOutstandingReadRequests = 6

• optional uint32 maxOutstandingWriteRequests = 7

• optional uint32 maxMessageSize = 8

• optional uint32 maxKeyRangeCount = 9

• optional uint32 maxIdentityCount = 10

• optional uint32 maxPinSize = 11

• optional uint32 maxOperationCountPerBatch = 12

• optional uint32 maxBatchCountPerDevice = 13

These numbers start at 0 when the device starts up and never wraps or resets.

Used in: GetLog

• optional MessageType messageType = 1

• optional uint64 count = 4

  2 and 3 are reserved, do not use

• optional uint64 bytes = 5

  This is the sum of the data that is in the data portion. This does not include t the command description. For P2P operations, this is the amount of data moved between devices

Used in: GetLog

• optional string name = 1

  The name of the temperature being reported. These names can be standard and proprietary. The standard name is "HDA". If there are more items that are being reported, such as processor temperature, can have a descriptive name.

• optional float current = 2

  The current temperature in degrees c

• optional float minimum = 3

• optional float maximum = 4

• optional float target = 5

Used in: GetLog

• INVALID_TYPE = -1

  Must come first, so default is invalid

• UTILIZATIONS = 0

• TEMPERATURES = 1

• CAPACITIES = 2

• CONFIGURATION = 3

• STATISTICS = 4

• MESSAGES = 5

• LIMITS = 6

• DEVICE = 7

Used in: GetLog

• optional string name = 1

  The name of the utilization being reported. These names can be standard and proprietary. The standard names are "HDA", "EN0" and "EN1". If there are more items that are being reported, such as processor utilization, can have a descriptive name.

• optional float value = 2

  A number between 0.00 and 1.00. The resolution of this number is up to the device. 1 means 100% utilized.

message header

Used in: Command

• optional int64 clusterVersion = 1

  "cluster" is the number of the cluster definition. If this is incompatible, the request is rejected. If it is missing, it is assumed to be 0. (0 allows systems not using cluster versioning to ignore this field in the header and in the setup.)

• optional int64 connectionID = 3

  A unique number for this connection between the source and target. On the first request to the device, this should be the time of day in seconds since 1970. The device can change this number and the client must continue to use the new number and the number must remain constant during the session. (See security document).

• optional int64 sequence = 4

  the sequence of this request in this TCP connection. As long as this value is getting larger we have strong ordering and replay prevention within a session. This combined with the time and connectionID provides strong ordering between sessions. (See security document).

• optional int64 ackSequence = 6

  co-related sequence

• optional MessageType messageType = 7

  operation code - put/get/delete/GetLog, etc.

• optional int64 timeout = 9

  Request timeout (in ms). This is the amount of time that this request should take. If this timeout is triggered, there are three possible results that can be returned. - SERVICE_BUSY meaning that the request was still on the queue waiting to be executed - EXPIRED meaning that a long running operation was stopped because the time expired. - DATA_ERROR meaning that the request was in process, but that the error recovery was not complete at the time that the time expired

• optional bool earlyExit = 10

  If true, requests will not attempt multi revolution recoveries even if the timeout has not occurred. In this case the result will be DATA_ERROR. To have the device exhaust all possible error recovery, leave this field off or set to false, and make sure that the timeout is set to be longer than any possible queue time and error recovery time. On a disk device, the maximum error recovery time could be seconds. Once all possible data recovery operations are complete and have not succeeded, PERM_DATA_ERROR will be returned.

• optional Priority priority = 12

  Priority is a simple integer that determines the priority of this request. All activity at a higher priority will execute before that of lower priority traffic. A higher number is higher priority.

• optional int64 TimeQuanta = 13

  A hint of how long a job should run before yielding. Specified in miliseconds. A value of 0 indicates that the operation can perform one sub operation and then check to see if there are other sub higher priority operations. An example of a sub-operation might be a single put in a P2P operation, etc.

• optional uint32 batchID = 14

  batch id to be included in each command of a batch operation this id is generated by client library and must be unique within the same connection.

key/value entry operation

Used in: Body

• optional bytes newVersion = 2

  On a put or delete, this is the next version that the data will be. The version field is opaque to the target. (See Atomic operations document)

• optional bool force = 8

  On a put or delete, this forces the write to ignore the existing version of existing data (if it exists).

• optional bytes key = 3

  entry key

• optional bytes dbVersion = 4

  entry version in store

• optional bytes tag = 5

  this is the integrity value of the data. This may or may not be in the clear, depending on the algorithm used.

• optional Algorithm algorithm = 6

  The following is for the protection of the data. If the data is protected with a hash or CRC, then the algorithm will be negative. If the data protection algorithm is not a standard unkeyed algorithm then a positive number is used and the device has no idea what the key is. See the discussion of encrypted key/value store.(See security document).

• optional bool metadataOnly = 7

  for read operations, this will get all the information about the value except for the value itself. This is valuable for getting the integrity field or the version without also having to get the data. If this field is not present, it is as if it is false. For write or delete operations, if this is set, the command is rejected.

• optional Synchronization synchronization = 9

  Synchronization allows the puts and deletes to determine if they are to be WRITETHROUGH: This request is made persistent before returning. This does not effect any other pending operations. WRITEBACK: They can be made persistent when the device chooses, or when a subsequent FLUSH is give to the device. FLUSH: All pending information that has not been written is pushed to the disk and the command that specifies FLUSH is written last and then returned. All WRITEBACK writes that have received ending status will be guaranteed to be written before the FLUSH operation is returned completed.

operation code

Used in: GetLog.Statistics, Header

• INVALID_MESSAGE_TYPE = -1

  Must come first, so default is invalid

• GET = 2

  get operation

• GET_RESPONSE = 1

• PUT = 4

  put operation

• PUT_RESPONSE = 3

• DELETE = 6

• DELETE_RESPONSE = 5

• GETNEXT = 8

• GETNEXT_RESPONSE = 7

• GETPREVIOUS = 10

• GETPREVIOUS_RESPONSE = 9

• GETKEYRANGE = 12

• GETKEYRANGE_RESPONSE = 11

• GETVERSION = 16

  13 and 14 are reserved, do not use

• GETVERSION_RESPONSE = 15

• SETUP = 22

  17, 18, 19, and 20 are reserved, do not use

• SETUP_RESPONSE = 21

• GETLOG = 24

• GETLOG_RESPONSE = 23

• SECURITY = 26

• SECURITY_RESPONSE = 25

• PEER2PEERPUSH = 28

  peer to peer push operation

• PEER2PEERPUSH_RESPONSE = 27

• NOOP = 30

• NOOP_RESPONSE = 29

• FLUSHALLDATA = 32

• FLUSHALLDATA_RESPONSE = 31

• PINOP = 36

  33, 34 are reserved

  Pin based operations

• PINOP_RESPONSE = 35

• MEDIASCAN = 38

  Media scan is to check that the user data is readable, and if the end to end integrity is known to the device, if the end to end integrity field is correct.

• MEDIASCAN_RESPONSE = 37

• MEDIAOPTIMIZE = 40

  This performs optimizations of the media. Things like defragmentation, compaction, garbage collection, compression could be things accomplished using the media optimize command.

• MEDIAOPTIMIZE_RESPONSE = 39

• START_BATCH = 42

  batch operations

• START_BATCH_RESPONSE = 41

• END_BATCH = 44

• END_BATCH_RESPONSE = 43

• ABORT_BATCH = 46

• ABORT_BATCH_RESPONSE = 45

P2P operations allow devices to be able to send keys to other devices. this is either a standalone command or added to a put command.

Used in: Body, P2POperation.Operation

• optional P2POperation.Peer peer = 1

  Describe the target machine

• repeated P2POperation.Operation operation = 2

  List of operations to be performed.

• optional bool allChildOperationsSucceeded = 3

  Indicates whether all operations have Status SUCCESS When false, clients should traverse Operation status codes to discover error cases. When true, no further error checking should be required.

Used in: P2POperation

• optional bytes key = 3

  the key of the entry to move

• optional bytes version = 4

  the expected version number in the other machine the version number will be the version in the stored entry.

• optional bytes newKey = 5

  to have the moved key have a different final key used.

• optional bool force = 6

  force the write ignoring the current key version.

• optional Status status = 7

  returned status

• optional P2POperation p2pop = 8

  an operation to add to this put operation. THis allows the formation of a pipeline client -> A ->B ->C with the status for all returning back to the client.

Used in: P2POperation

• optional string hostname = 1

• optional int32 port = 2

• optional bool tls = 3

Pin Operations are used for special commands that are valid when the device is locked or to be locked. These are unlock, lock and erase. This must come over the TLS connection to protect the confidentiality and integrity. This operations must be used with PinAuth.

Used in: Body

• optional PinOperation.PinOpType pinOpType = 1

Used in: PinOperation

• INVALID_PINOP = -1

• UNLOCK_PINOP = 1

  The pin will unlock the device

• LOCK_PINOP = 2

  This will lock the device. This includes all configuration and user data. This operation is secure from even given physical access and disassembly of the device.

• ERASE_PINOP = 3

  Erase the device. This may be secure or not. The implication is that it may be faster than the secure operation.

• SECURE_ERASE_PINOP = 4

  Erase the device in a way that will physical access and disassembly of the device will not

Used in: Header, Security.ACL

• NORMAL = 5

• LOWEST = 1

• LOWER = 3

• HIGHER = 7

• HIGHEST = 9

key range op

Used in: Body

• optional bytes startKey = 1

• optional bytes endKey = 2

• optional bool startKeyInclusive = 3

• optional bool endKeyInclusive = 4

• optional int32 maxReturned = 5

  The maximum number of keys returned

• optional bool reverse = 6

  The keys are searched for and returned in a reverse order. For instance if the search is startKey="j", endKey="k", maxReturned=2, reverse=true and the keys "k0", "k1", "k2" exist the system will return "k2" and "k1" in that order.

• repeated bytes keys = 8

  get range response .

These are persistent options that are retained across power fail and erased on either PIN erase or PIN secure erase.

Used in: Body

• repeated Security.ACL acl = 2

  one per identity

• optional bytes oldLockPIN = 3

  Set the lock and erase pins.

• optional bytes newLockPIN = 4

• optional bytes oldErasePIN = 5

• optional bytes newErasePIN = 6

Used in: Security

• optional int64 identity = 1

• optional bytes key = 2

  the HMAC key

• optional ACL.HMACAlgorithm hmacAlgorithm = 3

• repeated ACL.Scope scope = 4

  value that must be in the key for read, write, range requests. If none are specified then no checking occurs. If one or more is specified, one must match or the request is rejected

• optional Priority maxPriority = 5

  The maxPriority is checked against the header priority and range priority (if present) fields. The priority must be greater than or equal to this maxPriority field.

Used in: ACL

• INVALID_HMAC_ALGORITHM = -1

  Must come first

• HmacSHA1 = 1

  0 is reserved; do not use

  this is the default

Used in: Scope

• INVALID_PERMISSION = -1

  place holder for backward .proto file compatibility

• READ = 0

  can read key/values

• WRITE = 1

  can write key/values

• DELETE = 2

• RANGE = 3

  can do a range

• SETUP = 4

  can set up and a device

• P2POP = 5

  can do a peer to peer operation

• GETLOG = 7

  can get log

• SECURITY = 8

  can set up the security roles of the device

Used in: ACL

• optional int64 offset = 1

• optional bytes value = 2

• repeated Permission permission = 3

  one per role

• optional bool TlsRequired = 4

  This is only allowed over the the TLS connection

if any or all of these are fields are included, they are set. These are persistent options that are retained across power fail and erased on either PIN erase or PIN secure erase.

Used in: Body

• optional int64 newClusterVersion = 1

  The cluster version to be checked. The default if never set is 0. If this is missing, it is assumed to be unchanged; This is persistent between boots of the device.

• optional bool firmwareDownload = 5

  indicates the presence of a firmware load in the data portion of this message. The firmware is itself protected on its own for integrity, authenticity, etc.

operation status

Used in: Command, P2POperation.Operation

• optional Status.StatusCode code = 1

  status code

• optional string statusMessage = 2

  status message

• optional bytes detailedMessage = 3

  optional information comes with status

enum of status code

Used in: Status

• INVALID_STATUS_CODE = -1

  Must come first, so default is invalid

• NOT_ATTEMPTED = 0

  for a P2P operation, there was a reason the list was incomplete. This is for items that were not attempted.

• SUCCESS = 1

• HMAC_FAILURE = 2

• NOT_AUTHORIZED = 3

• VERSION_FAILURE = 4

• INTERNAL_ERROR = 5

• HEADER_REQUIRED = 6

• NOT_FOUND = 7

• VERSION_MISMATCH = 8

• SERVICE_BUSY = 9

  If there are too many requests in the device at this time, requests will be rejected with this error message. The common response is to wait and retry the operation with an exponential back-off.

• EXPIRED = 10

  A long operation was started and a timeout happened mid operation. This does not imply a failure.

• DATA_ERROR = 11

  A data error happened and either earlyExit was set or the timeout happened.

• PERM_DATA_ERROR = 12

  A data error happened and all possible error recovery operations have been performed. There is no value to trying this again. If the system has the ability to determine the correct information, writing the data again can get rid

• REMOTE_CONNECTION_ERROR = 13

  A TCP connection to the remote peer failed. This is only for the P2P Operation

• NO_SPACE = 14

  When the device is full, it returns this error. The background scrubbing may free space, so this error may go away

• NO_SUCH_HMAC_ALGORITHM = 15

  In the set security, an HmacAlgorithm was specified as Unknown or there is a protocol version mis-match

• INVALID_REQUEST = 16

  The request is not valid. Subsequent attempts with the same request will return the same code. Examples: GET does not specify keyValue message, GETKEYRANGE operation does not specify startKey, etc

• NESTED_OPERATION_ERRORS = 17

  For P2P Requests, the operation was executed successfully but some nested operations did not succeed. This indicates that callers should review the status of nested operations. This status should only be used in the Command > Status, not in the Status messages of nested P2POperations

• DEVICE_LOCKED = 18

  If the device is currently locked and can not validate the hmac. This is returned as an status and the connection is terminated.

• DEVICE_ALREADY_UNLOCKED = 19

  The device was already unlocked. The validity of the pin was NOT checked. The connection remains open.

• CONNECTION_TERMINATED = 20

  The connection is being terminated. Details as to why are in the message string.

• INVALID_BATCH = 21

  During a batch operation, the only operations allowed are put " and delete. This error is put against the offending command and " the rest of the commands and the END_BATCH return NOT_ATTEMPTED."

Used in: KeyValue

• INVALID_SYNCHRONIZATION = -1

  Must come first, so default is invalid

• WRITETHROUGH = 1

• WRITEBACK = 2

• FLUSH = 3

* kinetic extended message. This is currently used by extended transport and for evaluation only.

• optional Message interfaceMessage = 1

  drive interface message

• optional bytes value = 2

  optional value

this is a local message to allow the program to read the protocol version number by building this message and then reading the value.

• optional string protocolVersion = 1

THe message is an authorization and command bytes.

Used in: ExtendedMessage

• optional Message.AuthType authType = 4

  Every message must be one of the following types.

• optional Message.HMACauth hmacAuth = 5

  Normal messages

• optional Message.PINauth pinAuth = 6

  for Pin based operations. These include device unlock and device erase

• optional bytes commandBytes = 7

  the embedded message providing the request (for HMACauth) and the response (for all auth types).

The Message Type determines how the the message is to be processed.

Used in: Message

• INVALID_AUTH_TYPE = -1

  if the message type is unknown, close the connection

• HMACAUTH = 1

  This is for normal traffic. Check the HMAC of the command and if correct, process the command.

• PINAUTH = 2

  device unlock and ISE command. These must come over the TLS connection. If they do not, close the connection. If it is over the TLS connection, execute the pin operation.

• UNSOLICITEDSTATUS = 3

  In the event that the device is going to close the connection, an unsolicited status will be returned first.

This is for normal message to the device and for responses. These are allowed once the device is unlocked. The HMAC provides for authenticity, Integrity and to enforce roles.

Used in: Message

• optional int64 identity = 1

  The "identity" identifies the requester and the key and algorithm to be used for hmac.

• optional bytes hmac = 2

Pin based authentication for Pin operations.

Used in: Message

• optional bytes pin = 1

  The pin necessary to make the operations valid

* persisted entry value message format. <p> db persisted entry (KVValue)

• optional Versioned.Metadata metadata = 1

  metadata

• optional bytes value = 2

  entry value/data

key/value entry op metadata

Used in: Versioned

• optional bytes key = 1

  entry key

• optional bytes dbVersion = 2

  entry version in store

• optional bytes tag = 3

  this is the integrity value of the data. This may or may not be in the clear, depending on the algorithm used.

• optional Command.Algorithm algorithm = 4

  The following is for the protection of the data. If the data is protected with a hash or CRC, then the algorithm will be negative. If the data protection algorithm is not a standard unkeyed algorithm then a positive number is used and the drive has no idea what the key is. See the discussion of encrypted key/value store.(See security document).