| // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| syntax = "proto2"; |
| |
| option optimize_for = LITE_RUNTIME; |
| |
| package enterprise_management; |
| |
| // Request from device to server to register device. |
| message DeviceRegisterRequest { |
| // Reregister device without erasing server state. It can be used |
| // to refresh dmtoken etc. Client MUST set this value to true if it |
| // reuses an existing device id. |
| optional bool reregister = 1; |
| |
| // Device register type. This field does not exist for TT release. |
| // When a client requests for policies, server should verify the |
| // client has been registered properly. For example, a client must |
| // register with type DEVICE in order to retrieve device policies. |
| enum Type { |
| TT = 0; // Register for TT release. |
| USER = 1; // Register for user polices. |
| DEVICE = 2; // Register for device policies. |
| } |
| // NOTE: we also use this field to detect client version. If this |
| // field is missing, then the request comes from TT. We will remove |
| // Chrome OS TT support once it is over. |
| optional Type type = 2 [default = TT]; |
| |
| // Machine hardware id, such as serial number. |
| // This field is required if register type == DEVICE. |
| optional string machine_id = 3; |
| |
| // Machine model name, such as "ZGA", "Cr-48", "Nexus One". If the |
| // model name is not available, client SHOULD send generic name like |
| // "Android", or "Chrome OS". |
| optional string machine_model = 4; |
| |
| // When true, indicates that the |machine_id| field should be known to the |
| // server. The server can do additional checks based on this information. |
| // This is currently used for requests triggered by auto-enrollment. |
| // Defaults to false when not present. |
| optional bool known_machine_id = 5; |
| } |
| |
| // Response from server to device register request. |
| message DeviceRegisterResponse { |
| // Device management token for this registration. This token MUST be |
| // part of HTTP Authorization header for all future requests from |
| // device to server. |
| required string device_management_token = 1; |
| |
| // Device display name. By default, server generates the name in |
| // the format of "Machine Model - Machine Id". However, domain |
| // admin can update it using CPanel, so do NOT treat it as constant. |
| optional string machine_name = 2; |
| } |
| |
| // Request from device to server to unregister device. |
| // GoogleDMToken MUST be in HTTP Authorization header. |
| message DeviceUnregisterRequest { |
| } |
| |
| // Response from server to device for unregister request. |
| message DeviceUnregisterResponse { |
| } |
| |
| // Request for a setting or with optional watermark on client side. |
| // TODO(gfeher): remove this after Chrome OS TT is over. |
| message DevicePolicySettingRequest { |
| // setting key |
| required string key = 1; |
| // watermark last read from server if available. |
| optional string watermark = 2; |
| } |
| |
| message PolicyFetchRequest { |
| // This is the policy type, which maps to D3 policy type internally. |
| // By convention, we use "/" as separator to create policy namespace. |
| // The policy type names are case insensitive. |
| // |
| // Possible values for Chrome OS are: |
| // google/chromeos/device => ChromeDeviceSettingsProto |
| // google/chromeos/user => ChromeSettingsProto |
| // google/chromeos/unregistered_user => ChromeInitialSettingsProto (unused) |
| optional string policy_type = 1; |
| |
| // This is the last policy timestamp that client received from server. |
| optional int64 timestamp = 2; |
| |
| // Tell server what kind of security signature is required. |
| enum SignatureType { |
| NONE = 0; |
| SHA1_RSA = 1; |
| } |
| optional SignatureType signature_type = 3 [default = NONE]; |
| |
| // The version number of the public key that is currently stored |
| // on the client. This should be the last number the server had |
| // supplied as new_public_key_version in PolicyData. |
| // This field is unspecified if the client does not yet have a |
| // public key. |
| optional int32 public_key_version = 4; |
| |
| // Machine hardware id, such as serial number. |
| // This field is should be set only if the serial number for the device is |
| // missing from the server, as indicated by the valid_serial_number_missing |
| // field in the last policy fetch response. |
| optional string machine_id = 5; |
| } |
| |
| // This message is included in serialized form in PolicyFetchResponse |
| // below. It may also be signed, with the signature being created for |
| // the serialized form. |
| message PolicyData { |
| // See PolicyFetchRequest.policy_type. |
| optional string policy_type = 1; |
| |
| // [timestamp] is milliseconds since Epoch in UTC timezone. It is |
| // included here so that the time at which the server issued this |
| // response cannot be faked (as protection against replay attacks). |
| // It is the timestamp generated by DMServer, NOT the time admin |
| // last updated the policy or anything like that. |
| optional int64 timestamp = 2; |
| |
| // The DM token that was used by the client in the HTTP POST header |
| // for authenticating the request. It is included here again so that |
| // the client can verify that the response is meant for him (and not |
| // issued by a replay or man-in-the-middle attack). |
| optional string request_token = 3; |
| |
| // The serialized value of the actual policy protobuf. This can be |
| // deserialized to an instance of, for example, ChromeSettingsProto |
| // or ChromeDeviceSettingsProto. |
| optional bytes policy_value = 4; |
| |
| // The device display name assigned by the server. It is only |
| // filled if the display name is available. |
| // |
| // The display name of the machine as generated by the server or set |
| // by the Administrator in the CPanel GUI. This is the same thing as |
| // |machine_name| in DeviceRegisterResponse but it might have |
| // changed since then. |
| optional string machine_name = 5; |
| |
| // Version number of the server's current public key. (The key that |
| // was used to sign this response. Numbering should start at 1 and be |
| // increased by 1 at each key rotation.) |
| optional int32 public_key_version = 6; |
| |
| // The user this policy is intended for. In case of device policy, the name |
| // of the owner (who registered the device). |
| optional string username = 7; |
| |
| // In this field the DMServer should echo back the "deviceid" HTTP parameter |
| // from the request. |
| optional string device_id = 8; |
| |
| // Indicates which state this association with DMServer is in. This can be |
| // used to tell the client that it is not receiving policy even though the |
| // registration with the server is kept active. |
| enum AssociationState { |
| // Association is active and policy is pushed. |
| ACTIVE = 0; |
| // Association is alive, but the corresponding domain is not managed. |
| UNMANAGED = 1; |
| } |
| optional AssociationState state = 9 [default = ACTIVE]; |
| |
| // Indicates if the the server cannot find a valid serial number for the |
| // device. If this flag is set, the device should send the valid serial |
| // number with a device policy fetch request. Note that this only |
| // applies to device policy. |
| optional bool valid_serial_number_missing = 10; |
| } |
| |
| message PolicyFetchResponse { |
| // Since a single policy request may ask for multiple policies, we |
| // provide separate error code for each individual policy fetch. |
| |
| // We will use standard HTTP Status Code as error code. |
| optional int32 error_code = 1; |
| |
| // Human readable error message for customer support purpose. |
| optional string error_message = 2; |
| |
| // This is a serialized |PolicyData| protobuf (defined above). |
| optional bytes policy_data = 3; |
| |
| // Signature of the policy data above. |
| optional bytes policy_data_signature = 4; |
| |
| // If the public key has been rotated on the server, the new public |
| // key is sent here. It is already used for |policy_data_signature| |
| // above, whereas |new_public_key_signature| is created using the |
| // old key (so the client can trust the new key). If this is the |
| // first time when the client requests policies (so it doesn't have |
| // on old public key), then |new_public_key_signature| is empty. |
| optional bytes new_public_key = 5; |
| optional bytes new_public_key_signature = 6; |
| } |
| |
| // Request from device to server for reading policies. |
| message DevicePolicyRequest { |
| // identify request scope: CrOS settings or other type of settings. |
| // TODO(gfeher): remove this after Chrome OS TT is over. |
| optional string policy_scope = 1; |
| // identify key to the settings: proxy etc. |
| // TODO(gfeher): remove this after Chrome OS TT is over. |
| repeated DevicePolicySettingRequest setting_request = 2; |
| |
| // The policy fetch request. If this field exists, the request must |
| // comes from a non-TT client. The repeated field allows client to |
| // request multiple policies for better performance. |
| repeated PolicyFetchRequest request = 3; |
| } |
| |
| // Response from server to device for reading policies. |
| message DevicePolicyResponse { |
| // The policy fetch response. |
| repeated PolicyFetchResponse response = 3; |
| } |
| |
| message TimePeriod { |
| // [timestamp] is milli seconds since Epoch in UTC timezone. |
| optional int64 start_timestamp = 1; |
| optional int64 end_timestamp = 2; |
| } |
| |
| // This captures launch events for one app/extension or other installments. |
| message InstallableLaunch { |
| optional string install_id = 1; |
| |
| // Time duration where this report covers. These are required |
| // and the record will be ignored if not set. |
| optional TimePeriod duration = 2; |
| |
| // Client will send at most 50 timestamps to DM. All the rest |
| // launch activities will be summed into the total count. |
| // We will distribute the count evenly among the time span when |
| // doing time based aggregation. |
| repeated int64 timestamp = 3; |
| optional int64 total_count = 4; |
| } |
| |
| // Report device level status. |
| message DeviceStatusReportRequest { |
| optional string os_version = 1; |
| optional string firmware_version = 2; |
| |
| // "Validated", "Dev". Same as verified mode. |
| // If the mode is unknown, this field should not be set. |
| optional string boot_mode = 3; |
| |
| // Device active times collection since last report rpc call. |
| repeated TimePeriod active_time = 4; |
| |
| // The browser version string as shown in the About dialog. |
| optional string browser_version = 5; |
| } |
| |
| // Report session (a user on one device) level status. |
| message SessionStatusReportRequest { |
| // Installed apps for this user on this device. |
| repeated string installed_app_id = 1; |
| |
| // Installed extensions for this user on this device. |
| repeated string installed_extension_id = 2; |
| |
| // One stat per app for top 30 apps. |
| repeated InstallableLaunch app_launch_stat = 3; |
| } |
| |
| // Response from DMServer to update devices' status. |
| // It is possible that status report fails but policy request succeed. In such |
| // case, the DeviceStatusReportResponse will contain an error code and the |
| // device should re-send status report data in the next policy request. The |
| // device should re-send report data if policy request fails, even if |
| // DeviceStatusReportResponse contains no error code. |
| message DeviceStatusReportResponse { |
| optional int32 error_code = 1; |
| |
| // Human readable error message for customer support purpose. |
| optional string error_message = 2; |
| } |
| |
| // Response from DMServer to update user devices' status. |
| // It is possible that status report fails but policy request succeed. In such |
| // case, the SessionStatusReportResponse will contain an error code and the |
| // device should re-send status report data in the next policy request. The |
| // device should re-send report data if policy request fails, even if |
| // SessionStatusReportResponse contains no error code. |
| message SessionStatusReportResponse { |
| optional int32 error_code = 1; |
| |
| // Human readable error message for customer support purpose. |
| optional string error_message = 2; |
| } |
| |
| // Request from device to server to determine whether the device should |
| // go through enterprise enrollment. Unlike the other requests, this request is |
| // not authenticated. |
| message DeviceAutoEnrollmentRequest { |
| // SHA-256 hash of the device's serial number, mod |modulus|. |
| // Should always be present. |
| optional int64 remainder = 1; |
| |
| // Modulus of the hash used by the client. Should always be present. This |
| // is the number of buckets the client thinks the server has. For now, |
| // it is a power of 2, but due to the strict constraint on how many serial |
| // numbers a bucket can contain, it may become non power of 2. If that |
| // happens, client-side needs to change its assumption. |
| optional int64 modulus = 2; |
| } |
| |
| // Response from server to auto-enrollment detection request. |
| message DeviceAutoEnrollmentResponse { |
| // If this field is present, the other fields are ignored and the client |
| // should send a new DeviceAutoEnrollmentRequest with a new |remainder| |
| // computed using this new |modulus|. If this field is empty, the client's |
| // request was accepted. |
| // DMServer guarantees that if the modulus sent by client in |
| // DeviceAutoEnrollmentRequest matches server's expectation, this field |
| // is unset. |
| optional int64 expected_modulus = 1; |
| |
| // List of hashes in the client's hash bucket. If the client's hash matches |
| // any in this list, the client device should do enterprise enrollment. |
| // If it matches none, enrollment should be optional. |
| // Each entry has exactly 256 bits (32 bytes). |
| repeated bytes hash = 2; |
| } |
| |
| // Request from the DMAgent on the device to the DMServer. This is |
| // container for all requests from device to server. The overall HTTP |
| // request MUST be in the following format: |
| // |
| // * HTTP method is POST |
| // * Data mime type is application/x-protobuffer |
| // * HTTP parameters are (all required, all case sensitive): |
| // * request: MUST BE one of |
| // * register |
| // * unregister |
| // * policy |
| // * ping |
| // * status |
| // * enterprise_check |
| // |
| // * devicetype: MUST BE "1" for Android or "2" for Chrome OS. |
| // * apptype: MUST BE Android or Chrome. |
| // * deviceid: MUST BE no more than 64-char in [\x21-\x7E]. |
| // * agent: MUST BE no more than 64-char long. |
| // * HTTP Authorization header MUST be in the following formats: |
| // * For register and ping requests, using Gaia authentication: |
| // Authorization: GoogleLogin auth=<auth cookie for Mobile Sync> |
| // |
| // * For unregister, policy and status requests: |
| // Authorization: GoogleDMToken token=<dm token from register> |
| // |
| // * The Authorization header isn't used for enterprise_check requests, nor |
| // for register requests using OAuth. In the latter case, the OAuth token is |
| // passed in the "oauth" parameter. |
| // |
| // DeviceManagementRequest should only contain one request which matches the |
| // HTTP query parameter - request, as listed below. Other requests within the |
| // container will be ignored. |
| // ping: policy_request |
| // register: register_request |
| // unregister: unregister_request |
| // policy: policy_request |
| // status: status_report_request |
| // |
| // |
| message DeviceManagementRequest { |
| // Register request. |
| optional DeviceRegisterRequest register_request = 1; |
| |
| // Unregister request. |
| optional DeviceUnregisterRequest unregister_request = 2; |
| |
| // Policy request. |
| optional DevicePolicyRequest policy_request = 3; |
| |
| // Update status. |
| optional DeviceStatusReportRequest device_status_report_request = 4; |
| optional SessionStatusReportRequest session_status_report_request = 5; |
| |
| // Auto-enrollment detection. |
| optional DeviceAutoEnrollmentRequest auto_enrollment_request = 6; |
| } |
| |
| // Response from server to device. |
| // |
| // The server uses the following numbers as HTTP status codes |
| // to report top-level errors. |
| // |
| // 200 OK: valid response is returned to client. |
| // 400 Bad Request: invalid argument. |
| // 401 Unauthorized: invalid auth cookie or DM token. |
| // 403 Forbidden: device management is not allowed. |
| // 404 Not Found: the request URL is invalid. |
| // 410 Gone: device is unknown to the server. |
| // 491 Request Pending: the request is pending approval. |
| // 500 Internal Server Error: most likely a bug in DM server. |
| // 503 Service Unavailable: most likely a backend error. |
| // 901 Device Not Found: the device id is not found. |
| // 902 Policy Not Found: the policy is not found. |
| message DeviceManagementResponse { |
| // Error message. |
| optional string error_message = 2; |
| |
| // Register response |
| optional DeviceRegisterResponse register_response = 3; |
| |
| // Unregister response |
| optional DeviceUnregisterResponse unregister_response = 4; |
| |
| // Policy response. |
| optional DevicePolicyResponse policy_response = 5; |
| |
| // Device status report response. |
| optional DeviceStatusReportResponse device_status_report_response = 6; |
| |
| // Session status report response. |
| optional SessionStatusReportResponse session_status_report_response = 7; |
| |
| // Auto-enrollment detection response. |
| optional DeviceAutoEnrollmentResponse auto_enrollment_response = 8; |
| } |