oemlock/1.0/IOemLock.hal

   1 /*
   2  * Copyright (C) 2017 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 package android.hardware.oemlock@1.0;
  17
  18 /*
  19  * The OEM lock prevents the bootloader from allowing the device to be flashed.
  20  *
  21  * Both the carrier and the device itself have a say as to whether OEM unlock is
  22  * allowed and both must agree that is allowed in order for unlock to be
  23  * possible.
  24  */
  25 interface IOemLock {
  26     /**
  27      * Returns a vendor specific identifier of the HAL.
  28      *
  29      * The name returned must not be interpreted by the framework but must be
  30      * passed to vendor code which may use it to identify the security protocol
  31      * used by setOemUnlockAllowedByCarrier. This allows the vendor to identify
  32      * the protocol without having to maintain a device-to-protocol mapping.
  33      *
  34      * @return name of the implementation.
  35      */
  36     getName() generates (OemLockStatus status, string name);
  37
  38     /**
  39      * Updates whether OEM unlock is allowed by the carrier.
  40      *
  41      * The implementation may require a vendor defined signature to prove the
  42      * validity of this request in order to harden its security.
  43      *
  44      * @param allowed is the new value of the flag.
  45      * @param signature to prove validity of this request or empty if not
  46      *        required.
  47      * @return status is OK if the flag was successfully updated,
  48      *         INVALID_SIGNATURE if a signature is required but the wrong one
  49      *         was provided or FAILED if the update was otherwise unsuccessful.
  50      */
  51     setOemUnlockAllowedByCarrier(bool allowed, vec<uint8_t> signature)
  52             generates (OemLockSecureStatus status);
  53
  54     /**
  55      * Returns whether OEM unlock is allowed by the carrier.
  56      *
  57      * @return status is OK if the flag was successfully read.
  58      * @return allowed is the current state of the flag.
  59      */
  60     isOemUnlockAllowedByCarrier() generates (OemLockStatus status, bool allowed);
  61
  62     /**
  63      * Updates whether OEM unlock is allowed by the device.
  64      *
  65      * @param allowed is the new value of the flag.
  66      * @return status is OK if the flag was successfully updated.
  67      */
  68     setOemUnlockAllowedByDevice(bool allowed) generates (OemLockStatus status);
  69
  70     /**
  71      * Returns whether OEM unlock ia allowed by the device.
  72      *
  73      * @return status is OK if the flag was successfully read.
  74      * @return allowed is the current state of the flag.
  75      */
  76     isOemUnlockAllowedByDevice() generates (OemLockStatus status, bool allowed);
  77 };