1 /* 2 * Copyright (C) 2019 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 package android.car.encryptionrunner; 18 19 import android.annotation.NonNull; 20 21 /** 22 * A generalized interface that allows for generating shared secrets as well as encrypting 23 * messages. 24 * 25 * To use this interface: 26 * 1. As a client. 27 * 28 * HandshakeMessage initialClientMessage = clientRunner.initHandshake(); 29 * sendToServer(initialClientMessage.getNextMessage()); 30 * byte message = getServerResponse(); 31 * 32 * HandshakeMessage message = clientRunner.continueHandshake(message); 33 * message.getHandshakeState() should be VERIFICATION_NEEDED, 34 * otherwise if IN_PROGRESS just send the result of getNextMessage(); 35 * 36 * Show user the verification code and ask to verify. 37 * message.getVerificationCode() 38 * 39 * if user agrees 40 * HandshakeMessage lastMessage = clientRunner.verifyPin(); 41 * otherwise 42 * clientRunner.invalidPin(); 43 * 44 * Use lastMessage.getKey() for encryption. 45 * 46 * 2. As a server. 47 * 48 * byte[] initialMessage = getClientMessageBytes(); 49 * HandshakeMesssage message = serverRunner.respondToInitRequest(initialMessage); 50 * 51 * sendToClient(message.getNextMessage()); 52 * 53 * message.getHandshakeState() should be VERIFICATION_NEEDED, 54 * if so show user code and ask to verify 55 * message.getVerificationCode(); 56 * 57 * serverRunner.verifyPin or invalidPin and continue same as client above. 58 * 59 * 60 * Also see {@link EncryptionRunnerTest} for examples. 61 */ 62 public interface EncryptionRunner { 63 64 String TAG = "EncryptionRunner"; 65 66 /** 67 * Starts an encryption handshake. 68 * 69 * @return A handshake message with information about the handshake that is started. 70 */ initHandshake()71 HandshakeMessage initHandshake(); 72 73 /** 74 * Starts an encryption handshake where the device that is being communicated with already 75 * initiated the request. 76 * 77 * @param initializationRequest the bytes that the other device sent over. 78 * @return a handshake message with information about the handshake. 79 * 80 * @throws HandshakeException if initialization request is invalid. 81 */ respondToInitRequest(@onNull byte[] initializationRequest)82 HandshakeMessage respondToInitRequest(@NonNull byte[] initializationRequest) 83 throws HandshakeException; 84 85 /** 86 * Continues a handshake after receiving another response from the connected device. 87 * 88 * @param response the response from the other device. 89 * @return a message that can be used to continue the handshake. 90 * 91 * @throws HandshakeException if unexpected bytes in response. 92 */ continueHandshake(@onNull byte[] response)93 HandshakeMessage continueHandshake(@NonNull byte[] response) throws HandshakeException; 94 95 /** 96 * Verifies the pin shown to the user. The result is the next handshake message and will 97 * typically contain an encryption key. 98 * 99 * @throws HandshakeException if not in state to verify pin. 100 */ verifyPin()101 HandshakeMessage verifyPin() throws HandshakeException; 102 103 /** 104 * Notifies the encryption runner that the user failed to validate the pin. After calling this 105 * method the runner should not be used, and will throw exceptions. 106 */ invalidPin()107 void invalidPin(); 108 109 /** 110 * De-serializes a previously serialized key generated by an instance of this encryption runner. 111 * 112 * @param serialized the serialized bytes of the key. 113 * @return the Key object used for encryption. 114 */ keyOf(@onNull byte[] serialized)115 Key keyOf(@NonNull byte[] serialized); 116 117 } 118