Atestado de chave e ID

O Keystore fornece um local mais seguro para criar, armazenar e usar chaves criptográficas de maneira controlada. Quando o armazenamento de chaves com suporte de hardware está disponível e é usado, o material da chave fica mais seguro contra a extração do dispositivo, e o Keymaster impõe restrições difíceis de subverter.

No entanto, isso só é verdade se as chaves do keystore estiverem em armazenamento com suporte de hardware. No Keymaster 1, não havia como os aplicativos ou servidores remotos verificarem de forma confiável se esse era o caso. O daemon keystore carregou o HAL do keymaster disponível e acreditou no que o HAL disse com relação ao suporte de hardware das chaves.

Para remediar isso, a Keymaster introduziuo atestado de chave no Android 7.0 (Keymaster 2) e o atestado de ID no Android 8.0 (Keymaster 3).

O atestado de chave visa fornecer uma maneira de determinar fortemente se um par de chaves assimétricas é suportado por hardware, quais são as propriedades da chave e quais restrições são aplicadas ao seu uso.

O atestado de ID permite que o dispositivo forneça prova de seus identificadores de hardware, como número de série ou IMEI.

Atestado de chave

Para oferecer suporte ao atestado de chave, o Android 7.1 introduziu um conjunto de tags, tipo e método para o HAL.

Tag

• Tag::ATTESTATION_CHALLENGE
• Tag::INCLUDE_UNIQUE_ID
• Tag::RESET_SINCE_ID_ROTATION

Tipo

Keymaster 2 e abaixo

typedef struct {
    keymaster_blob_t* entries;
    size_t entry_count;
} keymaster_cert_chain_t;

Método AttestKey

Keymaster 3

    attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams)
        generates(ErrorCode error, vec<vec<uint8_t>> certChain);

Keymaster 2 e abaixo

keymaster_error_t (*attest_key)(const struct keymaster2_device* dev,
        const keymaster_key_blob_t* key_to_attest,
        const keymaster_key_param_set_t* attest_params,
        keymaster_cert_chain_t* cert_chain);

• dev é a estrutura do dispositivo keymaster.
• keyToAttest é o blob de chaves retornado de generateKey para o qual o atestado será criado.
• attestParams é uma lista de quaisquer parâmetros necessários para atestado. Isso inclui Tag::ATTESTATION_CHALLENGE e possivelmente Tag::RESET_SINCE_ID_ROTATION , bem como Tag::APPLICATION_ID e Tag::APPLICATION_DATA . Os dois últimos são necessários para descriptografar o blob de chaves se tiverem sido especificados durante a geração da chave.
• certChain é o parâmetro de saída, que retorna uma matriz de certificados. A entrada 0 é o certificado de atestado, o que significa que certifica a chave de keyToAttest e contém a extensão de atestado.

O método attestKey é considerado uma operação de chave pública na chave atestada, pois pode ser chamado a qualquer momento e não precisa atender às restrições de autorização. Por exemplo, se a chave atestada precisar de autenticação de usuário para uso, um atestado pode ser gerado sem autenticação de usuário.

Certificado de atestado

O certificado de atestado é um certificado X.509 padrão, com uma extensão de atestado opcional que contém uma descrição da chave atestada. O certificado é assinado com uma chave de atestado fornecida pela fábrica que usa o mesmo algoritmo da chave que está sendo atestado (RSA para RSA, EC para EC).

O certificado de atestado contém os campos da tabela abaixo e não pode conter campos adicionais. Alguns campos especificam um valor de campo fixo. Os testes CTS validam que o conteúdo do certificado é exatamente como definido.

Certificado SEQUÊNCIA

SEQUÊNCIA DE CERTIFICADO TBS

Extensão de atestado

A extensão de attestation contém uma descrição completa das autorizações do keymaster associadas à chave, em uma estrutura que corresponde diretamente às listas de autorização usadas no Android e no HAL do keymaster. Cada tag em uma lista de autorização é representada por uma entrada ASN.1 SEQUENCE , explicitamente marcada com o número da tag keymaster, mas com o descritor de tipo (quatro bits de alta ordem) mascarado.

Por exemplo, no Keymaster 3, Tag::PURPOSE PURPOSE é definido em types.hal como ENUM_REP | 1 . Para a extensão de atestado, o valor ENUM_REP é removido, deixando a tag 1 . (Para Keymaster 2 e abaixo, KM_TAG_PURPOSE é definido em keymaster_defs.h.)

Os valores são traduzidos de forma direta para os tipos ASN.1, conforme esta tabela:

Esquema

O conteúdo da extensão de atestado é descrito pelo esquema ASN.1 a seguir.

KeyDescription ::= SEQUENCE {
  attestationVersion         INTEGER, # KM2 value is 1. KM3 value is 2. KM4 value is 3.
  attestationSecurityLevel   SecurityLevel,
  keymasterVersion           INTEGER,
  keymasterSecurityLevel     SecurityLevel,
  attestationChallenge       OCTET_STRING,
  uniqueId                   OCTET_STRING,
  softwareEnforced           AuthorizationList,
  teeEnforced                AuthorizationList,
}

SecurityLevel ::= ENUMERATED {
  Software                   (0),
  TrustedEnvironment         (1),
  StrongBox                  (2),
}

AuthorizationList ::= SEQUENCE {
  purpose                     [1] EXPLICIT SET OF INTEGER OPTIONAL,
  algorithm                   [2] EXPLICIT INTEGER OPTIONAL,
  keySize                     [3] EXPLICIT INTEGER OPTIONAL.
  digest                      [5] EXPLICIT SET OF INTEGER OPTIONAL,
  padding                     [6] EXPLICIT SET OF INTEGER OPTIONAL,
  ecCurve                     [10] EXPLICIT INTEGER OPTIONAL,
  rsaPublicExponent           [200] EXPLICIT INTEGER OPTIONAL,
  rollbackResistance          [303] EXPLICIT NULL OPTIONAL, # KM4
  activeDateTime              [400] EXPLICIT INTEGER OPTIONAL
  originationExpireDateTime   [401] EXPLICIT INTEGER OPTIONAL
  usageExpireDateTime         [402] EXPLICIT INTEGER OPTIONAL
  noAuthRequired              [503] EXPLICIT NULL OPTIONAL,
  userAuthType                [504] EXPLICIT INTEGER OPTIONAL,
  authTimeout                 [505] EXPLICIT INTEGER OPTIONAL,
  allowWhileOnBody            [506] EXPLICIT NULL OPTIONAL,
  trustedUserPresenceRequired [507] EXPLICIT NULL OPTIONAL, # KM4
  trustedConfirmationRequired [508] EXPLICIT NULL OPTIONAL, # KM4
  unlockedDeviceRequired      [509] EXPLICIT NULL OPTIONAL, # KM4
  allApplications             [600] EXPLICIT NULL OPTIONAL,
  applicationId               [601] EXPLICIT OCTET_STRING OPTIONAL,
  creationDateTime            [701] EXPLICIT INTEGER OPTIONAL,
  origin                      [702] EXPLICIT INTEGER OPTIONAL,
  rollbackResistant           [703] EXPLICIT NULL OPTIONAL, # KM2 and KM3 only.
  rootOfTrust                 [704] EXPLICIT RootOfTrust OPTIONAL,
  osVersion                   [705] EXPLICIT INTEGER OPTIONAL,
  osPatchLevel                [706] EXPLICIT INTEGER OPTIONAL,
  attestationApplicationId    [709] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  attestationIdBrand          [710] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  attestationIdDevice         [711] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  attestationIdProduct        [712] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  attestationIdSerial         [713] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  attestationIdImei           [714] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  attestationIdMeid           [715] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  attestationIdManufacturer   [716] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  attestationIdModel          [717] EXPLICIT OCTET_STRING OPTIONAL, # KM3
  vendorPatchLevel            [718] EXPLICIT INTEGER OPTIONAL, # KM4
  bootPatchLevel              [719] EXPLICIT INTEGER OPTIONAL, # KM4
}

RootOfTrust ::= SEQUENCE {
  verifiedBootKey            OCTET_STRING,
  deviceLocked               BOOLEAN,
  verifiedBootState          VerifiedBootState,
  verifiedBootHash           OCTET_STRING, # KM4
}

VerifiedBootState ::= ENUMERATED {
  Verified                   (0),
  SelfSigned                 (1),
  Unverified                 (2),
  Failed                     (3),
}

Campos de descrição da chave

Os campos keymasterVersion e attestationChallenge são identificados posicionalmente, em vez de por tag, portanto, as tags no formulário codificado especificam apenas o tipo de campo. Os campos restantes são marcados implicitamente conforme especificado no esquema.

Campos da lista de autorizações

Os campos AuthorizationList são todos opcionais e são identificados pelo valor da tag keymaster, com os bits de tipo mascarados. A marcação explícita é usada para que os campos também contenham uma marca indicando seu tipo ASN.1, para facilitar a análise.

Para obter detalhes sobre os valores de cada campo, consulte types.hal para Keymaster 3 e keymaster_defs.h para Keymaster 2 e abaixo. Os nomes de tags Keymaster foram transformados em nomes de campo omitindo o prefixo KM_TAG e alterando o restante para camel case, então Tag::KEY_SIZE tornou-se keySize .

Campos RootOfTrust

Os campos RootOfTrust são identificados posicionalmente.

Valores de VerifiedBootState

Os valores de verifiedBootState têm os seguintes significados:

Valores de nível de segurança

Os valores de securityLevel têm os seguintes significados:

ID único

O ID exclusivo é um valor de 128 bits que identifica o dispositivo, mas apenas por um período limitado de tempo. O valor é calculado com:

HMAC_SHA256(T || C || R, HBK)

Onde:

• T é o "valor do contador temporal", calculado dividindo o valor de Tag::CREATION_DATETIME por 2592000000, descartando qualquer resto. T muda a cada 30 dias (2592000000 = 30 * 24 * 60 * 60 * 1000).
• C é o valor da Tag::APPLICATION_ID
• R é 1 se Tag::RESET_SINCE_ID_ROTATION estiver presente no parâmetro attest_params para a chamada attest_key, ou 0 se o tag não estiver presente.
• HBK é um segredo exclusivo de hardware conhecido pelo Trusted Execution Environment e nunca revelado por ele. O segredo contém pelo menos 128 bits de entropia e é exclusivo para o dispositivo individual (a singularidade probabilística é aceitável, considerando os 128 bits de entropia). HBK deve ser derivado de material de chave fundida via HMAC ou AES_CMAC.

Trunque a saída HMAC_SHA256 para 128 bits.

Chaves de atestado e certificados

Duas chaves, uma RSA e uma ECDSA, e as cadeias de certificados correspondentes, são provisionadas com segurança no dispositivo.

atestado de identidade

O Android 8.0 inclui suporte opcional para atestado de ID para dispositivos com Keymaster 3. O atestado de ID permite que o dispositivo forneça prova de seus identificadores de hardware, como número de série ou IMEI. Embora seja um recurso opcional, é altamente recomendável que todas as implementações do Keymaster 3 forneçam suporte para ele, pois ser capaz de provar a identidade do dispositivo permite que casos de uso como configuração remota sem toque real sejam mais seguros (porque o lado remoto pode ter certeza de que está falando com o dispositivo certo, não com um dispositivo falsificando sua identidade).

O atestado de ID funciona criando cópias dos identificadores de hardware do dispositivo que somente o Trusted Execution Environment (TEE) pode acessar antes que o dispositivo saia da fábrica. Um usuário pode desbloquear o bootloader do dispositivo e alterar o software do sistema e os identificadores relatados pelas estruturas do Android. As cópias dos identificadores mantidos pelo TEE não podem ser manipuladas dessa maneira, garantindo que o atestado de ID do dispositivo só atestará os identificadores de hardware originais do dispositivo, frustrando assim as tentativas de falsificação.

A superfície da API principal para o atestado de ID se baseia no mecanismo de atestado de chave existente introduzido com o Keymaster 2. Ao solicitar um certificado de atestado para uma chave mantida pelo keymaster, o chamador pode solicitar que os identificadores de hardware do dispositivo sejam incluídos nos metadados do certificado de atestado. Se a chave for mantida no TEE, o certificado será encadeado de volta a uma raiz de confiança conhecida. O destinatário de tal certificado pode verificar se o certificado e seu conteúdo, incluindo os identificadores de hardware, foram escritos pelo TEE. Quando solicitado a incluir identificadores de hardware no certificado de atestado, o TEE atesta apenas os identificadores mantidos em seu armazenamento, conforme preenchidos no chão de fábrica.

Propriedades de armazenamento

O armazenamento que contém os identificadores do dispositivo precisa ter estas propriedades:

• Os valores derivados dos identificadores originais do dispositivo são copiados para o armazenamento antes que o dispositivo saia da fábrica.
• O método destroyAttestationIds() pode destruir permanentemente esta cópia dos dados derivados do identificador. Destruição permanente significa que os dados são completamente removidos para que nem uma redefinição de fábrica nem qualquer outro procedimento realizado no dispositivo possam restaurá-los. Isso é especialmente importante para dispositivos em que um usuário desbloqueou o carregador de inicialização e alterou o software do sistema e modificou os identificadores retornados pelas estruturas do Android.
• As instalações de RMA devem ter a capacidade de gerar novas cópias dos dados derivados do identificador de hardware. Dessa forma, um dispositivo que passa pelo RMA pode realizar novamente a atestação de ID. O mecanismo usado pelos recursos de RMA deve ser protegido para que os usuários não possam invocá-lo, pois isso permitiria obter atestados de IDs falsificados.
• Nenhum código que não seja o aplicativo confiável Keymaster no TEE é capaz de ler os dados derivados do identificador mantidos no armazenamento.
• O armazenamento é inviolável: Se o conteúdo do armazenamento foi modificado, o TEE o trata como se as cópias do conteúdo tivessem sido destruídas e recusa todas as tentativas de atestado de identidade. Isso é implementado assinando ou MACing o armazenamento conforme descrito abaixo .
• O armazenamento não contém os identificadores originais. Como o atestado de ID envolve um desafio, o chamador sempre fornece os identificadores a serem atestados. O TEE só precisa verificar se eles correspondem aos valores que tinham originalmente. Armazenar hashes seguros dos valores originais em vez dos valores permite essa verificação.

Construção

Para criar uma implementação que tenha as propriedades listadas acima, armazene os valores derivados de ID na seguinte construção S. Não armazene outras cópias dos valores de ID, exceto os locais normais do sistema, que um proprietário de dispositivo pode modificar fazendo root:

S = D || HMAC(HBK, D)

Onde:

• D = HMAC(HBK, ID 1 ) || HMAC(HBK, ID 2 ) || ... || HMAC(HBK, ID n )
• HMAC é a construção HMAC com um hash seguro apropriado (recomenda-se SHA-256)
• HBK é uma chave vinculada a hardware não usada para nenhum outro propósito
• ID 1 ...ID n são os valores de ID originais; a associação de um valor específico a um índice específico depende da implementação, pois dispositivos diferentes terão números diferentes de identificadores
• || representa concatenação

Como as saídas HMAC são de tamanho fixo, nenhum cabeçalho ou outra estrutura é necessário para encontrar hashes de ID individuais ou o HMAC de D. Além de verificar os valores fornecidos para realizar o atestado, as implementações precisam validar S extraindo D de S , computando HMAC(HBK, D) e comparando-o com o valor em S para verificar se nenhum ID individual foi modificado/corrompido. Além disso, as implementações devem usar comparações de tempo constante para todos os elementos de ID individuais e a validação de S. O tempo de comparação deve ser constante, independentemente do número de IDs fornecidos e da correspondência correta de qualquer parte do teste.

Identificadores de hardware

O atestado de ID é compatível com os seguintes identificadores de hardware:

1. Nome da marca, conforme retornado por Build.BRAND no Android
2. Nome do dispositivo, conforme retornado por Build.DEVICE no Android
3. Nome do produto, conforme retornado por Build.PRODUCT no Android
4. Nome do fabricante, conforme retornado por Build.MANUFACTURER no Android
5. Nome do modelo, conforme retornado por Build.MODEL no Android
6. Número de série
7. IMEIs de todos os rádios
8. MEIDs de todos os rádios

Para oferecer suporte ao atestado de ID do dispositivo, um dispositivo atesta esses identificadores. Todos os dispositivos que executam o Android têm os seis primeiros e são necessários para que esse recurso funcione. Se o dispositivo tiver rádios celulares integrados, o dispositivo também deve suportar atestado para os IMEIs e/ou MEIDs dos rádios.

O atestado de ID é solicitado realizando um atestado de chave e incluindo os identificadores de dispositivo para atestar na solicitação. Os identificadores são marcados como:

• ATTESTATION_ID_BRAND
• ATTESTATION_ID_DEVICE
• ATTESTATION_ID_PRODUCT
• ATTESTATION_ID_MANUFACTURER
• ATTESTATION_ID_MODEL
• ATTESTATION_ID_SERIAL
• ATTESTATION_ID_IMEI
• ATTESTATION_ID_MEID

O identificador a ser atestado é uma string de bytes codificada em UTF-8. Esse formato também se aplica a identificadores numéricos. Cada identificador para atestar é expresso como uma string codificada em UTF-8.

Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua uma ou mais dessas tags falhará com ErrorCode::CANNOT_ATTEST_IDS .

Se o dispositivo suportar atestado de ID e uma ou mais das tags acima foram incluídas em uma solicitação de atestado de chave, o TEE verifica se o identificador fornecido com cada uma das tags corresponde à sua cópia dos identificadores de hardware. Se um ou mais identificadores não corresponderem, todo o atestado falhará com ErrorCode::CANNOT_ATTEST_IDS . É válido que a mesma tag seja fornecida várias vezes. Isso pode ser útil, por exemplo, ao atestar IMEIs: Um dispositivo pode ter vários rádios com vários IMEIs. Uma solicitação de atestado é válida se o valor fornecido com cada ATTESTATION_ID_IMEI corresponder a um dos rádios do dispositivo. O mesmo se aplica a todas as outras tags.

Se o atestado for bem-sucedido, os IDs atestados serão adicionados à extensão de atestado (OID 1.3.6.1.4.1.11129.2.1.17) do certificado de atestado emitido, usando o esquema acima . As alterações do esquema de atestado do Keymaster 2 estão em negrito , com comentários.

API Java

Esta seção é apenas informativa. Os implementadores do Keymaster não implementam nem usam a API Java. Isso é fornecido para ajudar os implementadores a entender como o recurso é usado pelos aplicativos. Os componentes do sistema podem usá-lo de maneira diferente, por isso é crucial que esta seção não seja tratada como normativa.

// Create KeyPairGenerator and set generation parameters for an ECDSA key pair
// using the NIST P-256 curve.  "Key1" is the key alias.
KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
    KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
keyPairGenerator.initialize(
    new KeyGenParameterSpec.Builder("Key1", KeyProperties.PURPOSE_SIGN)
         .setAlgorithmParameterSpec(new ECGenParameterSpec("secp256r1"))
         .setDigests(KeyProperties.DIGEST_SHA256,
                     KeyProperties.DIGEST_SHA384,
                     KeyProperties.DIGEST_SHA512)
         // Only permit the private key to be used if the user
         // authenticated within the last five minutes.
         .setUserAuthenticationRequired(true)
         .setUserAuthenticationValidityDurationSeconds(5 * 60)
         // Request an attestation with challenge "hello world".
         .setAttestationChallenge("hello world".getBytes("UTF-8"))
         .build());
// Generate the key pair. This will result in calls to both generate_key() and
// attest_key() at the keymaster2 HAL.
KeyPair keyPair = keyPairGenerator.generateKeyPair();
// Get the certificate chain
KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
Certificate[] certs = keyStore.getCertificateChain("Key1");
// certs[0] is the attestation certificate. certs[1] signs certs[0], etc.,
// up to certs[certs.length - 1].