major protocol change to fix HMAC bug and enable device lock/unlock and

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

 *

 */ package com.seagate.kinetic.proto;

 */

option java_outer_classname = "Kinetic"; /**

 * Update summary:

 *

 * 1. Message is divided into the following logical sections.

 *

 * 1.1 Header.

 * 1.2 Body.

 * 1.3 Status.

 * 1.4 value.

 * 1.5 HMAC.

 *

 */ message Message {

//

package com.seagate.kinetic.proto;

option java_outer_classname = "Kinetic";

// THe message is an authorization and command bytes.

message Message {

// 1-3 are reserved, do not use

// Every message must be one of the following types.

	optional AuthType authType = 4;

	// Normal messages

	optional HMACauth hmacAuth = 5;

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

	// device erase

	optional PINauth pinAuth = 6;

	// the embedded message providing the request (for HMACauth) and

	// the response (for all auth types).

	optional bytes commandBytes = 7;

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

	enum AuthType {

// The command contains the header, body and status as a single

// unit that will be used to calculate the HMAC.

	optional Command command = 1;

	// if the message type is unknown, close the connection

		INVALID_AUTH_TYPE = -1;

	// 2 is reserved, do not use

		// This is for normal traffic. Check the HMAC of the command and

		// if correct, process the command.

		HMACAUTH = 1;

		// 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.

		PINAUTH = 2;

		// In the event that the device is going to close the connection, an

		// unsolicited status will be returned first.

		UNSOLICITEDSTATUS = 3;

	}

	// 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.

	message HMACauth {

	// The "identity" identifies the requester and the key and algorithm to

	// be used for hmac.

		optional int64 identity = 1;

		optional bytes hmac = 2;

	}

	// Pin Auth is 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. The request ignores the value in commandBytes. The

	// response will return this pinAuth and will have a status in

	// the commandBytes.

	message PINauth {

	// The operation

		optional PinOp pinOp = 1;

		// The pin necessary to make the operations valid

		optional bytes pin = 2;

		enum PinOp {

			INVALID_PINOP = -1;

			// The pin will unlock the device

			UNLOCK_PINOP = 1;

			// 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.

			LOCK_PINOP = 2;

			// Erase the device. This may be secure

			// or not. The implication is that it may be faster

			// than the secure operation.

			ERASE_PINOP = 3;

			// Erase the device in a way that will

			// physical access and disassembly of the device

			// will not

			SECURE_ERASE_PINOP = 3;

			// Both erase operations will return

			// the device to an as manufactured state removing all

			// user data and configuration settings.

		}

	}

	//HMAC

	optional bytes hmac = 3;

	message Command {

	//message header

		optional Header header = 1;

		//operation status

		optional Status status = 3;

	}

		//message header

		message Header {

		// "cluster" is the version 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 vesioning to ignore this field in the header and in the setup.)

		// using cluster versioning to ignore this field in the header and in the setup.)

			optional int64 clusterVersion = 1;

			// The hmac of the request provides the authentication and (indirectly) the authority of the identity.

			optional int64 identity = 2;

			// A unique number for this connection between the source and target. On the first request

		// to the drive, this should be the time of day in seconds since 1970. The drive can change this

			// 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 connectionID = 3;

			optional int64 timeout = 9;

			// 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 drive exhaust all possible error recovery, leave

			// 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 drive, the maximum error recovery time could be seconds.

			// 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 bool earlyExit = 10;

			//set up security

			optional Security security = 7;

			// Defined long running commands that are device dependent and

			// typically background operations.

			optional BackgroundOperation backgroundOperation = 5;

		}

		//operation status

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

				REMOTE_CONNECTION_ERROR = 13;

			// When the drive is full, it returns this error. The background scrubbing may free space,

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

				// so this error may go away

				NO_SPACE = 14;

				// This status should only be used in the Command > Status, not in the Status messages

				// of nested P2POperations

				NESTED_OPERATION_ERRORS = 17;

				// If the device is currently locked and can not validate

				// the hmac. This is returned as an status

				// and the connection is terminated.

				DEVICE_LOCKED = 18;

				// The device was already unlocked. The validity of the

				// pin was NOT checked. The connection remains open.

				DEVICE_ALREADY_UNLOCKED = 19;

				// The connection is being terminated. Details as to why are

				// in the message string.

				CONNECTION_TERMINATED = 20;

			}

		}

			// 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

			// 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 Algorithm algorithm = 6;

			// 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 drive chooses, or when a subsequent FLUSH is give to the drive.

			// 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.

		}

		//set up operation.

		// 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.

		message Setup {

		// 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 drive.

		// This is persistent between boots of the device.

			optional int64 newClusterVersion = 1;

		// setting this empties the entire database. If supported will also change

		// keys such that the data is destroyed even if the platters are removed and

		// put into a spin stand, the data is not recoverable.

		optional bool instantSecureErase = 2;

		// if set with instantSecureErase, this sets the Pin. If with pin, this changes the pin.

		optional bytes setPin = 3;

		// If the pin is set, then the pin needs to be set whenever the drive is

		// booted or powered up. Any drive getting a command, and the pin has not

		// been set, will be rejected.

		optional bytes pin = 4;

			// 2, 3, 4 are reserved.

			// 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.

			optional bool firmwareDownload = 5;

			// sets the erase pin for the pin authorized erase commands.

			// 0 length or null pin is NOT allowed and an error returned.

			optional bytes newErasePin = 6;

			// Sets the lock unlock pin. When enabled the device has the

			// ability to be securely locked. Entering or changing the lock

			// unlock pin does not erase the device.

			optional bytes newLockPin = 7;

		}

	// P2P operations allow drives to be able to send keys to other drives.

		// 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.

		message P2POperation {

				optional string name = 1;

				// A number between 0.00 and 1.00. The resolution of this number is up to the

			// drive. 1 means 100% utilized.

				// device. 1 means 100% utilized.

				optional float value = 2;

			}

				// Device world wide name (WWN)

				optional bytes worldWideName = 14;

			// This is the vendor specific version of the software on the drive in dot notation

				// 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 version = 8;

				optional string compilationDate = 12;

				optional string sourceHash = 13;

			// This is the version of the protocol (.proto file) that the drive uses.

				// 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 protocolVersion = 15;

				// these are the port numbers for the software

				optional int32 port = 10;

				optional int32 tlsPort = 11;

				optional bool Locking = 18;

				optional bool SecureErase = 19;

				message Interface {

					optional string name = 1;

					optional bytes MAC = 2;

			}

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

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

			message Statistics {

				optional MessageType messageType = 1;

				// 2 and 3 are reserved, do not use

				optional uint64 count = 4;

				// 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

			// drives

				// devices

				optional uint64 bytes = 5;

			}

		}

		// These are persistent options that are retained across power fail and

		// erased on either PIN erase or PIN secure erase.

		message Security {

			repeated ACL acl = 2; // one per identity

			message ACL {

		}

		// These are long running background operations. The value of the

		// system controlling background operations is that the system

		// can make sure that during high performance periods that

		// background operations are not being performed.

		message BackgroundOperation {

		// Determine the operation type

			optional BackOpType backOpType = 1;

			// The range on the request and results on the response

			optional Range range = 2;

			enum BackOpType {

				INVALID_BACKOP = 0;

				// 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 = 1;

				// This performes optomizations of the media. Things like

				// defragmentation, compaction, garbage collection, compression

				// could be things accomplished using the media optimize command.

				MEDIAOPTIMIZE = 2;

			}

		}

		enum Priority {

			NORMAL = 5;

			LOWEST = 1;

			NOOP_RESPONSE = 29;

			FLUSHALLDATA = 32;

			FLUSHALLDATA_RESPONSE = 31;

			BACKOP = 32;

			BACKOP_RESPONSE = 31;

		}

	}

}

 No newline at end of file