Criptografia

Este documento descreve a maneira correta de usar os recursos criptográficos do Android e inclui alguns exemplos de uso. Se o app exigir maior segurança de chave, use o sistema Android Keystore.

Especificar um provedor apenas com o sistema Android Keystore

Se você estiver usando o sistema Android Keystore, precisará especificar um provedor.

Em outras situações, no entanto, o Android não garante um provedor específico para um determinado algoritmo. A especificação de um provedor sem usar o sistema Android Keystore pode causar problemas de compatibilidade em versões futuras.

Escolher um algoritmo recomendado

Quando você tem a liberdade de escolher qual algoritmo usar (por exemplo, quando não precisa de compatibilidade com um sistema de terceiros), recomendamos o uso dos seguintes algoritmos:

Executar operações criptográficas comuns

As seções a seguir incluem snippets que demonstram como você pode concluir operações criptográficas comuns no seu app.

Ler um arquivo

// Although you can define your own key generation parameter specification, it's
// recommended that you use the value specified here.
val keyGenParameterSpec = MasterKeys.AES256_GCM_SPEC
val mainKeyAlias = MasterKeys.getOrCreate(keyGenParameterSpec)

val fileToRead = "my_sensitive_data.txt"
val encryptedFile = EncryptedFile.Builder(
    File(DIRECTORY, fileToRead),
    applicationContext,
    mainKeyAlias,
    EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB
).build()

val inputStream = encryptedFile.openFileInput()
val byteArrayOutputStream = ByteArrayOutputStream()
var nextByte: Int = inputStream.read()
while (nextByte != -1) {
    byteArrayOutputStream.write(nextByte)
    nextByte = inputStream.read()
}

val plaintext: ByteArray = byteArrayOutputStream.toByteArray()

Context context = getApplicationContext();

// Although you can define your own key generation parameter specification, it's
// recommended that you use the value specified here.
KeyGenParameterSpec keyGenParameterSpec = MasterKeys.AES256_GCM_SPEC;
String mainKeyAlias = MasterKeys.getOrCreate(keyGenParameterSpec);

String fileToRead = "my_sensitive_data.txt";
EncryptedFile encryptedFile = new EncryptedFile.Builder(
        new File(DIRECTORY, fileToRead),
        context,
        mainKeyAlias,
        EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB
).build();

InputStream inputStream = encryptedFile.openFileInput();
ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
int nextByte = inputStream.read();
while (nextByte != -1) {
    byteArrayOutputStream.write(nextByte);
    nextByte = inputStream.read();
}

byte[] plaintext = byteArrayOutputStream.toByteArray();

Gravar um arquivo

// Although you can define your own key generation parameter specification, it's
// recommended that you use the value specified here.
val keyGenParameterSpec = MasterKeys.AES256_GCM_SPEC
val mainKeyAlias = MasterKeys.getOrCreate(keyGenParameterSpec)

// Create a file with this name, or replace an entire existing file
// that has the same name. Note that you cannot append to an existing file,
// and the file name cannot contain path separators.
val fileToWrite = "my_sensitive_data.txt"
val encryptedFile = EncryptedFile.Builder(
    File(DIRECTORY, fileToWrite),
    applicationContext,
    mainKeyAlias,
    EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB
).build()

val fileContent = "MY SUPER-SECRET INFORMATION"
        .toByteArray(StandardCharsets.UTF_8)
encryptedFile.openFileOutput().apply {
    write(fileContent)
    flush()
    close()
}

Context context = getApplicationContext();

// Although you can define your own key generation parameter specification, it's
// recommended that you use the value specified here.
KeyGenParameterSpec keyGenParameterSpec = MasterKeys.AES256_GCM_SPEC;
String mainKeyAlias = MasterKeys.getOrCreate(keyGenParameterSpec);

// Create a file with this name, or replace an entire existing file
// that has the same name. Note that you cannot append to an existing file,
// and the file name cannot contain path separators.
String fileToWrite = "my_sensitive_data.txt";
EncryptedFile encryptedFile = new EncryptedFile.Builder(
        new File(DIRECTORY, fileToWrite),
        context,
        mainKeyAlias,
        EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB
).build();

byte[] fileContent = "MY SUPER-SECRET INFORMATION"
        .getBytes(StandardCharsets.UTF_8);
OutputStream outputStream = encryptedFile.openFileOutput();
outputStream.write(fileContent);
outputStream.flush();
outputStream.close();

Criptografar uma mensagem

val plaintext: ByteArray = ...
val keygen = KeyGenerator.getInstance("AES")
keygen.init(256)
val key: SecretKey = keygen.generateKey()
val cipher = Cipher.getInstance("AES/CBC/PKCS5PADDING")
cipher.init(Cipher.ENCRYPT_MODE, key)
val ciphertext: ByteArray = cipher.doFinal(plaintext)
val iv: ByteArray = cipher.iv

byte[] plaintext = ...;
KeyGenerator keygen = KeyGenerator.getInstance("AES");
keygen.init(256);
SecretKey key = keygen.generateKey();
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5PADDING");
cipher.init(Cipher.ENCRYPT_MODE, key);
byte[] ciphertext = cipher.doFinal(plaintext);
byte[] iv = cipher.getIV();

Gerar um resumo de mensagens

val message: ByteArray = ...
val md = MessageDigest.getInstance("SHA-256")
val digest: ByteArray = md.digest(message)

byte[] message = ...;
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] digest = md.digest(message);

Gerar uma assinatura digital

Você precisa ter um objeto PrivateKey contendo a chave de assinatura, que pode ser gerada no momento da execução, lida em um arquivo incluído no seu app ou adquirida em alguma outra origem, dependendo das suas necessidades.

val message: ByteArray = ...
val key: PrivateKey = ...
val s = Signature.getInstance("SHA256withECDSA")
        .apply {
            initSign(key)
            update(message)
        }
val signature: ByteArray = s.sign()

byte[] message = ...;
PrivateKey key = ...;
Signature s = Signature.getInstance("SHA256withECDSA");
s.initSign(key);
s.update(message);
byte[] signature = s.sign();

Verificar uma assinatura digital

Você precisa ter um objeto PublicKey contendo a chave pública do assinante, que pode ser lida em um arquivo empacotado com seu app, extraída de um certificado ou adquirida em alguma outra origem, dependendo das suas necessidades.

val message: ByteArray = ...
val signature: ByteArray = ...
val key: PublicKey = ...
val s = Signature.getInstance("SHA256withECDSA")
        .apply {
            initVerify(key)
            update(message)
        }
val valid: Boolean = s.verify(signature)

byte[] message = ...;
byte[] signature = ...;
PublicKey key = ...;
Signature s = Signature.getInstance("SHA256withECDSA");
s.initVerify(key);
s.update(message);
boolean valid = s.verify(signature);

Complexidades de implementação

Alguns detalhes da implementação de criptografia do Android parecem incomuns, mas estão presentes devido a preocupações de compatibilidade. Esta seção discute as que você provavelmente encontrará.

Resumo da mensagem OAEP MGF1

As criptografias RSA OAEP são parametrizadas por dois resumos de mensagens diferentes: o resumo “principal” e o resumo MGF1. Há identificadores de criptografia que incluem nomes de resumo, por exemplo, Cipher.getInstance("RSA/ECB/OAEPwithSHA-256andMGF1Padding"), que especificam o resumo principal e deixam o resumo MGF1 não especificado. Para o Android Keystore, o SHA-1 é usado para o resumo MGF1. Para outros provedores criptográficos do Android, os dois resumos são iguais.

Para ter mais controle sobre os resumos que seu app usa, solicite uma criptografia com OAEPPadding, como em Cipher.getInstance("RSA/ECB/OAEPPadding"), e forneça um OAEPParameterSpec a init() para escolher explicitamente os dois resumos.

val key: Key = ...
val cipher = Cipher.getInstance("RSA/ECB/OAEPPadding")
        .apply {
            // To use SHA-256 the main digest and SHA-1 as the MGF1 digest
            init(Cipher.ENCRYPT_MODE, key, OAEPParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA1, PSource.PSpecified.DEFAULT))
            // To use SHA-256 for both digests
            init(Cipher.ENCRYPT_MODE, key, OAEPParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSource.PSpecified.DEFAULT))
        }

Key key = ...;
Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPPadding");
// To use SHA-256 the main digest and SHA-1 as the MGF1 digest
cipher.init(Cipher.ENCRYPT_MODE, key, new OAEPParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA1, PSource.PSpecified.DEFAULT));
// To use SHA-256 for both digests
cipher.init(Cipher.ENCRYPT_MODE, key, new OAEPParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSource.PSpecified.DEFAULT));

Funcionalidades suspensas

As seções a seguir descrevem funcionalidades suspensas que você não deve mais usar no seu app.

Algoritmos do Bouncy Castle

As implementações do Bouncy Castle de muitos algoritmos estão obsoletas. Isso só afeta casos em que você solicita explicitamente o provedor do Bouncy Castle, conforme mostrado no exemplo a seguir:

Cipher.getInstance("AES/CBC/PKCS7PADDING", "BC")
// OR
Cipher.getInstance("AES/CBC/PKCS7PADDING", Security.getProvider("BC"))

Cipher.getInstance("AES/CBC/PKCS7PADDING", "BC");
// OR
Cipher.getInstance("AES/CBC/PKCS7PADDING", Security.getProvider("BC"));

Conforme mencionado acima, não é recomendável solicitar um provedor específico. Portanto, se seguir essa diretriz, essa suspensão de uso não afetará você.

Criptografias baseadas em senhas sem IV

As criptografias baseadas em senha (PBE, na sigla em inglês) que exigem um vetor de inicialização (IV, na sigla em inglês) podem adquiri-lo na chave, se ela for construída adequadamente ou em um IV transmitido explicitamente. Ao transmitir uma chave de PBE que não contém um IV e nenhum IV explícito, as criptografias PBE no Android atualmente assumem um IV de zero.

Ao usar criptografias PBE, sempre transmita um IV explícito, conforme mostrado neste snippet de código:

val key: SecretKey = ...
val cipher = Cipher.getInstance("PBEWITHSHA256AND256BITAES-CBC-BC")
val iv = ByteArray(16)
SecureRandom().nextBytes(iv)
cipher.init(Cipher.ENCRYPT_MODE, key, IvParameterSpec(iv))

SecretKey key = ...;
Cipher cipher = Cipher.getInstance("PBEWITHSHA256AND256BITAES-CBC-BC");
byte[] iv = new byte[16];
new SecureRandom().nextBytes(iv);
cipher.init(Cipher.ENCRYPT_MODE, key, new IvParameterSpec(iv));

Provedor de criptografia

A partir do Android 9 (API de nível 28), o provedor de criptografia Java Cryptography Architecture (JCA) foi removido. Se o app solicitar uma instância do provedor de criptografia, por exemplo, chamar o método a seguir, ocorrerá um NoSuchProviderException.

SecureRandom.getInstance("SHA1PRNG", "Crypto")

SecureRandom.getInstance("SHA1PRNG", "Crypto");

Algoritmos compatíveis

Estes são os identificadores de algoritmo JCA compatíveis com o Android em cada nível de API:

• AlgorithmParameterGenerator
• AlgorithmParameters
• CertPathBuilder
• CertPathValidator
• CertStore
• CertificateFactory
• Cipher
• KeyAgreement
• KeyFactory
• KeyGenerator
• KeyManagerFactory
• KeyPairGenerator
• KeyStore
• Mac
• MessageDigest
• SSLContext
• SSLEngine.Supported
• SSLSocket.Supported
• SecretKeyFactory
• SecureRandom
• Signature
• TrustManagerFactory

AlgorithmParameterGenerator

AlgorithmParameters

CertPathBuilder

CertPathValidator

CertStore

CertificateFactory

Cipher

KeyAgreement

KeyFactory

KeyGenerator

KeyManagerFactory

KeyPairGenerator

KeyStore

Mac

MessageDigest

SSLContext

SSLEngine

SSLSocket

SecretKeyFactory

SecureRandom

Assinatura

TrustManagerFactory