identity/java/android/security/identity/CredentialDataResult.java - LeafOS-Project/android_frameworks_base - Gitiles

 /*
  * Copyright 2021 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.security.identity;

 import static java.lang.annotation.RetentionPolicy.SOURCE;

 import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.annotation.Nullable;

 import java.lang.annotation.Retention;
 import java.util.Collection;


 /**
  * An object that contains the result of retrieving data from a credential. This is used to return
  * data requested in a {@link PresentationSession}.
  */
 public abstract class CredentialDataResult {
     /**
      * @hide
      */
     protected CredentialDataResult() {}

     /**
      * Returns a CBOR structure containing the retrieved device-signed data.
      *
      * <p>This structure - along with the session transcript - may be cryptographically
      * authenticated to prove to the reader that the data is from a trusted credential and
      * {@link #getDeviceMac()} can be used to get a MAC.
      *
      * <p>The CBOR structure which is cryptographically authenticated is the
      * {@code DeviceAuthenticationBytes} structure according to the following
      * <a href="https://tools.ietf.org/html/rfc8610">CDDL</a> schema:
      *
      * <pre>
      *   DeviceAuthentication = [
      *     "DeviceAuthentication",
      *     SessionTranscript,
      *     DocType,
      *     DeviceNameSpacesBytes
      *   ]
      *
      *   DocType = tstr
      *   SessionTranscript = any
      *   DeviceNameSpacesBytes = #6.24(bstr .cbor DeviceNameSpaces)
      *   DeviceAuthenticationBytes = #6.24(bstr .cbor DeviceAuthentication)
      * </pre>
      *
      * <p>where
      *
      * <pre>
      *   DeviceNameSpaces = {
      *     * NameSpace => DeviceSignedItems
      *   }
      *
      *   DeviceSignedItems = {
      *     + DataItemName => DataItemValue
      *   }
      *
      *   NameSpace = tstr
      *   DataItemName = tstr
      *   DataItemValue = any
      * </pre>
      *
      * <p>The returned data is the binary encoding of the {@code DeviceNameSpaces} structure
      * as defined above.
      *
      * @return The bytes of the {@code DeviceNameSpaces} CBOR structure.
      */
     public abstract @NonNull byte[] getDeviceNameSpaces();

     /**
      * Returns a message authentication code over the {@code DeviceAuthenticationBytes} CBOR
      * specified in {@link #getDeviceNameSpaces()}, to prove to the reader that the data
      * is from a trusted credential.
      *
      * <p>The MAC proves to the reader that the data is from a trusted credential. This code is
      * produced by using the key agreement and key derivation function from the ciphersuite
      * with the authentication private key and the reader ephemeral public key to compute a
      * shared message authentication code (MAC) key, then using the MAC function from the
      * ciphersuite to compute a MAC of the authenticated data. See section 9.2.3.5 of
      * ISO/IEC 18013-5 for details of this operation.
      *
      * <p>If the session transcript or reader ephemeral key wasn't set on the {@link
      * PresentationSession} used to obtain this data no message authencation code will be produced
      * and this method will return {@code null}.
      *
      * @return A COSE_Mac0 structure with the message authentication code as described above
      *         or {@code null} if the conditions specified above are not met.
      */
     public abstract @Nullable byte[] getDeviceMac();

     /**
      * Returns a signature over the {@code DeviceAuthenticationBytes} CBOR
      * specified in {@link #getDeviceNameSpaces()}, to prove to the reader that the data
      * is from a trusted credential.
      *
      * <p>The signature is made using the authentication private key. See section 9.1.3.4 of
      * ISO/IEC 18013-5:2021 for details of this operation.
      *
      * <p>If the session transcript or reader ephemeral key wasn't set on the {@link
      * PresentationSession} used to obtain this data no signature will be produced and this method
      * will return {@code null}.
      *
      * <p>This is only implemented in feature version 202301 or later. If not implemented, the call
      * fails with {@link UnsupportedOperationException}. See
      * {@link android.content.pm.PackageManager#FEATURE_IDENTITY_CREDENTIAL_HARDWARE} for known
      * feature versions.
      *
      * @return A COSE_Sign1 structure as described above or {@code null} if the conditions
      *     specified above are not met.
      */
     public @Nullable byte[] getDeviceSignature() {
         throw new UnsupportedOperationException();
     }

     /**
      * Returns the static authentication data associated with the dynamic authentication
      * key used to MAC the data returned by {@link #getDeviceNameSpaces()}.
      *
      * @return The static authentication data associated with dynamic authentication key used to
      * MAC the data.
      */
     public abstract @NonNull byte[] getStaticAuthenticationData();

     /**
      * Gets the device-signed entries that was returned.
      *
      * @return an object to examine the entries returned.
      */
     public abstract @NonNull Entries getDeviceSignedEntries();

     /**
      * Gets the issuer-signed entries that was returned.
      *
      * @return an object to examine the entries returned.
      */
     public abstract @NonNull Entries getIssuerSignedEntries();

     /**
      * A class for representing data elements returned.
      */
     public interface Entries {
         /** Value was successfully retrieved. */
         int STATUS_OK = 0;

         /** The entry does not exist. */
         int STATUS_NO_SUCH_ENTRY = 1;

         /** The entry was not requested. */
         int STATUS_NOT_REQUESTED = 2;

         /** The entry wasn't in the request message. */
         int STATUS_NOT_IN_REQUEST_MESSAGE = 3;

         /** The entry was not retrieved because user authentication failed. */
         int STATUS_USER_AUTHENTICATION_FAILED = 4;

         /** The entry was not retrieved because reader authentication failed. */
         int STATUS_READER_AUTHENTICATION_FAILED = 5;

         /**
          * The entry was not retrieved because it was configured without any access
          * control profile.
          */
         int STATUS_NO_ACCESS_CONTROL_PROFILES = 6;

         /**
          * Gets the names of namespaces with retrieved entries.
          *
          * @return collection of name of namespaces containing retrieved entries. May be empty if no
          *     data was retrieved.
          */
         @NonNull Collection<String> getNamespaces();

         /**
          * Get the names of all requested entries in a name space.
          *
          * <p>This includes the name of entries that wasn't successfully retrieved.
          *
          * @param namespaceName the namespace name to get entries for.
          * @return A collection of names for the given namespace or the empty collection if no
          *   entries was returned for the given name space.
          */
         @NonNull Collection<String> getEntryNames(@NonNull String namespaceName);

         /**
          * Get the names of all entries that was successfully retrieved from a name space.
          *
          * <p>This only return entries for which {@link #getStatus(String, String)} will return
          * {@link #STATUS_OK}.
          *
          * @param namespaceName the namespace name to get entries for.
          * @return The entries in the given namespace that were successfully rerieved or the
          *   empty collection if no entries was returned for the given name space.
          */
         @NonNull Collection<String> getRetrievedEntryNames(@NonNull String namespaceName);

         /**
          * Gets the status of an entry.
          *
          * <p>This returns {@link #STATUS_OK} if the value was retrieved, {@link
          * #STATUS_NO_SUCH_ENTRY} if the given entry wasn't retrieved, {@link
          * #STATUS_NOT_REQUESTED} if it wasn't requested, {@link #STATUS_NOT_IN_REQUEST_MESSAGE} if
          * the request message was set but the entry wasn't present in the request message, {@link
          * #STATUS_USER_AUTHENTICATION_FAILED} if the value wasn't retrieved because the necessary
          * user authentication wasn't performed, {@link #STATUS_READER_AUTHENTICATION_FAILED} if
          * the supplied reader certificate chain didn't match the set of certificates the entry was
          * provisioned with, or {@link #STATUS_NO_ACCESS_CONTROL_PROFILES} if the entry was
          * configured without any access control profiles.
          *
          * @param namespaceName the namespace name of the entry.
          * @param name the name of the entry to get the value for.
          * @return the status indicating whether the value was retrieved and if not, why.
          */
         @Status int getStatus(@NonNull String namespaceName, @NonNull String name);

         /**
          * Gets the raw CBOR data for the value of an entry.
          *
          * <p>This should only be called on an entry for which the {@link #getStatus(String,
          * String)} method returns {@link #STATUS_OK}.
          *
          * @param namespaceName the namespace name of the entry.
          * @param name the name of the entry to get the value for.
          * @return the raw CBOR data or {@code null} if no entry with the given name exists.
          */
         @Nullable byte[] getEntry(@NonNull String namespaceName, @NonNull String name);

         /**
          * The type of the entry status.
          * @hide
          */
         @Retention(SOURCE)
         @IntDef({STATUS_OK, STATUS_NO_SUCH_ENTRY, STATUS_NOT_REQUESTED,
                     STATUS_NOT_IN_REQUEST_MESSAGE, STATUS_USER_AUTHENTICATION_FAILED,
                     STATUS_READER_AUTHENTICATION_FAILED, STATUS_NO_ACCESS_CONTROL_PROFILES})
                     @interface Status {}
     }

 }
	/*
	* Copyright 2021 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.security.identity;

	import static java.lang.annotation.RetentionPolicy.SOURCE;

	import android.annotation.IntDef;
	import android.annotation.NonNull;
	import android.annotation.Nullable;

	import java.lang.annotation.Retention;
	import java.util.Collection;


	/**
	* An object that contains the result of retrieving data from a credential. This is used to return
	* data requested in a {@link PresentationSession}.
	*/
	public abstract class CredentialDataResult {
	/**
	* @hide
	*/
	protected CredentialDataResult() {}

	/**
	* Returns a CBOR structure containing the retrieved device-signed data.
	*
	* <p>This structure - along with the session transcript - may be cryptographically
	* authenticated to prove to the reader that the data is from a trusted credential and
	* {@link #getDeviceMac()} can be used to get a MAC.
	*
	* <p>The CBOR structure which is cryptographically authenticated is the
	* {@code DeviceAuthenticationBytes} structure according to the following
	* <a href="https://tools.ietf.org/html/rfc8610">CDDL</a> schema:
	*
	* <pre>
	* DeviceAuthentication = [
	* "DeviceAuthentication",
	* SessionTranscript,
	* DocType,
	* DeviceNameSpacesBytes
	* ]
	*
	* DocType = tstr
	* SessionTranscript = any
	* DeviceNameSpacesBytes = #6.24(bstr .cbor DeviceNameSpaces)
	* DeviceAuthenticationBytes = #6.24(bstr .cbor DeviceAuthentication)
	* </pre>
	*
	* <p>where
	*
	* <pre>
	* DeviceNameSpaces = {
	* * NameSpace => DeviceSignedItems
	* }
	*
	* DeviceSignedItems = {
	* + DataItemName => DataItemValue
	* }
	*
	* NameSpace = tstr
	* DataItemName = tstr
	* DataItemValue = any
	* </pre>
	*
	* <p>The returned data is the binary encoding of the {@code DeviceNameSpaces} structure
	* as defined above.
	*
	* @return The bytes of the {@code DeviceNameSpaces} CBOR structure.
	*/
	public abstract @NonNull byte[] getDeviceNameSpaces();

	/**
	* Returns a message authentication code over the {@code DeviceAuthenticationBytes} CBOR
	* specified in {@link #getDeviceNameSpaces()}, to prove to the reader that the data
	* is from a trusted credential.
	*
	* <p>The MAC proves to the reader that the data is from a trusted credential. This code is
	* produced by using the key agreement and key derivation function from the ciphersuite
	* with the authentication private key and the reader ephemeral public key to compute a
	* shared message authentication code (MAC) key, then using the MAC function from the
	* ciphersuite to compute a MAC of the authenticated data. See section 9.2.3.5 of
	* ISO/IEC 18013-5 for details of this operation.
	*
	* <p>If the session transcript or reader ephemeral key wasn't set on the {@link
	* PresentationSession} used to obtain this data no message authencation code will be produced
	* and this method will return {@code null}.
	*
	* @return A COSE_Mac0 structure with the message authentication code as described above
	* or {@code null} if the conditions specified above are not met.
	*/
	public abstract @Nullable byte[] getDeviceMac();

	/**
	* Returns a signature over the {@code DeviceAuthenticationBytes} CBOR
	* specified in {@link #getDeviceNameSpaces()}, to prove to the reader that the data
	* is from a trusted credential.
	*
	* <p>The signature is made using the authentication private key. See section 9.1.3.4 of
	* ISO/IEC 18013-5:2021 for details of this operation.
	*
	* <p>If the session transcript or reader ephemeral key wasn't set on the {@link
	* PresentationSession} used to obtain this data no signature will be produced and this method
	* will return {@code null}.
	*
	* <p>This is only implemented in feature version 202301 or later. If not implemented, the call
	* fails with {@link UnsupportedOperationException}. See
	* {@link android.content.pm.PackageManager#FEATURE_IDENTITY_CREDENTIAL_HARDWARE} for known
	* feature versions.
	*
	* @return A COSE_Sign1 structure as described above or {@code null} if the conditions
	* specified above are not met.
	*/
	public @Nullable byte[] getDeviceSignature() {
	throw new UnsupportedOperationException();
	}

	/**
	* Returns the static authentication data associated with the dynamic authentication
	* key used to MAC the data returned by {@link #getDeviceNameSpaces()}.
	*
	* @return The static authentication data associated with dynamic authentication key used to
	* MAC the data.
	*/
	public abstract @NonNull byte[] getStaticAuthenticationData();

	/**
	* Gets the device-signed entries that was returned.
	*
	* @return an object to examine the entries returned.
	*/
	public abstract @NonNull Entries getDeviceSignedEntries();

	/**
	* Gets the issuer-signed entries that was returned.
	*
	* @return an object to examine the entries returned.
	*/
	public abstract @NonNull Entries getIssuerSignedEntries();

	/**
	* A class for representing data elements returned.
	*/
	public interface Entries {
	/** Value was successfully retrieved. */
	int STATUS_OK = 0;

	/** The entry does not exist. */
	int STATUS_NO_SUCH_ENTRY = 1;

	/** The entry was not requested. */
	int STATUS_NOT_REQUESTED = 2;

	/** The entry wasn't in the request message. */
	int STATUS_NOT_IN_REQUEST_MESSAGE = 3;

	/** The entry was not retrieved because user authentication failed. */
	int STATUS_USER_AUTHENTICATION_FAILED = 4;

	/** The entry was not retrieved because reader authentication failed. */
	int STATUS_READER_AUTHENTICATION_FAILED = 5;

	/**
	* The entry was not retrieved because it was configured without any access
	* control profile.
	*/
	int STATUS_NO_ACCESS_CONTROL_PROFILES = 6;

	/**
	* Gets the names of namespaces with retrieved entries.
	*
	* @return collection of name of namespaces containing retrieved entries. May be empty if no
	* data was retrieved.
	*/
	@NonNull Collection<String> getNamespaces();

	/**
	* Get the names of all requested entries in a name space.
	*
	* <p>This includes the name of entries that wasn't successfully retrieved.
	*
	* @param namespaceName the namespace name to get entries for.
	* @return A collection of names for the given namespace or the empty collection if no
	* entries was returned for the given name space.
	*/
	@NonNull Collection<String> getEntryNames(@NonNull String namespaceName);

	/**
	* Get the names of all entries that was successfully retrieved from a name space.
	*
	* <p>This only return entries for which {@link #getStatus(String, String)} will return
	* {@link #STATUS_OK}.
	*
	* @param namespaceName the namespace name to get entries for.
	* @return The entries in the given namespace that were successfully rerieved or the
	* empty collection if no entries was returned for the given name space.
	*/
	@NonNull Collection<String> getRetrievedEntryNames(@NonNull String namespaceName);

	/**
	* Gets the status of an entry.
	*
	* <p>This returns {@link #STATUS_OK} if the value was retrieved, {@link
	* #STATUS_NO_SUCH_ENTRY} if the given entry wasn't retrieved, {@link
	* #STATUS_NOT_REQUESTED} if it wasn't requested, {@link #STATUS_NOT_IN_REQUEST_MESSAGE} if
	* the request message was set but the entry wasn't present in the request message, {@link
	* #STATUS_USER_AUTHENTICATION_FAILED} if the value wasn't retrieved because the necessary
	* user authentication wasn't performed, {@link #STATUS_READER_AUTHENTICATION_FAILED} if
	* the supplied reader certificate chain didn't match the set of certificates the entry was
	* provisioned with, or {@link #STATUS_NO_ACCESS_CONTROL_PROFILES} if the entry was
	* configured without any access control profiles.
	*
	* @param namespaceName the namespace name of the entry.
	* @param name the name of the entry to get the value for.
	* @return the status indicating whether the value was retrieved and if not, why.
	*/
	@Status int getStatus(@NonNull String namespaceName, @NonNull String name);

	/**
	* Gets the raw CBOR data for the value of an entry.
	*
	* <p>This should only be called on an entry for which the {@link #getStatus(String,
	* String)} method returns {@link #STATUS_OK}.
	*
	* @param namespaceName the namespace name of the entry.
	* @param name the name of the entry to get the value for.
	* @return the raw CBOR data or {@code null} if no entry with the given name exists.
	*/
	@Nullable byte[] getEntry(@NonNull String namespaceName, @NonNull String name);

	/**
	* The type of the entry status.
	* @hide
	*/
	@Retention(SOURCE)
	@IntDef({STATUS_OK, STATUS_NO_SUCH_ENTRY, STATUS_NOT_REQUESTED,
	STATUS_NOT_IN_REQUEST_MESSAGE, STATUS_USER_AUTHENTICATION_FAILED,
	STATUS_READER_AUTHENTICATION_FAILED, STATUS_NO_ACCESS_CONTROL_PROFILES})
	@interface Status {}
	}

	}