roboto/at.asitplus.attestation.android/AndroidAttestationConfiguration

AndroidAttestationConfiguration

@Serializable

data class AndroidAttestationConfiguration @JvmOverloads constructor(val applications: List<AndroidAttestationConfiguration.AppData>, val androidVersion: Int? = null, patchLevel: PatchLevel? = null, val requireStrongBox: Boolean = false, val allowBootloaderUnlock: Boolean = false, val requireRollbackResistance: Boolean = false, val ignoreLeafValidity: Boolean = false, val hardwareAttestationTrustAnchors: Set<@Serializable(with = PubKeyBasePemSerializer::class) PublicKey> = linkedSetOf(*DEFAULT_HARDWARE_TRUST_ANCHORS), val softwareAttestationTrustAnchors: Set<@Serializable(with = PubKeyBasePemSerializer::class) PublicKey> = linkedSetOf(*DEFAULT_SOFTWARE_TRUST_ANCHORS), val verificationSecondsOffset: Long = 0, val attestationStatementValiditySeconds: Long? = 5 * 60, val disableHardwareAttestation: Boolean = false, val enableNougatAttestation: Boolean = false, val enableSoftwareAttestation: Boolean = false, val requireRemoteKeyProvisioning: Boolean = false, val httpProxy: String? = null)(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!)

hardwareAttestationTrustAnchors

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 DEFAULT_HARDWARE_TRUST_ANCHORS

softwareAttestationTrustAnchors

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 DEFAULT_SOFTWARE_TRUST_ANCHORS

disableHardwareAttestation

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

enableNougatAttestation

Enables hybrid attestation. NougatHybridAttestationChecker can only be instantiated if this flag is set to true. Only change this flag, if you require support for devices, which originally shipped with Android 7 (Nougat), as these devices only support hardware-backed key attestation, but provide no indication about the OS state. Hence, app-attestation cannot be trusted, but key attestation still can.

enableSoftwareAttestation

Enables software attestation. A SoftwareAttestationChecker 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 HardwareAttestationChecker and a SoftwareAttestationChecker.

Constructors

AndroidAttestationConfiguration

constructor(singleApp: AndroidAttestationConfiguration.AppData, androidVersion: Int? = null, patchLevel: PatchLevel? = null, requireStrongBox: Boolean = false, allowBootloaderUnlock: Boolean = false, requireRollbackResistance: Boolean = false, ignoreLeafValidity: Boolean = false, hardwareAttestationTrustAnchors: Set<PublicKey> = linkedSetOf(*DEFAULT_HARDWARE_TRUST_ANCHORS), softwareAttestationTrustAnchors: Set<PublicKey> = linkedSetOf(*DEFAULT_SOFTWARE_TRUST_ANCHORS), verificationSecondsOffset: Long = 0, attestationStatementValiditySeconds: Long? = 5 * 60, disableHardwareAttestation: Boolean = false, enableNougatAttestation: Boolean = false, enableSoftwareAttestation: Boolean = false, httpProxy: String? = null, 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 = false, verificationSecondsOffset: Long = 0, attestationStatementValiditySeconds: Long? = 5 * 60, disableHardwareAttestation: Boolean = false, enableNougatAttestation: Boolean = false, enableSoftwareAttestation: Boolean = false, hardwareAttestationRootKeys: Set<ByteArray> = DEFAULT_HARDWARE_TRUST_ANCHORS.map { it.encoded }.toSet(), softwareAttestationRootKeys: Set<ByteArray> = DEFAULT_SOFTWARE_TRUST_ANCHORS.map { it.encoded }.toSet(), apps: List<AndroidAttestationConfiguration.AppData>, httpProxy: String? = null, requireRemoteKeyProvisioning: Boolean = false)

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

@JvmOverloads

constructor(applications: List<AndroidAttestationConfiguration.AppData>, androidVersion: Int? = null, patchLevel: PatchLevel? = null, requireStrongBox: Boolean = false, allowBootloaderUnlock: Boolean = false, requireRollbackResistance: Boolean = false, ignoreLeafValidity: Boolean = false, hardwareAttestationTrustAnchors: Set<@Serializable(with = PubKeyBasePemSerializer::class) PublicKey> = linkedSetOf(*DEFAULT_HARDWARE_TRUST_ANCHORS), softwareAttestationTrustAnchors: Set<@Serializable(with = PubKeyBasePemSerializer::class) PublicKey> = linkedSetOf(*DEFAULT_SOFTWARE_TRUST_ANCHORS), verificationSecondsOffset: Long = 0, attestationStatementValiditySeconds: Long? = 5 * 60, disableHardwareAttestation: Boolean = false, enableNougatAttestation: Boolean = false, enableSoftwareAttestation: Boolean = false, requireRemoteKeyProvisioning: Boolean = false, httpProxy: String? = null)

Types

AppData

@Serializable

data class AppData @JvmOverloads constructor(val packageName: String, val signatureDigests: List<@Serializable(with = ByteArrayBase64UrlSerializer::class) ByteArray>, val appVersion: Int? = null, val androidVersionOverride: Int? = null, patchLevelOverride: PatchLevel? = null, val trustAnchorOverrides: Set<@Serializable(with = PubKeyBasePemSerializer::class) PublicKey>? = null, val requireRemoteKeyProvisioningOverride: 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

Properties

allowBootloaderUnlock

val allowBootloaderUnlock: Boolean = false

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 NougatHybridAttestationChecker of SoftwareAttestationChecker is used

androidVersion

val androidVersion: Int? = null

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 = false

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

enableNougatAttestation

val enableNougatAttestation: Boolean = false

Enables hybrid attestation. A NougatHybridAttestationChecker can only be instantiated if this flag is set to true. Only change this flag, if you require support for devices, which originally shipped with Android 7 (Nougat), as these devices only support hardware-backed key attestation, but provide no indication about the OS state. Hence, app-attestation cannot be trusted, but key attestation still can.

enableSoftwareAttestation

val enableSoftwareAttestation: Boolean = false

hardwareAttestationTrustAnchors

val hardwareAttestationTrustAnchors: Set<@Serializable(with = PubKeyBasePemSerializer::class) PublicKey>

httpProxy

val httpProxy: String? = null

HTTP Proxy URL formatted as http(s)://proxy-domain:port

ignoreLeafValidity

val ignoreLeafValidity: Boolean = false

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

requireRemoteKeyProvisioning

val requireRemoteKeyProvisioning: Boolean = false

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

requireRollbackResistance

val requireRollbackResistance: Boolean = false

Unsupported by most devices. See Official Documentation

requireStrongBox

val requireStrongBox: Boolean = false

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

softwareAttestationTrustAnchors

val softwareAttestationTrustAnchors: Set<@Serializable(with = PubKeyBasePemSerializer::class) PublicKey>

verificationSecondsOffset

val verificationSecondsOffset: Long = 0

Tolerance in seconds added to verification date

Functions

equals

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

hashCode

open override fun hashCode(): Int

toString

open override fun toString(): String