roboto/at.asitplus.attestation.android/AndroidAttestationConfiguration

AndroidAttestationConfiguration

@Serializable

data class AndroidAttestationConfiguration @JvmOverloads constructor(val applications: List<AndroidAttestationConfiguration.AppData>, val androidVersion: Int? = null, val patchLevel: PatchLevel? = null, val requireStrongBox: Boolean = false, val allowBootloaderUnlock: Boolean = false, val requireRollbackResistance: Boolean = false, val ignoreLeafValidity: Boolean = true, val verificationSecondsOffset: Long = 0, val attestationStatementValiditySeconds: Long? = null, val hardwareTrustedRoots: Set<TrustedRoot> = GOOGLE_DEFAULT_HARDWARE_TRUST_ANCHORS, val softwareTrustedRoots: Set<TrustedRoot> = GOOGLE_SOFTWARE_TRUST_ANCHORS_UNTIL_A12, val disableHardwareAttestation: Boolean = false, val enableSoftwareAttestation: Boolean = false, val requireRemoteKeyProvisioning: Boolean = false, val revocation: List<AndroidRevocationList.Loader.Configuration<*>> = listOf(AndroidRevocationList.GoogleDefaultLoaderConfig)) : AttestationConfiguration(source)

Main Android attestation configuration class serving as ground truth for all key and app attestation verifications.

Parameters

applications

list of applications to be attested

androidVersion

optional parameter. If set, attestation enforces Android version to be greater or equal to this parameter. Caution: Major Android versions increment in steps of ten-thousands. I.e. Android 11 is specified as 110000 Can be overridden for individual apps

patchLevel

optional parameter. If set, attestation enforces Security patch level to be greater or equal to this parameter

requireStrongBox

optional parameter. Set to true if StrongBox security level should be required

allowBootloaderUnlock

optional parameter. Set to true if unlocked bootloaders should be allowed. Attention: Allowing unlocked bootloaders in production effectively defeats the purpose of app attestation. (but retains the ability to attest whether a key is securely stored in hardware) Useful for debugging/testing

requireRollbackResistance

optional parameter. Unsupported by most devices. See Official Documentation

ignoreLeafValidity

optional parameter. Whether to ignore the timely validity of the leaf certificate (looking at you, Samsung!)

hardwareTrustedRoots

Manually specify the trust anchor for HW-attested certificate chains. Defaults to google HW attestation key. Overriding this set is useful for automated end-to-end tests, for example. The default trust anchors are accessible through GOOGLE_DEFAULT_HARDWARE_TRUST_ANCHORS

softwareTrustedRoots

Manually specify the trust anchor for SW-attested certificate chains. Defaults to google SW attestation keys. Overriding this set is useful for automated end-to-end tests, for example. The default trust anchors are accessible through GOOGLE_SOFTWARE_TRUST_ANCHORS_UNTIL_A12

disableHardwareAttestation

Entirely disable creation of a HardwareAttestationVerifier. Only change this flag, if you really know what you are doing!

enableSoftwareAttestation

Enables software attestation. A SoftwareAttestationVerifier can only be instantiated if this flag is set to true. Only change this flag, if you really know what you are doing! Enabling this flag, while keeping disableHardwareAttestation true makes is possible to instantiate both a HardwareAttestationVerifier and a SoftwareAttestationVerifier.

Constructors

AndroidAttestationConfiguration

@JvmOverloads

constructor(applications: List<AndroidAttestationConfiguration.AppData>, androidVersion: Int? = null, patchLevel: PatchLevel? = null, requireStrongBox: Boolean = false, allowBootloaderUnlock: Boolean = false, requireRollbackResistance: Boolean = false, ignoreLeafValidity: Boolean = true, verificationSecondsOffset: Long = 0, attestationStatementValiditySeconds: Long? = null, hardwareTrustedRoots: Set<TrustedRoot> = GOOGLE_DEFAULT_HARDWARE_TRUST_ANCHORS, softwareTrustedRoots: Set<TrustedRoot> = GOOGLE_SOFTWARE_TRUST_ANCHORS_UNTIL_A12, disableHardwareAttestation: Boolean = false, enableSoftwareAttestation: Boolean = false, requireRemoteKeyProvisioning: Boolean = false, revocation: List<AndroidRevocationList.Loader.Configuration<*>> = listOf(AndroidRevocationList.GoogleDefaultLoaderConfig))

constructor(singleApp: AndroidAttestationConfiguration.AppData, androidVersion: Int? = null, patchLevel: PatchLevel? = null, requireStrongBox: Boolean = false, allowBootloaderUnlock: Boolean = false, requireRollbackResistance: Boolean = false, ignoreLeafValidity: Boolean = true, verificationSecondsOffset: Long = 0, attestationStatementValiditySeconds: Long? = null, hardwareTrustedRoots: Set<TrustedRoot> = GOOGLE_DEFAULT_HARDWARE_TRUST_ANCHORS, softwareTrustedRoots: Set<TrustedRoot> = GOOGLE_SOFTWARE_TRUST_ANCHORS_UNTIL_A12, disableHardwareAttestation: Boolean = false, enableSoftwareAttestation: Boolean = false, revocation: List<AndroidRevocationList.Loader.Configuration<*>> = listOf(AndroidRevocationList.GoogleDefaultLoaderConfig), requireRemoteKeyProvisioning: Boolean = false)

Convenience constructor to attest a single app

constructor(version: Int? = null, patchLevel: PatchLevel? = null, requireStrongBox: Boolean = false, allowBootloaderUnlock: Boolean = false, requireRollbackResistance: Boolean = false, ignoreLeafValidity: Boolean = true, verificationSecondsOffset: Long = 0, attestationStatementValiditySeconds: Long? = null, disableHardwareAttestation: Boolean = false, enableSoftwareAttestation: Boolean = false, hardwareTrustedRoots: Set<ByteArray> = GOOGLE_DEFAULT_HARDWARE_TRUST_ANCHORS.map { it.derEncoded }.toSet(), softwareTrustedRoots: Set<ByteArray> = GOOGLE_SOFTWARE_TRUST_ANCHORS_UNTIL_A12.map { it.derEncoded }.toSet(), apps: List<AndroidAttestationConfiguration.AppData>, revocation: List<AndroidRevocationList.Loader.Configuration<*>> = listOf(AndroidRevocationList.GoogleDefaultLoaderConfig), requireRemoteKeyProvisioning: Boolean = false)

Constructor used when loading this class from a config file through Hoplite

Types

AppData

@Serializable

data class AppData @JvmOverloads constructor(val packageName: String, val signerFingerprints: List<@Serializable(with = ByteArrayBase64UrlSerializer::class) ByteArray>, val appVersion: Int? = null, val androidVersionOverride: Int? = null, patchLevelOverride: PatchLevel? = null, val requireRemoteKeyProvisioningOverride: Boolean? = null, val trustedRootOverrides: Set<TrustedRoot>? = null, val requireStrongBoxOverride: Boolean? = null)

Specifies a to-be attested app

Builder

class Builder(applications: List<AndroidAttestationConfiguration.AppData>)

Builder to construct an AndroidAttestationConfiguration in a java-friendly way

Companion

object Companion : AttestationConfiguration.Reader<AndroidAttestationConfiguration>

Properties

allowBootloaderUnlock

val allowBootloaderUnlock: Boolean

Set to true if unlocked bootloaders should be allowed. Attention: Allowing unlocked bootloaders in production effectively defeats the purpose of Key Attestation. Useful for debugging/testing BEWARE that this switch is utterly useless if SoftwareAttestationVerifier is used

androidVersion

val androidVersion: Int?

applications

val applications: List<AndroidAttestationConfiguration.AppData>

List of applications which can be attested

attestationStatementValiditySeconds

val attestationStatementValiditySeconds: Long?

Validity of the attestation statement in seconds. This is not the certificate validity! An attestation statement has a creation time. This value indicates how far in the past the creation time might be.

disableHardwareAttestation

val disableHardwareAttestation: Boolean

Entirely disable creation of a HardwareAttestationVerifier. Only change this flag, if you really know what you are doing!

enableSoftwareAttestation

val enableSoftwareAttestation: Boolean

hardwareTrustedRoots

val hardwareTrustedRoots: Set<TrustedRoot>

ignoreLeafValidity

val ignoreLeafValidity: Boolean

Whether to ignore the timely validity of the leaf certificate

osPatchLevel

val osPatchLevel: Int?

Internal representation of the patch level as contained in the com.google.android.attestation.ParsedAttestationRecord

patchLevel

val patchLevel: PatchLevel?

optional parameter. If set, attestation enforces Security patch level to be greater or equal to this parameter. Can be overridden for individual apps.

requireRemoteKeyProvisioning

val requireRemoteKeyProvisioning: Boolean

Mandates Remote Key Provisioning (RKP) for attestation checks to pass

requireRollbackResistance

val requireRollbackResistance: Boolean

Unsupported by most devices. See Official Documentation

requireStrongBox

val requireStrongBox: Boolean

Set to true if StrongBox security level should be required. BEWARE that this switch is utterly useless if SoftwareAttestationVerifier is used

revocation

val revocation: List<AndroidRevocationList.Loader.Configuration<*>>

Configures revocation checking. Defaults to checking against the official Google revocation list without Proxy.

softwareTrustedRoots

val softwareTrustedRoots: Set<TrustedRoot>

verificationSecondsOffset

val verificationSecondsOffset: Long

Tolerance in seconds added to verification date

Functions

equals

open operator override fun equals(other: Any?): Boolean

hashCode

open override fun hashCode(): Int

toJsonElement

open override fun toJsonElement(): JsonObject

Serialises this config into a JsonObject. Can be loaded using fromJsonObject afterwards.

toJsonFile

fun AttestationConfiguration.toJsonFile(file: File)

fun AttestationConfiguration.toJsonFile(path: String)

Writes the JSON representation of this AttestationConfiguration to the specified file.

toJsonString

open override fun toJsonString(): String

Serialises this config into its canonical form (JSON). Can be loaded using fromJsonString afterwards.

toString

open override fun toString(): String

toYamlFile

fun AttestationConfiguration.toYamlFile(file: File)

fun AttestationConfiguration.toYamlFile(path: String)

Serializes this AttestationConfiguration instance to a YAML-formatted string and writes it to the specified file.

toYamlString

open override fun toYamlString(): String

Serialises this config into its canonical form (YAML). Can be loaded using fromYamlString afterwards.