1 /* 2 * Copyright 2021 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.hardware.identity; 18 19 import android.hardware.identity.CipherSuite; 20 import android.hardware.identity.IIdentityCredential; 21 22 /** 23 * An interface to present multiple credentials in the same session. 24 * 25 * This interface was introduced in API version 4. 26 * 27 */ 28 @VintfStability 29 interface IPresentationSession { 30 /** 31 * Gets the ephemeral EC key pair to be used in establishing a secure session with a reader. 32 * This method returns the private key so the caller can perform an ECDH key agreement operation 33 * with the reader. The reason for generating the key pair in the secure environment is so that 34 * the secure environment knows what public key to expect to find in the session transcript 35 * when presenting credentials. 36 * 37 * The generated key matches the selected cipher suite of the presentation session (e.g. EC 38 * key using the P-256 curve). 39 * 40 * @return the private key, in DER format as specified in RFC 5915. 41 */ getEphemeralKeyPair()42 byte[] getEphemeralKeyPair(); 43 44 /** 45 * Gets the challenge value to be used for proving successful user authentication. This 46 * is to be included in the authToken passed to the IIdentityCredential.startRetrieval() 47 * method and the verificationToken passed to the IIdentityCredential.setVerificationToken() 48 * method. 49 * 50 * @return challenge, a non-zero number. 51 */ getAuthChallenge()52 long getAuthChallenge(); 53 54 /** 55 * Sets the public part of the reader's ephemeral key pair to be used to complete 56 * an ECDH key agreement for the session. 57 * 58 * The curve of the key must match the curve for the key returned by getEphemeralKeyPair(). 59 * 60 * This method may only be called once per instance. If called more than once, STATUS_FAILED 61 * must be returned. 62 * 63 * @param publicKey contains the reader's ephemeral public key, in uncompressed 64 * form (e.g. 0x04 || X || Y). 65 */ setReaderEphemeralPublicKey(in byte[] publicKey)66 void setReaderEphemeralPublicKey(in byte[] publicKey); 67 68 /** 69 * Sets the session transcript for the session. 70 * 71 * This can be empty but if it's non-empty it must be valid CBOR. 72 * 73 * If mdoc session encryption is used (e.g. getEphemeralKeyPair() has been called) 74 * and the SessionTranscript CBOR is not empty, the X and Y coordinates of the public 75 * part of the key-pair previously generated by createEphemeralKeyPair() must appear 76 * somewhere in the bytes of the CBOR. Each of these coordinates must appear encoded 77 * with the most significant bits first and use the exact amount of bits indicated by 78 * the key size of the ephemeral keys. For example, if the ephemeral key is using the 79 * P-256 curve then the 32 bytes for the X coordinate encoded with the most significant 80 * bits first must appear somewhere in the CBOR and ditto for the 32 bytes for the Y 81 * coordinate. If this is not satisfied, the call fails with 82 * STATUS_EPHEMERAL_PUBLIC_KEY_NOT_FOUND. 83 * 84 * This method may only be called once per instance. If called more than once, STATUS_FAILED 85 * must be returned. 86 * 87 * @param sessionTrancsript the session transcript. 88 */ setSessionTranscript(in byte[] sessionTranscript)89 void setSessionTranscript(in byte[] sessionTranscript); 90 91 /** 92 * getCredential() retrieves an IIdentityCredential interface for presentation in the 93 * current presentation session. 94 * 95 * On the returned instance only the methods startRetrieval(), startRetrieveEntryValue(), 96 * retrieveEntryValue(), finishRetrieval(), setRequestedNamespaces(), setVerificationToken() 97 * may be called. Other methods will fail with STATUS_FAILED. 98 * 99 * The implementation is expected to get the session transcript, ephemeral key, reader 100 * ephemeral key, and auth challenge from this instance. 101 * 102 * @param credentialData is a CBOR-encoded structure containing metadata about the credential 103 * and an encrypted byte array that contains data used to secure the credential. See the 104 * return argument of the same name in IWritableIdentityCredential.finishAddingEntries(). 105 * 106 * Note that the format of credentialData may depend on the feature version. 107 * Implementations must support credentialData created by an earlier feature version. 108 * 109 * @return an IIdentityCredential interface that provides operations on the Credential. 110 */ getCredential(in byte[] credentialData)111 IIdentityCredential getCredential(in byte[] credentialData); 112 } 113