Add proto definitions for messages used by CryptAuth APIs and the authentication protocol.

components/proximity_auth/cryptauth/proto/cryptauth_api.proto

+// Definitions for CryptAuth API calls.
+// Generated from server definitions. Do not edit.

[Ilya Sherman, 2014/10/06 21:15:59]

nit: We should probably add a copyright stanza to the top of the file.

[Tim Song, 2014/10/07 00:06:07]

Done.

+syntax = "proto2";
+
+package cryptauth;
+option java_package = "com.google.api.services.cryptauth";

[Ilya Sherman, 2014/10/06 21:15:58]

nit: Do we want to keep this line in the Chromium repo?

[Tim Song, 2014/10/07 00:06:07]

Done.

+
+option optimize_for = LITE_RUNTIME;
+
+// Wait for the specified transaction to change state.
+message AwaitTxRequest {
+  // An opaque (random) identifier for this transaction.
+  optional bytes tx_id = 1;
+}
+
+// If the transaction has completed, a token will be returned encapsulating the
+// result of the transaction. The token is opaque, and can be decoded by using
+// the CompleteTx backend query.
+message AwaitTxResponse {
+  // An opaque token encoding the transaction result.
+  optional bytes tx_token = 1;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#awaitTxResponse"</code>.
+  optional string kind = 2;
+}
+
+// Device information provided to external clients that need to sync device
+// state.
+message ExternalDeviceInfo {
+  // A cryptographic public key associated with the device.
+  optional bytes public_key = 1;
+
+  // A user friendly (human readable) name for this device.
+  optional string friendly_device_name = 2;
+
+  // If available, the device's bluetooth MAC address
+  optional string bluetooth_address = 3;
+
+  // Whether or not this device can be used as an unlock key
+  optional bool unlock_key = 4;
+
+  // Whether or not this device can be unlocked
+  optional bool unlockable = 5;
+}
+
+// Request for a list of devices that could be used as Unlock Keys, optionally
+// requesting a callback over bluetooth (for proximity detection).
+message FindEligibleUnlockDevicesRequest {
+  // A bluetooth MAC address to be contacted if a device that may be eligible
+  // for unlock is nearby. If set, a message will be pushed to all eligible
+  // unlock devices requesting that they contact the specified MAC address. If
+  // this field is left unset, no callback will be made, and no message will be
+  // pushed to the user's devices.
+  optional string callback_bluetooth_address = 2;

[Ilya Sherman, 2014/10/06 21:15:59]

Is it intentional that the field with tag "1" is omitted?  There are a few other
fields omitted in the rest of this file as well.  Is this because they've been
deprecated on the server side?

[Tim Song, 2014/10/07 00:06:07]

Yes, it's intentional. There are fields used only on the server along with
deprecated fields. The client doesn't need to know about them.

+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#findEligibleUnlockDevicesRequest"</code>.

[Ilya Sherman, 2014/10/06 21:15:58]

Hmm, why do we have this field at all, if it has a fixed value?

[Tim Song, 2014/10/07 00:06:07]

This value is used if you just have a serialized blob and need to determine the
type of the message. I talked to Denis, and he'll remove this on the
server-side. For now, we need this here as the all responses from the prod
server contain this field.

+  optional string kind = 3;
+}
+
+// Response containing a list of devices that could be made Unlock Keys
+message FindEligibleUnlockDevicesResponse {
+  // Devices that could be made Unlock Keys (even if they aren't enabled yet)
+  repeated ExternalDeviceInfo eligible_devices = 1;
+
+  // Devices that cannot be made unlock keys, and reasons for this. This list
+  // will not contain any non-gms core devices, even though these are also not
+  // eligible to be unlock keys.
+  repeated IneligibleDevice ineligible_devices = 2;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#findEligibleUnlockDevicesResponse"</code>.
+  optional string kind = 3;
+}
+
+// Request to complete a device enrollment.
+message FinishEnrollmentRequest {
+  // The enrollment session identifer from the <code>setup</code> response.
+  optional bytes enrollment_session_id = 2;
+
+  // An encrypted payload containing enrollment information for the device.
+  optional bytes enrollment_message = 3;
+
+  // A Diffie-Hellman public key for the device, to complete the key exchange.
+  optional bytes device_ephemeral_key = 4;
+}
+
+// Response indicating whether a device enrollment completed successfully.
+message FinishEnrollmentResponse {
+  // Status should be OK if the request was successful.
+  optional string status = 1;
+
+  // A detailed error message if there was a failure.
+  optional string error_message = 2;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#finishEnrollmentResponse"</code>.
+  optional string kind = 5;
+}
+
+// Used to request devices that have a specific feature.
+message GetDevicesForFeatureRequest {
+  // Requests those devices that support the specified DeviceFeature
+  optional string device_feature = 2;

[Ilya Sherman, 2014/10/06 21:15:58]

Is there a list of valid features?  (Seems like this ought to be an enum field
rather than a field string...)

[Tim Song, 2014/10/07 00:06:07]

I'm not sure why the generator turns enums into strings. It might be a bit of
work to change this.

+}
+
+// Devices that have a certain feature, as returned by the GetDevicesForFeature
+// RPC.
+message GetDevicesForFeatureResponse {
+  // A (possibly empty) list of devices supporting the requested featur

[Ilya Sherman, 2014/10/06 21:15:59]

nit: "featur" -> "feature"

[Tim Song, 2014/10/07 00:06:07]

Done. I'll also change this on the server-side so it won't get wiped the next
time we update.

+  repeated ExternalDeviceInfo result_sets = 1;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#getDevicesForFeatureResponse"</code>.
+  optional string kind = 2;
+}
+
+// This request is sent by the login page to obtain one challenge session for

[Ilya Sherman, 2014/10/06 21:15:58]

What is the "login page"?  The ChromeOS sign-in screen?

[Tim Song, 2014/10/07 00:06:06]

I think this refers to the GAIA login page.

[Ilya Sherman, 2014/10/07 01:09:08]

Hmm, do we show a GAIA login page as part of EasyUnlock?  If not, why do we need
this message type?

[Tim Song, 2014/10/07 17:05:42]

We don't use this in Easy Unlock, but it might be useful for bootstrap.

[Ilya Sherman, 2014/10/07 20:46:41]

Hmm.  My preference would be to not include messages that we don't use in Easy
Unlock/Sign-in, since we can always add them if they become useful.

[Tim Song, 2014/10/14 00:30:24]

Okay I removed the unused APIs.

+// each of the user's devices. Challenges can be signed by the user's device as
+// part of a login assertion.
+message GetLoginChallengesRequest {
+  // Protocol type to be used with the requested login challenges.
+  optional string protocol_type = 3;
+
+  // Used to request a login challenge for a particular device, specified by its
+  // public key
+  optional bytes user_public_key = 5;
+}
+
+// Response encapsulating a list of login challenges (together with their
+// metadata).
+message GetLoginChallengesResponse {
+  // List of login challenges (with associated metadata)
+  repeated LoginChallengeInfo login_challenge_infos = 3;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#getLoginChallengesResponse"</code>.
+  optional string kind = 4;
+}
+
+// Request for a listing of a user's own devices
+message GetMyDevicesRequest {
+  // Return only devices that can act as EasyUnlock keys.
+  optional bool approved_for_unlock_required = 2;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#getMyDevicesRequest"</code>.
+  optional string kind = 3;
+}
+
+// Response containing a listing of the users device's
+message GetMyDevicesResponse {
+  // A listing of all sync-able devices
+  repeated ExternalDeviceInfo devices = 1;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#getMyDevicesResponse"</code>.
+  optional string kind = 2;
+}
+
+// A device that the server thinks is not eligible to be an unlock key, and the
+// reason for this.
+message IneligibleDevice {
+  // The device that is not eligible to be an unlock key.
+  optional ExternalDeviceInfo device = 1;
+
+  // The reasons why the server thinks it is not an unlock key. NOTE: for now,
+  // this list of reasons will contain exactly one element. It is a repeated
+  // field because, in principle, there can be more than one reason that makes a
+  // device not eligible to be an unlock key, and we want to be able to add
+  // multiple reasons in the future.
+  repeated string reasons = 2;
+}
+
+// A login challenge together with its metadata
+message LoginChallengeInfo {
+  // Protocol type to be used with this login challenge
+  optional string type = 1;
+
+  // Challenge to be signed by the device
+  optional bytes challenge = 2;
+
+  // Key handle that the device registered with
+  optional bytes key_handle = 3;
+
+  // Used to identify this challenge to the server
+  optional bytes challenge_session_id = 7;
+
+  // Application id for which the device key is supposed to work
+  optional string application_id = 8;
+}
+
+// Encapsulates a transaction reply, sent from the user's device. The details of
+// the transaction and the reply are encrypted.
+message ReplyTxRequest {
+  // Encrypted transaction ledger, containing the original prompt request and
+  // the user's response.
+  optional bytes secure_tx_ledger = 1;
+}
+
+// Requests to send a "tickle" requesting to sync all of a user's devices now
+message SendDeviceSyncTickleRequest {
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#sendDeviceSyncTickleRequest"</code>.
+  optional string kind = 2;
+}
+
+// Contains information needed to begin a device enrollment.
+message SetupEnrollmentInfo {
+  // Type of protocol this setup information was requested for
+  optional string type = 1;
+
+  // A session identifier to be used for this enrollment session.
+  optional bytes enrollment_session_id = 2;
+
+  // A Diffie-Hellman public key used perform a key exchange during enrollment.

[Ilya Sherman, 2014/10/06 21:15:59]

nit: "used perform" -> "used to perform"

[Tim Song, 2014/10/07 00:06:07]

Done.

+  optional bytes server_ephemeral_key = 3;
+}
+
+// Requests information needed to begin a device enrollment.
+message SetupEnrollmentRequest {
+  // Deprecated. See <code>application_id</code>
+  optional string origin = 2;

[Ilya Sherman, 2014/10/06 21:15:59]

nit: Can this field be annotated as "[deprecated=true]"?

[Tim Song, 2014/10/07 00:06:07]

I think this is a "soft" deprecation rather than a hard one, in that certain
clients still use it.

+
+  // Type(s) of protocol supported by this enrolling device (e.g. "gcmV1")
+  repeated string types = 3;
+
+  // Indicates whether a legacy crypto suite must be used with this device.

[Ilya Sherman, 2014/10/06 21:15:58]

Is there a specific legacy crypto suite that's being referred to?

[Tim Song, 2014/10/07 00:06:07]

No idea...

+  optional bool use_legacy_crypto = 4;
+
+  // A URL describing which application facets this enrollment can be used (see

[Ilya Sherman, 2014/10/06 21:15:58]

nit: I don't understand this sentence :/

[Tim Song, 2014/10/07 00:06:07]

This seems to be something in the early stages of development. We don't use it
for enrollment either.

+  // http://go/appid).

[Ilya Sherman, 2014/10/06 21:15:58]

nit: Can we point to a publicly-accessible URL?

[Tim Song, 2014/10/07 00:06:07]

I don't think this concept is fully implemented yet.

+  optional string application_id = 5;
+}
+
+// Contains information needed to begin a device enrollment.
+message SetupEnrollmentResponse {
+  // Should return OK if the request was well formed.
+  optional string status = 1;
+
+  // Information for each of the requested protocol <code>type</code>s.
+  repeated SetupEnrollmentInfo infos = 2;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#setupEnrollmentResponse"</code>.
+  optional string kind = 3;
+}
+
+// Encapsulates a sync request from the user's device, in encrypted form. This
+// is used to inform the server when the
+// user's device has received a transaction, as well as to provide additional

[Ilya Sherman, 2014/10/06 21:15:58]

nit: Odd choice of line-break.

[Tim Song, 2014/10/07 00:06:07]

Done. The generated code used a text-width of 100 chars (Java style guide). I'll
run a formatter to make it fit 80 chars properly.

+// client state information useful for updating device records, debugging, UI
+// indications, etc.
+message SyncTxRequest {
+  // Encrypted sync request, containing state of the user's device at the time
+  // the sync request was sent, as well as indicating whether a specific
+  // transaction is desired to be
+  // sync'd, or if a list of all pending transactions should be sent back in
+  // the response.
+  optional bytes secure_sync_request = 1;
+}
+message SyncTxResponse {
+  // Encrypted sync response, containing any additional transaction information
+  // requested by the device for a specific transaction, or a list of all
+  // currently pending transactions if none was specified in the request.
+  optional bytes secure_sync_response = 1;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#syncTxResponse"</code>.
+  optional string kind = 2;
+}
+
+// Used to enable or disable EasyUnlock features on a specified device, and also
+// causes other devices to sync the new EasyUnlock state.
+message ToggleEasyUnlockRequest {
+  // If true, Easyunlock will be enabled for the device with public key equal

[Ilya Sherman, 2014/10/06 21:15:59]

nit: "Easyunlock" -> "EasyUnlock"

[Tim Song, 2014/10/07 00:06:07]

Done.

+  // to public_key. Otherwise, it will be disabled for that device.
+  optional bool enable = 1;
+
+  // Encoded public key of the device to enable/disable (here you must use the
+  // same exact encoding that was sent during device enrollment).
+  optional bytes public_key = 2;
+
+  // If true, EasyUnlock enabled state will be set to the value of "enable" for
+  // all of a

[Ilya Sherman, 2014/10/06 21:15:58]

nit: Odd choice of line break.

[Tim Song, 2014/10/07 00:06:07]

Done.

+  // user's devices. This is the same as calling the toggle RPC for every
+  // device. However, this removes the need for calling GetMyDevices, so it
+  // reduces network overhead. If this field is set "public_key" must not be
+  // set.  NOTE: the case enable=true is not yet supported, so this option can
+  // only disable EasyUnlock for all devices.
+  optional bool apply_to_all = 3;
+
+  // Identifies what kind of resource this is. Value: the fixed string
+  // <code>"cryptauth#toggleEasyUnlockRequest"</code>.
+  optional string kind = 4;
+}