WrappedApplicationKey.java revision 0d55aa387a4ec65899fc82a1391e5533c85c3edb
1/* 2 * Copyright (C) 2018 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 17package android.security.keystore.recovery; 18 19import android.annotation.NonNull; 20import android.annotation.SystemApi; 21import android.os.Parcel; 22import android.os.Parcelable; 23 24import com.android.internal.util.Preconditions; 25 26/** 27 * Helper class with data necessary recover a single application key, given a recovery key. 28 * 29 * <ul> 30 * <li>Alias - Keystore alias of the key. 31 * <li>Encrypted key material. 32 * </ul> 33 * 34 * Note that Application info is not included. Recovery Agent can only make its own keys 35 * recoverable. 36 * 37 * @hide 38 */ 39@SystemApi 40public final class WrappedApplicationKey implements Parcelable { 41 private String mAlias; 42 // The only supported format is AES-256 symmetric key. 43 private byte[] mEncryptedKeyMaterial; 44 45 // IMPORTANT! PLEASE READ! 46 // ----------------------- 47 // If you edit this file (e.g., to add new fields), please MAKE SURE to also do the following: 48 // - Update the #writeToParcel(Parcel) method below 49 // - Update the #(Parcel) constructor below 50 // - Update android.security.keystore.recovery.KeyChainSnapshotTest to make sure nobody 51 // accidentally breaks your fields in the Parcel in the future. 52 // - Update com.android.server.locksettings.recoverablekeystore.serialization 53 // .KeyChainSnapshotSerializer to correctly serialize your new field 54 // - Update com.android.server.locksettings.recoverablekeystore.serialization 55 // .KeyChainSnapshotSerializer to correctly deserialize your new field 56 // - Update com.android.server.locksettings.recoverablekeystore.serialization 57 // .KeychainSnapshotSerializerTest to make sure nobody breaks serialization of your field 58 // in the future. 59 60 /** 61 * Builder for creating {@link WrappedApplicationKey}. 62 */ 63 public static class Builder { 64 private WrappedApplicationKey mInstance = new WrappedApplicationKey(); 65 66 /** 67 * Sets Application-specific alias of the key. 68 * 69 * @param alias The alias. 70 * @return This builder. 71 */ 72 public Builder setAlias(@NonNull String alias) { 73 mInstance.mAlias = alias; 74 return this; 75 } 76 77 /** 78 * @removed AOSP does not associate keys with accounts. This may be done by system app. 79 */ 80 @Deprecated 81 public Builder setAccount(@NonNull byte[] account) { 82 return this; 83 } 84 85 /** 86 * Sets key material encrypted by recovery key. 87 * 88 * @param encryptedKeyMaterial The key material 89 * @return This builder 90 */ 91 92 public Builder setEncryptedKeyMaterial(@NonNull byte[] encryptedKeyMaterial) { 93 mInstance.mEncryptedKeyMaterial = encryptedKeyMaterial; 94 return this; 95 } 96 97 /** 98 * Creates a new {@link WrappedApplicationKey} instance. 99 * 100 * @return new instance 101 * @throws NullPointerException if some required fields were not set. 102 */ 103 @NonNull public WrappedApplicationKey build() { 104 Preconditions.checkNotNull(mInstance.mAlias); 105 Preconditions.checkNotNull(mInstance.mEncryptedKeyMaterial); 106 return mInstance; 107 } 108 } 109 110 private WrappedApplicationKey() { } 111 112 /** 113 * Deprecated - consider using Builder. 114 * @hide 115 */ 116 public WrappedApplicationKey(@NonNull String alias, @NonNull byte[] encryptedKeyMaterial) { 117 mAlias = Preconditions.checkNotNull(alias); 118 mEncryptedKeyMaterial = Preconditions.checkNotNull(encryptedKeyMaterial); 119 } 120 121 /** 122 * Application-specific alias of the key. 123 * 124 * @see java.security.KeyStore.aliases 125 */ 126 public @NonNull String getAlias() { 127 return mAlias; 128 } 129 130 /** Key material encrypted by recovery key. */ 131 public @NonNull byte[] getEncryptedKeyMaterial() { 132 return mEncryptedKeyMaterial; 133 } 134 135 /** 136 * @removed AOSP does not associate keys with accounts. This may be done by system app. 137 */ 138 @Deprecated 139 public @NonNull byte[] getAccount() { 140 return new byte[0]; 141 } 142 143 public static final Parcelable.Creator<WrappedApplicationKey> CREATOR = 144 new Parcelable.Creator<WrappedApplicationKey>() { 145 public WrappedApplicationKey createFromParcel(Parcel in) { 146 return new WrappedApplicationKey(in); 147 } 148 149 public WrappedApplicationKey[] newArray(int length) { 150 return new WrappedApplicationKey[length]; 151 } 152 }; 153 154 @Override 155 public void writeToParcel(Parcel out, int flags) { 156 out.writeString(mAlias); 157 out.writeByteArray(mEncryptedKeyMaterial); 158 } 159 160 /** 161 * @hide 162 */ 163 protected WrappedApplicationKey(Parcel in) { 164 mAlias = in.readString(); 165 mEncryptedKeyMaterial = in.createByteArray(); 166 } 167 168 @Override 169 public int describeContents() { 170 return 0; 171 } 172} 173