src.android.security.identity.ResultData Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright 2020 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 from a {@link IdentityCredential}.
*
* @deprecated Use {@link PresentationSession} instead.
*/
@Deprecated
public abstract class ResultData {
/** Value was successfully retrieved. */
public static final int STATUS_OK = 0;
/** The entry does not exist. */
public static final int STATUS_NO_SUCH_ENTRY = 1;
/** The entry was not requested. */
public static final int STATUS_NOT_REQUESTED = 2;
/** The entry wasn't in the request message. */
public static final int STATUS_NOT_IN_REQUEST_MESSAGE = 3;
/** The entry was not retrieved because user authentication failed. */
public static final int STATUS_USER_AUTHENTICATION_FAILED = 4;
/** The entry was not retrieved because reader authentication failed. */
public static final int STATUS_READER_AUTHENTICATION_FAILED = 5;
/**
* The entry was not retrieved because it was configured without any access
* control profile.
*/
public static final int STATUS_NO_ACCESS_CONTROL_PROFILES = 6;
/**
* @hide
*/
protected ResultData() {}
/**
* Returns a CBOR structure containing the retrieved data.
*
* 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 #getMessageAuthenticationCode()} can be used to get a MAC.
*
*
The CBOR structure which is cryptographically authenticated is the
* {@code DeviceAuthenticationBytes} structure according to the following
* CDDL schema:
*
*
* DeviceAuthentication = [
* "DeviceAuthentication",
* SessionTranscript,
* DocType,
* DeviceNameSpacesBytes
* ]
*
* DocType = tstr
* SessionTranscript = any
* DeviceNameSpacesBytes = #6.24(bstr .cbor DeviceNameSpaces)
* DeviceAuthenticationBytes = #6.24(bstr .cbor DeviceAuthentication)
*
*
* where
*
*
* DeviceNameSpaces = {
* * NameSpace => DeviceSignedItems
* }
*
* DeviceSignedItems = {
* + DataItemName => DataItemValue
* }
*
* NameSpace = tstr
* DataItemName = tstr
* DataItemValue = any
*
*
* 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[] getAuthenticatedData();
/**
* Returns a message authentication code over the {@code DeviceAuthenticationBytes} CBOR
* specified in {@link #getAuthenticatedData()}, to prove to the reader that the data
* is from a trusted credential.
*
*
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.
*
*
If the {@code sessionTranscript} parameter passed to
* {@link IdentityCredential#getEntries(byte[], Map, byte[], byte[])} was {@code null}
* or the reader ephmeral public key was never set using
* {@link IdentityCredential#setReaderEphemeralPublicKey(PublicKey)}, 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[] getMessageAuthenticationCode();
/**
* Returns the static authentication data associated with the dynamic authentication
* key used to sign or MAC the data returned by {@link #getAuthenticatedData()}.
*
* @return The static authentication data associated with dynamic authentication key used to
* MAC the data.
*/
public abstract @NonNull byte[] getStaticAuthenticationData();
/**
* 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.
*/
public abstract @NonNull Collection getNamespaces();
/**
* Get the names of all entries.
*
* 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 or {@code null} if there are no entries for the given
* namespace.
*/
public abstract @Nullable Collection getEntryNames(@NonNull String namespaceName);
/**
* Get the names of all entries that was successfully retrieved.
*
* 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 A collection of names or {@code null} if there are no entries for the given
* namespace.
*/
public abstract @Nullable Collection getRetrievedEntryNames(
@NonNull String namespaceName);
/**
* Gets the status of an entry.
*
* 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.
*/
public abstract @Status int getStatus(@NonNull String namespaceName, @NonNull String name);
/**
* Gets the raw CBOR data for the value of an entry.
*
*
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.
*/
public abstract @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})
public @interface Status {
}
}