| /* |
| * Copyright (C) 2019 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.car.encryptionrunner; |
| |
| import android.annotation.NonNull; |
| |
| /** |
| * A generalized interface that allows for generating shared secrets as well as encrypting |
| * messages. |
| * |
| * To use this interface: |
| * 1. As a client. |
| * |
| * HandshakeMessage initialClientMessage = clientRunner.initHandshake(); |
| * sendToServer(initialClientMessage.getNextMessage()); |
| * byte message = getServerResponse(); |
| * |
| * HandshakeMessage message = clientRunner.continueHandshake(message); |
| * message.getHandshakeState() should be VERIFICATION_NEEDED, |
| * otherwise if IN_PROGRESS just send the result of getNextMessage(); |
| * |
| * Show user the verification code and ask to verify. |
| * message.getVerificationCode() |
| * |
| * if user agrees |
| * HandshakeMessage lastMessage = clientRunner.verifyPin(); |
| * otherwise |
| * clientRunner.invalidPin(); |
| * |
| * Use lastMessage.getKey() for encryption. |
| * |
| * 2. As a server. |
| * |
| * byte[] initialMessage = getClientMessageBytes(); |
| * HandshakeMesssage message = serverRunner.respondToInitRequest(initialMessage); |
| * |
| * sendToClient(message.getNextMessage()); |
| * |
| * message.getHandshakeState() should be VERIFICATION_NEEDED, |
| * if so show user code and ask to verify |
| * message.getVerificationCode(); |
| * |
| * serverRunner.verifyPin or invalidPin and continue same as client above. |
| * |
| * |
| * Also see {@link EncryptionRunnerTest} for examples. |
| */ |
| public interface EncryptionRunner { |
| |
| String TAG = "EncryptionRunner"; |
| |
| /** |
| * Starts an encryption handshake. |
| * |
| * @return A handshake message with information about the handshake that is started. |
| */ |
| HandshakeMessage initHandshake(); |
| |
| /** |
| * Starts an encryption handshake where the device that is being communicated with already |
| * initiated the request. |
| * |
| * @param initializationRequest the bytes that the other device sent over. |
| * @return a handshake message with information about the handshake. |
| * |
| * @throws HandshakeException if initialization request is invalid. |
| */ |
| HandshakeMessage respondToInitRequest(@NonNull byte[] initializationRequest) |
| throws HandshakeException; |
| |
| /** |
| * Continues a handshake after receiving another response from the connected device. |
| * |
| * @param response the response from the other device. |
| * @return a message that can be used to continue the handshake. |
| * |
| * @throws HandshakeException if unexpected bytes in response. |
| */ |
| HandshakeMessage continueHandshake(@NonNull byte[] response) throws HandshakeException; |
| |
| /** |
| * Verifies the pin shown to the user. The result is the next handshake message and will |
| * typically contain an encryption key. |
| * |
| * @throws HandshakeException if not in state to verify pin. |
| */ |
| HandshakeMessage verifyPin() throws HandshakeException; |
| |
| /** |
| * Notifies the encryption runner that the user failed to validate the pin. After calling this |
| * method the runner should not be used, and will throw exceptions. |
| */ |
| void invalidPin(); |
| |
| /** |
| * De-serializes a previously serialized key generated by an instance of this encryption runner. |
| * |
| * @param serialized the serialized bytes of the key. |
| * @return the Key object used for encryption. |
| */ |
| Key keyOf(@NonNull byte[] serialized); |
| |
| } |