1 /*
2  * Copyright (C) 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.security.attestationverification;
18 
19 import android.annotation.CheckResult;
20 import android.annotation.NonNull;
21 import android.app.Service;
22 import android.os.Bundle;
23 import android.security.attestationverification.AttestationVerificationManager.VerificationResult;
24 
25 /**
26  * A verifier which can be implemented by apps to verify an attestation (as described in {@link
27  * AttestationVerificationManager}).
28  *
29  * In the manifest for this service, specify the profile and local binding type this verifier
30  * supports. Create a new service for each combination of profile & local binding type that your app
31  * supports. Each service must declare an {@code intent-filter} action of {@link #SERVICE_INTERFACE}
32  * and permission of {@link android.Manifest.permission#BIND_ATTESTATION_VERIFICATION_SERVICE}.
33  *
34  * <p>Example:
35  * {@code
36  * <pre>
37  * <service android:name=".MyAttestationVerificationService"
38  *          android:permission="android.permission.BIND_ATTESTATION_VERIFICATION_SERVICE"
39  *          android:exported="true">
40  *   <intent-filter>
41  *     <action
42  *         android:name="android.security.attestationverification.AttestationVerificationService" />
43  *   </intent-filter>
44  *   <meta-data android:name="android.security.attestationverification.PROFILE_ID"
45  *              android:value="PROFILE_PLACEHOLDER_0" />
46  *   <meta-data android:name="android.security.attestationverification.LOCAL_BINDING_TYPE"
47  *              android:value="TYPE_PLACEHOLDER_0" />
48  * </service>
49  * </pre>
50  * }
51  *
52  * <p>For app-defined profiles, an example of the {@code <meta-data>}:
53  * {@code
54  * <pre>
55  *   <meta-data android:name="android.security.attestation.PROFILE_PACKAGE_NAME"
56  *              android:value="com.example" />
57  *   <meta-data android:name="android.security.attestation.PROFILE_NAME"
58  *              android:value="com.example.profile.PROFILE_FOO" />
59  * </pre>
60  * }
61  *
62  * @hide
63  */
64 public abstract class AttestationVerificationService extends Service {
65 
66     /**
67      * An intent action for a service to be bound and act as an attestation verifier.
68      *
69      * <p>The app will be kept alive for a short duration between verification calls after which
70      * the system will unbind from this service making the app eligible for cleanup.
71      *
72      * <p>The service must also require permission
73      * {@link android.Manifest.permission#BIND_ATTESTATION_VERIFICATION_SERVICE}.
74      */
75     public static final String SERVICE_INTERFACE =
76             "android.security.attestationverification.AttestationVerificationService";
77 
78     /**
79      * Verifies that {@code attestation} attests that the device identified by the local binding
80      * data in {@code requirements} meets the minimum requirements of this verifier for this
81      * verifier's profile.
82      *
83      * <p>Called by the system to verify an attestation.
84      *
85      * <p>The data passed into this method comes directly from apps and should be treated as
86      * potentially dangerous user input.
87      *
88      * @param requirements a {@link Bundle} containing locally-known data which must match {@code
89      *                     attestation}
90      * @param attestation  the attestation to verify
91      * @return whether the verification passed
92      * @see AttestationVerificationManager#verifyAttestation(AttestationProfile, int, Bundle,
93      * byte[], java.util.concurrent.Executor, java.util.function.BiConsumer)
94      */
95     @CheckResult
96     @VerificationResult
onVerifyPeerDeviceAttestation( @onNull Bundle requirements, @NonNull byte[] attestation)97     public abstract int onVerifyPeerDeviceAttestation(
98             @NonNull Bundle requirements,
99             @NonNull byte[] attestation);
100 }
101