device_management_backend.proto

// Copyright (c) 2011 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;

// Meta-settings that control how a user receives regular settings
// (CloudPolicySettings) for Chrome. The name "Initial" indicates that
// these settings will be downloaded before Chrome starts requesting
// regular settings.
message ChromeInitialSettingsProto {
  enum EnrollmentProvision {
    // The users's device is not automatically enrolled for policies, but the
    // user may choose to try to enroll it.
    UNMANAGED = 0;
    // The user must enroll its device for policies.
    MANAGED = 1;
  }
  // Chrome will interpret this as UNMANAGED if unset.
  optional EnrollmentProvision enrollment_provision = 1 [default = UNMANAGED];
}

// A setting is a set of generic name value pairs.
// TODO(gfeher): remove this after Chrome OS TT is over.
message GenericSetting {
  repeated GenericNamedValue named_value = 1;
}

// Generic value container.
message GenericValue {
  enum ValueType {
    VALUE_TYPE_BOOL = 1;
    VALUE_TYPE_INT64 = 2;
    VALUE_TYPE_STRING = 3;
    VALUE_TYPE_DOUBLE = 4;
    VALUE_TYPE_BYTES = 5;
    VALUE_TYPE_BOOL_ARRAY = 6;
    VALUE_TYPE_INT64_ARRAY = 7;
    VALUE_TYPE_STRING_ARRAY = 8;
    VALUE_TYPE_DOUBLE_ARRAY = 9;
  }

  optional ValueType value_type = 1 [default = VALUE_TYPE_STRING];

  // basic value types
  optional bool bool_value = 2;
  optional int64 int64_value = 3;
  optional string string_value = 4;
  optional double double_value = 5;
  optional bytes bytes_value = 6;
  repeated bool bool_array = 7;
  repeated int64 int64_array = 8;
  repeated string string_array = 9;
  repeated double double_array = 10;
}

// Generic name value pair container.
message GenericNamedValue {
  required string name = 1;
  optional GenericValue value = 2;
}

// Identify a single device policy setting key/value pair.
// TODO(gfeher): remove this after Chrome OS TT is over.
message DevicePolicySetting {
  // key of the policy setting
  required string policy_key = 1;
  // value of the setting
  optional GenericSetting policy_value = 2;
  // watermark for setting value.
  optional string watermark = 3;
}

// 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 MEID, Mac adress.
  // 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;
}

// Response from server to device register request.
message DeviceRegisterResponse {
  // Device mangement 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
  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;
}

// 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 milli seconds 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 ChromeUserSettingsProto.
  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;
}

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 result of the settings.
  // TODO(gfeher): remove this after Chrome OS TT is over.
  repeated DevicePolicySetting setting = 1;

  // The policy fetch response.
  repeated PolicyFetchResponse response = 3;
}

// 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
//   * 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 [\x20-\x7E].
//   * agent: MUST BE no more than 64-char long.
// * HTTP Authorization header MUST be in the following formats:
//   * For register and ping requests
//     Authorization: GoogleLogin auth=<auth cookie for Mobile Sync>
//
//   * For unregister and policy requests
//      Authorization: GoogleDMToken token=<dm token from register>
//
//   * OAuth is NOT supported yet.
message DeviceManagementRequest {
  // Register request.
  optional DeviceRegisterRequest register_request = 1;

  // Unregister request.
  optional DeviceUnregisterRequest unregister_request = 2;

  // Policy request.
  optional DevicePolicyRequest policy_request = 3;
}

// Response from server to device.
message DeviceManagementResponse {
  // Error code to client.
  enum ErrorCode {
    SUCCESS = 0;
    // Returned for register request when device management is not supported
    // for the domain.
    DEVICE_MANAGEMENT_NOT_SUPPORTED = 1;
    // Returned when the device is not found.
    DEVICE_NOT_FOUND  = 2;
    // Returned when passed in device management token doesn't match the token
    // on server side.
    DEVICE_MANAGEMENT_TOKEN_INVALID  = 3;
    // Returned when device registration is pending approval (if required).
    ACTIVATION_PENDING = 4;
    // Returned when the policy is not found.
    POLICY_NOT_FOUND  = 5;
  }

  // Error code for this request.
  required ErrorCode error = 1;

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