|
| 1 | +package android.system.keystore2; |
| 2 | + |
| 3 | +import android.os.IBinder; |
| 4 | +import android.os.IInterface; |
| 5 | + |
| 6 | +import androidx.annotation.Nullable; |
| 7 | + |
| 8 | +/** |
| 9 | + * {@code IKeystoreOperation} represents a cryptographic operation using a Keystore key. |
| 10 | + * |
| 11 | + * <p>The lifecycle of an operation begins with {@link KeystoreSecurityLevel#create} |
| 12 | + * and ends with a call to {@link #finish}, {@link #abort}, or when the reference to |
| 13 | + * the binder object is released. |
| 14 | + * |
| 15 | + * <p>During the operation lifecycle, {@link #update} may be called multiple times. |
| 16 | + * For AEAD operations, {@link #updateAad} may be called to add associated data, but |
| 17 | + * it must be called before the first call to {@link #update}. |
| 18 | + * |
| 19 | + * <h2>Error Conditions</h2> |
| 20 | + * <p>Error conditions are reported as service-specific errors: |
| 21 | + * <ul> |
| 22 | + * <li>Positive error codes correspond to {@code android.system.keystore2.ResponseCode} |
| 23 | + * and indicate error conditions diagnosed by the Keystore 2.0 service.</li> |
| 24 | + * <li>Negative error codes correspond to {@code android.hardware.security.keymint.ErrorCode} |
| 25 | + * and indicate KeyMint backend errors. Refer to the KeyMint interface specification |
| 26 | + * for detailed information.</li> |
| 27 | + * </ul> |
| 28 | + */ |
| 29 | +public interface IKeystoreOperation extends IInterface { |
| 30 | + String DESCRIPTOR = "android.system.keystore2.IKeystoreOperation"; |
| 31 | + |
| 32 | + /** |
| 33 | + * Advances an operation by adding Additional Authenticated Data (AAD) to AEAD mode |
| 34 | + * encryption or decryption operations. This method cannot be called after {@link #update}, |
| 35 | + * and attempting to do so will result in {@code ErrorCode.INVALID_TAG}. This error code |
| 36 | + * is used for historical reasons, dating back when AAD was passed as an additional |
| 37 | + * {@code KeyParameter} with the tag {@code ASSOCIATED_DATA}. |
| 38 | + * |
| 39 | + * <h2>Error Conditions</h2> |
| 40 | + * <ul> |
| 41 | + * <li>{@code ResponseCode.TOO_MUCH_DATA} if {@code aadInput} exceeds 32KiB.</li> |
| 42 | + * <li>{@code ResponseCode.OPERATION_BUSY} if {@code updateAad} is called concurrently |
| 43 | + * with any other {@code IKeystoreOperation} API call.</li> |
| 44 | + * <li>{@code ErrorCode.INVALID_TAG} if {@code updateAad} is called after {@link #update} |
| 45 | + * on a given operation.</li> |
| 46 | + * <li>{@code ErrorCode.INVALID_OPERATION_HANDLE} if the operation has been finalized |
| 47 | + * for any reason.</li> |
| 48 | + * </ul> |
| 49 | + * <p> |
| 50 | + * Note: Any error condition except {@code ResponseCode.OPERATION_BUSY} finalizes the |
| 51 | + * operation, causing subsequent API calls to return {@code INVALID_OPERATION_HANDLE}. |
| 52 | + * |
| 53 | + * @param aadInput the Additional Authenticated Data to be added to the operation |
| 54 | + */ |
| 55 | + void updateAad(byte[] aadInput); |
| 56 | + |
| 57 | + /** |
| 58 | + * Advances the operation by processing additional input data. The input data may be |
| 59 | + * plain text to be encrypted or signed, or cipher text to be decrypted. During |
| 60 | + * encryption operations, this method returns the resulting cipher text. During |
| 61 | + * decryption operations, it returns the resulting plain text. No data is returned |
| 62 | + * for signing operations. |
| 63 | + * |
| 64 | + * <h2>Error Conditions</h2> |
| 65 | + * <ul> |
| 66 | + * <li>{@code ResponseCode.TOO_MUCH_DATA} if the {@code input} exceeds 32KiB.</li> |
| 67 | + * <li>{@code ResponseCode.OPERATION_BUSY} if {@code updateAad} is called concurrently |
| 68 | + * with any other {@code IKeystoreOperation} API call.</li> |
| 69 | + * <li>{@code ErrorCode.INVALID_OPERATION_HANDLE} if the operation has been finalized |
| 70 | + * for any reason.</li> |
| 71 | + * </ul> |
| 72 | + * <p> |
| 73 | + * Note: Any error condition except {@code ResponseCode.OPERATION_BUSY} finalizes the |
| 74 | + * operation, causing subsequent API calls to return {@code INVALID_OPERATION_HANDLE}. |
| 75 | + * |
| 76 | + * @param input the input data to process |
| 77 | + * @return the output data, which may be cipher text during encryption, plain text |
| 78 | + * during decryption, or {@code null} for signing operations |
| 79 | + */ |
| 80 | + byte[] update(byte[] input); |
| 81 | + |
| 82 | + /** |
| 83 | + * Finalizes the operation. This method takes a final chunk of input data similar to |
| 84 | + * {@link #update}. The output varies depending on the operation type: it may be a |
| 85 | + * signature for signing operations, plain text for decryption operations, or cipher |
| 86 | + * text for encryption operations. |
| 87 | + * |
| 88 | + * <h2>Error Conditions</h2> |
| 89 | + * <ul> |
| 90 | + * <li>{@code ResponseCode.TOO_MUCH_DATA} if the {@code input} exceeds 32KiB.</li> |
| 91 | + * <li>{@code ResponseCode.OPERATION_BUSY} if {@code updateAad} is called concurrently |
| 92 | + * with any other {@code IKeystoreOperation} API call.</li> |
| 93 | + * <li>{@code ErrorCode.INVALID_OPERATION_HANDLE} if the operation has already been |
| 94 | + * finalized for any reason.</li> |
| 95 | + * </ul> |
| 96 | + * <p> |
| 97 | + * Note: {@code finish} finalizes the operation regardless of the outcome, unless |
| 98 | + * {@code ResponseCode.OPERATION_BUSY} is returned. |
| 99 | + * |
| 100 | + * @param input the final chunk of input data to process |
| 101 | + * @param signature an optional HMAC signature for HMAC verification operations |
| 102 | + * @return the operation result, which may be a signature for signing operations, |
| 103 | + * an AEAD message tag for authenticated encryption, or the final chunk of |
| 104 | + * cipher/plain text for encryption/decryption operations respectively |
| 105 | + */ |
| 106 | + byte[] finish(@Nullable byte[] input, @Nullable byte[] signature); |
| 107 | + |
| 108 | + /** |
| 109 | + * Aborts the operation immediately. |
| 110 | + * |
| 111 | + * <p>Note: {@code abort} finalizes the operation regardless of the outcome, unless |
| 112 | + * {@code ResponseCode.OPERATION_BUSY} is returned. |
| 113 | + */ |
| 114 | + void abort(); |
| 115 | + |
| 116 | + class Stub implements IKeystoreOperation { |
| 117 | + public static IKeystoreOperation asInterface(IBinder b) { |
| 118 | + throw new RuntimeException("Stub!"); |
| 119 | + } |
| 120 | + |
| 121 | + @Override |
| 122 | + public void updateAad(byte[] aadInput) { |
| 123 | + throw new RuntimeException("Stub!"); |
| 124 | + } |
| 125 | + |
| 126 | + @Override |
| 127 | + public byte[] update(byte[] input) { |
| 128 | + throw new RuntimeException("Stub!"); |
| 129 | + } |
| 130 | + |
| 131 | + @Override |
| 132 | + public byte[] finish(@Nullable byte[] input, @Nullable byte[] signature) { |
| 133 | + throw new RuntimeException("Stub!"); |
| 134 | + } |
| 135 | + |
| 136 | + @Override |
| 137 | + public void abort() { |
| 138 | + throw new RuntimeException("Stub!"); |
| 139 | + } |
| 140 | + |
| 141 | + @Override |
| 142 | + public IBinder asBinder() { |
| 143 | + throw new RuntimeException("Stub!"); |
| 144 | + } |
| 145 | + } |
| 146 | +} |
0 commit comments