cryptfs.h

   1 /*
   2  * Copyright (C) 2010 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
  17 /* This structure starts 16,384 bytes before the end of a hardware
  18  * partition that is encrypted, or in a separate partition.  It's location
  19  * is specified by a property set in init.<device>.rc.
  20  * The structure allocates 48 bytes for a key, but the real key size is
  21  * specified in the struct.  Currently, the code is hardcoded to use 128
  22  * bit keys.
  23  * The fields after salt are only valid in rev 1.1 and later stuctures.
  24  * Obviously, the filesystem does not include the last 16 kbytes
  25  * of the partition if the crypt_mnt_ftr lives at the end of the
  26  * partition.
  27  */
  28
  29 #include <cutils/properties.h>
  30 #include <openssl/sha.h>
  31
  32 /* The current cryptfs version */
  33 #define CURRENT_MAJOR_VERSION 1
  34 #define CURRENT_MINOR_VERSION 3
  35
  36 #define CRYPT_FOOTER_OFFSET 0x4000
  37 #define CRYPT_FOOTER_TO_PERSIST_OFFSET 0x1000
  38 #define CRYPT_PERSIST_DATA_SIZE 0x1000
  39
  40 #define MAX_CRYPTO_TYPE_NAME_LEN 64
  41
  42 #define MAX_KEY_LEN 48
  43 #define SALT_LEN 16
  44 #define SCRYPT_LEN 32
  45
  46 /* definitions of flags in the structure below */
  47 #define CRYPT_MNT_KEY_UNENCRYPTED 0x1 /* The key for the partition is not encrypted. */
  48 #define CRYPT_ENCRYPTION_IN_PROGRESS 0x2 /* Encryption partially completed,
  49                                             encrypted_upto valid*/
  50 #define CRYPT_INCONSISTENT_STATE 0x4 /* Set when starting encryption, clear when
  51                                         exit cleanly, either through success or
  52                                         correctly marked partial encryption */
  53 #define CRYPT_DATA_CORRUPT 0x8 /* Set when encryption is fine, but the
  54                                   underlying volume is corrupt */
  55
  56 /* Allowed values for type in the structure below */
  57 #define CRYPT_TYPE_PASSWORD 0 /* master_key is encrypted with a password
  58                                * Must be zero to be compatible with pre-L
  59                                * devices where type is always password.*/
  60 #define CRYPT_TYPE_DEFAULT  1 /* master_key is encrypted with default
  61                                * password */
  62 #define CRYPT_TYPE_PATTERN  2 /* master_key is encrypted with a pattern */
  63 #define CRYPT_TYPE_PIN      3 /* master_key is encrypted with a pin */
  64 #define CRYPT_TYPE_MAX_TYPE 3 /* type cannot be larger than this value */
  65
  66 #define CRYPT_MNT_MAGIC 0xD0B5B1C4
  67 #define PERSIST_DATA_MAGIC 0xE950CD44
  68
  69 #define SCRYPT_PROP "ro.crypto.scrypt_params"
  70 #define SCRYPT_DEFAULTS { 15, 3, 1 }
  71
  72 /* Key Derivation Function algorithms */
  73 #define KDF_PBKDF2 1
  74 #define KDF_SCRYPT 2
  75 /* TODO(paullawrence): Remove KDF_SCRYPT_KEYMASTER_UNPADDED and KDF_SCRYPT_KEYMASTER_BADLY_PADDED
  76  * when it is safe to do so. */
  77 #define KDF_SCRYPT_KEYMASTER_UNPADDED 3
  78 #define KDF_SCRYPT_KEYMASTER_BADLY_PADDED 4
  79 #define KDF_SCRYPT_KEYMASTER 5
  80
  81 /* Maximum allowed keymaster blob size. */
  82 #define KEYMASTER_BLOB_SIZE 2048
  83
  84 /* __le32 and __le16 defined in system/extras/ext4_utils/ext4_utils.h */
  85 #define __le8  unsigned char
  86
  87 struct crypt_mnt_ftr {
  88   __le32 magic;         /* See above */
  89   __le16 major_version;
  90   __le16 minor_version;
  91   __le32 ftr_size;      /* in bytes, not including key following */
  92   __le32 flags;         /* See above */
  93   __le32 keysize;       /* in bytes */
  94   __le32 crypt_type;    /* how master_key is encrypted. Must be a
  95                          * CRYPT_TYPE_XXX value */
  96   __le64 fs_size;       /* Size of the encrypted fs, in 512 byte sectors */
  97   __le32 failed_decrypt_count; /* count of # of failed attempts to decrypt and
  98                                   mount, set to 0 on successful mount */
  99   unsigned char crypto_type_name[MAX_CRYPTO_TYPE_NAME_LEN]; /* The type of encryption
 100                                                                needed to decrypt this
 101                                                                partition, null terminated */
 102   __le32 spare2;        /* ignored */
 103   unsigned char master_key[MAX_KEY_LEN]; /* The encrypted key for decrypting the filesystem */
 104   unsigned char salt[SALT_LEN];   /* The salt used for this encryption */
 105   __le64 persist_data_offset[2];  /* Absolute offset to both copies of crypt_persist_data
 106                                    * on device with that info, either the footer of the
 107                                    * real_blkdevice or the metadata partition. */
 108
 109   __le32 persist_data_size;       /* The number of bytes allocated to each copy of the
 110                                    * persistent data table*/
 111
 112   __le8  kdf_type; /* The key derivation function used. */
 113
 114   /* scrypt parameters. See www.tarsnap.com/scrypt/scrypt.pdf */
 115   __le8  N_factor; /* (1 << N) */
 116   __le8  r_factor; /* (1 << r) */
 117   __le8  p_factor; /* (1 << p) */
 118   __le64 encrypted_upto; /* If we are in state CRYPT_ENCRYPTION_IN_PROGRESS and
 119                             we have to stop (e.g. power low) this is the last
 120                             encrypted 512 byte sector.*/
 121   __le8  hash_first_block[SHA256_DIGEST_LENGTH]; /* When CRYPT_ENCRYPTION_IN_PROGRESS
 122                                                     set, hash of first block, used
 123                                                     to validate before continuing*/
 124
 125   /* key_master key, used to sign the derived key which is then used to generate
 126    * the intermediate key
 127    * This key should be used for no other purposes! We use this key to sign unpadded
 128    * data, which is acceptable but only if the key is not reused elsewhere. */
 129   __le8 keymaster_blob[KEYMASTER_BLOB_SIZE];
 130   __le32 keymaster_blob_size;
 131
 132   /* Store scrypt of salted intermediate key. When decryption fails, we can
 133      check if this matches, and if it does, we know that the problem is with the
 134      drive, and there is no point in asking the user for more passwords.
 135
 136      Note that if any part of this structure is corrupt, this will not match and
 137      we will continue to believe the user entered the wrong password. In that
 138      case the only solution is for the user to enter a password enough times to
 139      force a wipe.
 140
 141      Note also that there is no need to worry about migration. If this data is
 142      wrong, we simply won't recognise a right password, and will continue to
 143      prompt. On the first password change, this value will be populated and
 144      then we will be OK.
 145    */
 146   unsigned char scrypted_intermediate_key[SCRYPT_LEN];
 147 };
 148
 149 /* Persistant data that should be available before decryption.
 150  * Things like airplane mode, locale and timezone are kept
 151  * here and can be retrieved by the CryptKeeper UI to properly
 152  * configure the phone before asking for the password
 153  * This is only valid if the major and minor version above
 154  * is set to 1.1 or higher.
 155  *
 156  * This is a 4K structure.  There are 2 copies, and the code alternates
 157  * writing one and then clearing the previous one.  The reading
 158  * code reads the first valid copy it finds, based on the magic number.
 159  * The absolute offset to the first of the two copies is kept in rev 1.1
 160  * and higher crypt_mnt_ftr structures.
 161  */
 162 struct crypt_persist_entry {
 163   char key[PROPERTY_KEY_MAX];
 164   char val[PROPERTY_VALUE_MAX];
 165 };
 166
 167 /* Should be exactly 4K in size */
 168 struct crypt_persist_data {
 169   __le32 persist_magic;
 170   __le32 persist_valid_entries;
 171   __le32 persist_spare[30];
 172   struct crypt_persist_entry persist_entry[0];
 173 };
 174
 175 struct volume_info {
 176    unsigned int size;
 177    unsigned int flags;
 178    struct crypt_mnt_ftr crypt_ftr;
 179    char mnt_point[256];
 180    char blk_dev[256];
 181    char crypto_blkdev[256];
 182    char label[256];
 183 };
 184 #define VOL_NONREMOVABLE   0x1
 185 #define VOL_ENCRYPTABLE    0x2
 186 #define VOL_PRIMARY        0x4
 187 #define VOL_PROVIDES_ASEC  0x8
 188
 189 #define DATA_MNT_POINT "/data"
 190
 191 /* Return values for cryptfs_crypto_complete */
 192 #define CRYPTO_COMPLETE_NOT_ENCRYPTED  1
 193 #define CRYPTO_COMPLETE_ENCRYPTED      0
 194 #define CRYPTO_COMPLETE_BAD_METADATA  -1
 195 #define CRYPTO_COMPLETE_PARTIAL       -2
 196 #define CRYPTO_COMPLETE_INCONSISTENT  -3
 197 #define CRYPTO_COMPLETE_CORRUPT       -4
 198
 199 /* Return values for cryptfs_enable_inplace*() */
 200 #define ENABLE_INPLACE_OK 0
 201 #define ENABLE_INPLACE_ERR_OTHER -1
 202 #define ENABLE_INPLACE_ERR_DEV -2  /* crypto_blkdev issue */
 203
 204 /* Return values for cryptfs_getfield */
 205 #define CRYPTO_GETFIELD_OK                   0
 206 #define CRYPTO_GETFIELD_ERROR_NO_FIELD      -1
 207 #define CRYPTO_GETFIELD_ERROR_OTHER         -2
 208 #define CRYPTO_GETFIELD_ERROR_BUF_TOO_SMALL -3
 209
 210 /* Return values for cryptfs_setfield */
 211 #define CRYPTO_SETFIELD_OK                    0
 212 #define CRYPTO_SETFIELD_ERROR_OTHER          -1
 213 #define CRYPTO_SETFIELD_ERROR_FIELD_TOO_LONG -2
 214 #define CRYPTO_SETFIELD_ERROR_VALUE_TOO_LONG -3
 215
 216 /* Return values for persist_del_key */
 217 #define PERSIST_DEL_KEY_OK                 0
 218 #define PERSIST_DEL_KEY_ERROR_OTHER       -1
 219 #define PERSIST_DEL_KEY_ERROR_NO_FIELD    -2
 220
 221 #ifdef __cplusplus
 222 extern "C" {
 223 #endif
 224
 225   typedef int (*kdf_func)(const char *passwd, const unsigned char *salt,
 226                           unsigned char *ikey, void *params);
 227
 228   int cryptfs_crypto_complete(void);
 229   int cryptfs_check_passwd(char *pw);
 230   int cryptfs_verify_passwd(char *newpw);
 231   int cryptfs_restart(void);
 232   int cryptfs_enable(char *flag, int type, char *passwd, int allow_reboot);
 233   int cryptfs_changepw(int type, const char *newpw);
 234   int cryptfs_enable_default(char *flag, int allow_reboot);
 235   int cryptfs_setup_volume(const char *label, int major, int minor,
 236                            char *crypto_dev_path, unsigned int max_pathlen,
 237                            int *new_major, int *new_minor);
 238   int cryptfs_revert_volume(const char *label);
 239   int cryptfs_getfield(const char *fieldname, char *value, int len);
 240   int cryptfs_setfield(const char *fieldname, const char *value);
 241   int cryptfs_mount_default_encrypted(void);
 242   int cryptfs_get_password_type(void);
 243   char* cryptfs_get_password(void);
 244   void cryptfs_clear_password(void);
 245 #ifdef __cplusplus
 246 }
 247 #endif