WrappedApplicationKey.java revision 3990ee1c9fcd8f801220edec94e6bef3009809b5
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 * @deprecated AOSP does not associate keys with accounts. This may be done by system app. 79 * @removed 80 */ 81 @Deprecated 82 public Builder setAccount(@NonNull byte[] account) { 83 return this; 84 } 85 86 /** 87 * Sets key material encrypted by recovery key. 88 * 89 * @param encryptedKeyMaterial The key material 90 * @return This builder 91 */ 92 93 public Builder setEncryptedKeyMaterial(@NonNull byte[] encryptedKeyMaterial) { 94 mInstance.mEncryptedKeyMaterial = encryptedKeyMaterial; 95 return this; 96 } 97 98 /** 99 * Creates a new {@link WrappedApplicationKey} instance. 100 * 101 * @return new instance 102 * @throws NullPointerException if some required fields were not set. 103 */ 104 @NonNull public WrappedApplicationKey build() { 105 Preconditions.checkNotNull(mInstance.mAlias); 106 Preconditions.checkNotNull(mInstance.mEncryptedKeyMaterial); 107 return mInstance; 108 } 109 } 110 111 private WrappedApplicationKey() { } 112 113 /** 114 * Deprecated - consider using Builder. 115 * @hide 116 */ 117 public WrappedApplicationKey(@NonNull String alias, @NonNull byte[] encryptedKeyMaterial) { 118 mAlias = Preconditions.checkNotNull(alias); 119 mEncryptedKeyMaterial = Preconditions.checkNotNull(encryptedKeyMaterial); 120 } 121 122 /** 123 * Application-specific alias of the key. 124 * 125 * @see java.security.KeyStore.aliases 126 */ 127 public @NonNull String getAlias() { 128 return mAlias; 129 } 130 131 /** Key material encrypted by recovery key. */ 132 public @NonNull byte[] getEncryptedKeyMaterial() { 133 return mEncryptedKeyMaterial; 134 } 135 136 /** 137 * @deprecated AOSP does not associate keys with accounts. This may be done by system app. 138 * @removed 139 */ 140 @Deprecated 141 public @NonNull byte[] getAccount() { 142 return new byte[0]; 143 } 144 145 public static final Parcelable.Creator<WrappedApplicationKey> CREATOR = 146 new Parcelable.Creator<WrappedApplicationKey>() { 147 public WrappedApplicationKey createFromParcel(Parcel in) { 148 return new WrappedApplicationKey(in); 149 } 150 151 public WrappedApplicationKey[] newArray(int length) { 152 return new WrappedApplicationKey[length]; 153 } 154 }; 155 156 @Override 157 public void writeToParcel(Parcel out, int flags) { 158 out.writeString(mAlias); 159 out.writeByteArray(mEncryptedKeyMaterial); 160 } 161 162 /** 163 * @hide 164 */ 165 protected WrappedApplicationKey(Parcel in) { 166 mAlias = in.readString(); 167 mEncryptedKeyMaterial = in.createByteArray(); 168 } 169 170 @Override 171 public int describeContents() { 172 return 0; 173 } 174} 175