public abstract class ResultData

An object that contains the result of retrieving data from a credential. This is used to return data requested from a IdentityCredential.

Summary

Constants
static final int

Requested entry wasn't in the request message.
static final int

Requested entry was not requested.
static final int

The requested entry was not retrieved because it was configured without any access control profile.
static final int

Requested entry does not exist.
static final int

Value was successfully retrieved.
static final int

The requested entry was not retrieved because reader authentication wasn't performed.
static final int

The requested entry was not retrieved because user authentication wasn't performed.

Public methods
abstract @NonNull byte[]

Returns a CBOR structure containing the retrieved data.
abstract @Nullable byte[]

Returns a digital signature over the DeviceAuthenticationBytes CBOR specified in getAuthenticatedData, to prove to the reader that the data is from a trusted credential.
abstract @Nullable byte[]
getEntry(@NonNull String namespaceName, @NonNull String name)

Gets the raw CBOR data for the value of an entry.
boolean
getEntryBoolean(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry.
@Nullable byte[]
getEntryBytestring(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry.
@Nullable Calendar
getEntryCalendar(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry.
long
getEntryInteger(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry.
abstract @Nullable Collection<String>
getEntryNames(@NonNull String namespaceName)

Get the names of all entries.
@Nullable String
getEntryString(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry.
abstract @Nullable byte[]

Returns a message authentication code over the DeviceAuthenticationBytes CBOR specified in getAuthenticatedData, to prove to the reader that the data is from a trusted credential.
abstract @NonNull Collection<String>

Gets the names of namespaces with retrieved entries.
abstract @Nullable Collection<String>

Get the names of all entries that was successfully retrieved.
abstract @NonNull byte[]

Returns the static authentication data associated with the dynamic authentication key used to sign or MAC the data returned by getAuthenticatedData.
abstract int
getStatus(@NonNull String namespaceName, @NonNull String name)

Gets the status of an entry.

Constants

STATUS_NOT_IN_REQUEST_MESSAGE

Added in 1.0.0-alpha04
public static final int STATUS_NOT_IN_REQUEST_MESSAGE = 3

Requested entry wasn't in the request message.

STATUS_NOT_REQUESTED

Added in 1.0.0-alpha04
public static final int STATUS_NOT_REQUESTED = 2

Requested entry was not requested.

STATUS_NO_ACCESS_CONTROL_PROFILES

Added in 1.0.0-alpha04
public static final int STATUS_NO_ACCESS_CONTROL_PROFILES = 6

The requested entry was not retrieved because it was configured without any access control profile.

STATUS_NO_SUCH_ENTRY

Added in 1.0.0-alpha04
public static final int STATUS_NO_SUCH_ENTRY = 1

Requested entry does not exist.

STATUS_OK

Added in 1.0.0-alpha04
public static final int STATUS_OK = 0

Value was successfully retrieved.

STATUS_READER_AUTHENTICATION_FAILED

Added in 1.0.0-alpha04
public static final int STATUS_READER_AUTHENTICATION_FAILED = 5

The requested entry was not retrieved because reader authentication wasn't performed.

STATUS_USER_AUTHENTICATION_FAILED

Added in 1.0.0-alpha04
public static final int STATUS_USER_AUTHENTICATION_FAILED = 4

The requested entry was not retrieved because user authentication wasn't performed.

Public methods

getAuthenticatedData

Added in 1.0.0-alpha04
public abstract @NonNull byte[] getAuthenticatedData()

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 getMessageAuthenticationCode can be used to get a MAC.

The CBOR structure which is cryptographically authenticated is the 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 DeviceNameSpaces structure as defined above.

Returns
@NonNull byte[]

The bytes of the DeviceNameSpaces CBOR structure.

getEcdsaSignature

Added in 1.0.0-alpha04
public abstract @Nullable byte[] getEcdsaSignature()

Returns a digital signature over the DeviceAuthenticationBytes CBOR specified in getAuthenticatedData, to prove to the reader that the data is from a trusted credential. The signature will be made with one of the provisioned dynamic authentication keys. At most one of getMessageAuthenticationCode or getEcdsaSignature is implemented.

Returns
@Nullable byte[]

null if not implemented, otherwise a COSE_Sign1 structure with the payload set to the data returned by getAuthenticatedData.

getEntry

Added in 1.0.0-alpha04
public abstract @Nullable byte[] getEntry(@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 getStatus method returns STATUS_OK.

Parameters
@NonNull String namespaceName

the namespace name of the entry.
@NonNull String name

the name of the entry to get the value for.
Returns
@Nullable byte[]

the raw CBOR data or null if no entry with the given name exists.

getEntryBoolean

Added in 1.0.0-alpha04
public boolean getEntryBoolean(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry. This should only be called on an entry for which the getStatus method returns STATUS_OK.

Parameters
@NonNull String namespaceName

the namespace name of the entry.
@NonNull String name

the name of the entry to get the value for.
Returns
boolean

a boolean or false if no entry with the given name exists.

getEntryBytestring

Added in 1.0.0-alpha04
public @Nullable byte[] getEntryBytestring(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry. This should only be called on an entry for which the getStatus method returns STATUS_OK.

Parameters
@NonNull String namespaceName

the namespace name of the entry.
@NonNull String name

the name of the entry to get the value for.
Returns
@Nullable byte[]

a byte[] or null if no entry with the given name exists.

getEntryCalendar

Added in 1.0.0-alpha04
public @Nullable Calendar getEntryCalendar(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry. This should only be called on an entry for which the getStatus method returns STATUS_OK.

Parameters
@NonNull String namespaceName

the namespace name of the entry.
@NonNull String name

the name of the entry to get the value for.
Returns
@Nullable Calendar

a Calendar or null if no entry with the given name exists.

getEntryInteger

Added in 1.0.0-alpha04
public long getEntryInteger(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry. This should only be called on an entry for which the getStatus method returns STATUS_OK.

Parameters
@NonNull String namespaceName

the namespace name of the entry.
@NonNull String name

the name of the entry to get the value for.
Returns
long

a long or 0 if no entry with the given name exists.

getEntryNames

Added in 1.0.0-alpha04
public abstract @Nullable Collection<String> getEntryNames(@NonNull String namespaceName)

Get the names of all entries. This includes the name of entries that wasn't successfully retrieved.

Parameters
@NonNull String namespaceName

the namespace name to get entries for.
Returns
@Nullable Collection<String>

A collection of names or null if there are no entries for the given namespace.

getEntryString

Added in 1.0.0-alpha04
public @Nullable String getEntryString(@NonNull String namespaceName, @NonNull String name)

Gets the value of an entry. This should only be called on an entry for which the getStatus method returns STATUS_OK.

Parameters
@NonNull String namespaceName

the namespace name of the entry.
@NonNull String name

the name of the entry to get the value for.
Returns
@Nullable String

a String or null if no entry with the given name exists.

getMessageAuthenticationCode

Added in 1.0.0-alpha04
public abstract @Nullable byte[] getMessageAuthenticationCode()

Returns a message authentication code over the DeviceAuthenticationBytes CBOR specified in 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 sessionTranscript parameter passed to getEntries was null or the reader ephmeral public key was never set using setReaderEphemeralPublicKey, no message authencation code will be produced and this method will return null. At most one of getMessageAuthenticationCode or getEcdsaSignature is implemented.

Returns
@Nullable byte[]

A COSE_Mac0 structure with the message authentication code as described above or null if the conditions specified above are not met.

getNamespaces

Added in 1.0.0-alpha04
public abstract @NonNull Collection<String> getNamespaces()

Gets the names of namespaces with retrieved entries.

Returns
@NonNull Collection<String>

collection of name of namespaces containing retrieved entries. May be empty if no data was retrieved.

getRetrievedEntryNames

Added in 1.0.0-alpha04
public abstract @Nullable Collection<String> getRetrievedEntryNames(@NonNull String namespaceName)

Get the names of all entries that was successfully retrieved. This only return entries for which getStatus will return STATUS_OK.

Parameters
@NonNull String namespaceName

the namespace name to get entries for.
Returns
@Nullable Collection<String>

A collection of names or null if there are no entries for the given namespace.

getStaticAuthenticationData

Added in 1.0.0-alpha04
public abstract @NonNull byte[] getStaticAuthenticationData()

Returns the static authentication data associated with the dynamic authentication key used to sign or MAC the data returned by getAuthenticatedData.

Returns
@NonNull byte[]

The static authentication data associated with dynamic authentication key used to MAC the data.

getStatus

Added in 1.0.0-alpha04
public abstract int getStatus(@NonNull String namespaceName, @NonNull String name)

Gets the status of an entry. This returns STATUS_OK if the value was retrieved, STATUS_NO_SUCH_ENTRY if the given entry wasn't retrieved, STATUS_NOT_REQUESTED if it wasn't requested, STATUS_NOT_IN_REQUEST_MESSAGE if the request message was set but the entry wasn't present in the request message, STATUS_USER_AUTHENTICATION_FAILED if the value wasn't retrieved because the necessary user authentication wasn't performed, STATUS_READER_AUTHENTICATION_FAILED if the supplied reader certificate chain didn't match the set of certificates the entry was provisioned with, or STATUS_NO_ACCESS_CONTROL_PROFILES if the entry was configured without any access control profiles.

Parameters
@NonNull String namespaceName

the namespace name of the entry.
@NonNull String name

the name of the entry to get the value for.
Returns
int

the status indicating whether the value was retrieved and if not, why.