KeyGenParameterSpec Classe

Définition

[Android.Runtime.Register("android/security/keystore/KeyGenParameterSpec", ApiSince=23, DoNotGenerateAcw=true)]
public sealed class KeyGenParameterSpec : Java.Lang.Object, IDisposable, Java.Security.Spec.IAlgorithmParameterSpec

[<Android.Runtime.Register("android/security/keystore/KeyGenParameterSpec", ApiSince=23, DoNotGenerateAcw=true)>]
type KeyGenParameterSpec = class
    inherit Object
    interface IAlgorithmParameterSpec
    interface IJavaObject
    interface IDisposable
    interface IJavaPeerable

Héritage

Object

JavaObject

Object

KeyGenParameterSpec

Attributs

RegisterAttribute

Implémente

IJavaObject IJavaPeerable IAlgorithmParameterSpec IDisposable

Remarques

AlgorithmParameterSpec pour initialiser un KeyPairGenerator ou un KeyGenerator système Android Keystore. La spécification détermine les utilisations autorisées de la clé, par exemple si l’authentification de l’utilisateur est requise pour l’utilisation de la clé, quelles opérations sont autorisées (par exemple, la signature, mais pas le déchiffrement), avec les paramètres (par exemple, uniquement avec un schéma de remplissage ou digest particulier) et les dates de début et de fin de la clé. Les autorisations d’utilisation de clé exprimées dans la spécification s’appliquent uniquement aux clés secrètes et aux clés privées. Les clés publiques peuvent être utilisées pour toutes les opérations prises en charge.

Pour générer une paire de clés asymétrique ou une clé symétrique, créez une instance de cette classe à l’aide Builderdu , initialisez un KeyPairGenerator ou un KeyGenerator du type de clé souhaité (par exemple, EC ou AES -- voir KeyProperties.KEY_ALGORITHM constantes) à partir du AndroidKeyStore fournisseur avec l’instance KeyGenParameterSpec , puis générez une paire clé ou clé à l’aide KeyGenerator#generateKey() ou KeyPairGenerator#generateKeyPair().

La paire de clés ou la clé générée est retournée par le générateur et également stockée dans le magasin de clés Android sous l’alias spécifié dans cette spécification. Pour obtenir la clé secrète ou privée à partir de l’utilisation java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null) du magasin de clés Android ou java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null). Pour obtenir la clé publique à partir de l’utilisation java.security.KeyStore#getCertificate(String) du magasin de clés Android, puis Certificate#getPublicKey().

Pour obtenir des paramètres publics spécifiques à l’algorithme des paires de clés stockées dans le magasin de clés Android, les clés privées générées implémentent java.security.interfaces.ECKey ou java.security.interfaces.RSAKey interfaces, tandis que les clés publiques implémentent java.security.interfaces.ECPublicKey ou java.security.interfaces.RSAPublicKey interfaces.

Pour les paires de clés asymétriques, un certificat X.509 est également généré et stocké dans le magasin de clés Android. Cela est dû au fait que l’abstraction java.security.KeyStore ne prend pas en charge le stockage de paires de clés sans certificat. L’objet, le numéro de série et les dates de validité du certificat peuvent être personnalisées dans cette spécification. Le certificat peut être remplacé ultérieurement par un certificat signé par une autorité de certification.

REMARQUE : Si l’attestation n’est pas demandée à l’aide Builder#setAttestationChallenge(byte[]), le certificat généré peut être auto-signé. Si une clé privée n’est pas autorisée à signer le certificat, le certificat est créé avec une signature non valide qui ne sera pas vérifiée. Un tel certificat est toujours utile, car il fournit l’accès à la clé publique. Pour générer une signature valide pour le certificat, la clé doit être autorisée pour toutes les opérations suivantes : <ul><li>KeyProperties#PURPOSE_SIGN,</><li li>sans exiger que l’utilisateur soit authentifié (voir Builder#setUserAuthenticationRequired(boolean)),</li><>signature/origine à ce moment-là (voir Builder#setKeyValidityStart(Date) et Builder#setKeyValidityForOriginationEnd(Date)),</li li>approprié digest,</li><><li>(clés RSA uniquement) schéma KeyProperties#SIGNATURE_PADDING_RSA_PKCS1de remplissage.</li></ul>

REMARQUE : Le matériel de clé des clés symétriques et privées générées n’est pas accessible. Le matériel clé des clés publiques est accessible.

Les instances de cette classe sont immuables.

<H3>Problèmes< connus/h3> Un bogue connu dans Android 6.0 (niveau d’API 23) entraîne l’application des autorisations liées à l’authentification utilisateur même pour les clés publiques. Pour contourner ce problème, extrayez le matériel de clé publique à utiliser en dehors d’Android Keystore. Par exemple:

{@code
            PublicKey unrestrictedPublicKey =
                    KeyFactory.getInstance(publicKey.getAlgorithm()).generatePublic(
                            new X509EncodedKeySpec(publicKey.getEncoded()));
            }

<Exemple h3>: paire de clés EC P-256 NIST pour la signature/vérification à l’aide d’ECDSA</h3> Cet exemple montre comment générer une paire de clés EC NIST P-256 (aka secp256r1 aka prime256v1) EC dans le système Android KeyStore sous l’alias key1 où la clé privée est autorisée à être utilisée uniquement pour la signature à l’aide de SHA-256, SHA-384 ou SHA-512 digest et uniquement si l’utilisateur a été authentifié au cours des cinq dernières minutes. L’utilisation de la clé publique est illimitée (voir Problèmes connus).

{@code
            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)
                            .build());
            KeyPair keyPair = keyPairGenerator.generateKeyPair();
            Signature signature = Signature.getInstance("SHA256withECDSA");
            signature.initSign(keyPair.getPrivate());
            ...

            // The key pair can also be obtained from the Android Keystore any time as follows:
            KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
            keyStore.load(null);
            PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
            PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
            }

<Exemple h3>: Paire de clés RSA pour la signature/vérification à l’aide de RSA-PSS</h3> Cet exemple montre comment générer une paire de clés RSA dans le système Android KeyStore sous alias key1 autorisé à être utilisée uniquement pour la signature à l’aide du schéma de remplissage de signature RSA-PSS avec les synthèses SHA-256 ou SHA-512. L’utilisation de la clé publique est illimitée.

{@code
            KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
                    KeyProperties.KEY_ALGORITHM_RSA, "AndroidKeyStore");
            keyPairGenerator.initialize(
                    new KeyGenParameterSpec.Builder(
                            "key1",
                            KeyProperties.PURPOSE_SIGN)
                            .setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
                            .setSignaturePaddings(KeyProperties.SIGNATURE_PADDING_RSA_PSS)
                            .build());
            KeyPair keyPair = keyPairGenerator.generateKeyPair();
            Signature signature = Signature.getInstance("SHA256withRSA/PSS");
            signature.initSign(keyPair.getPrivate());
            ...

            // The key pair can also be obtained from the Android Keystore any time as follows:
            KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
            keyStore.load(null);
            PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
            PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
            }

<Exemple h3>: Paire de clés RSA pour le chiffrement/déchiffrement à l’aide de RSA OAEP/h3< Cet exemple montre comment générer une paire de clés RSA dans le système Android KeyStore sous alias > où la clé privée est autorisée à être utilisée uniquement pour le déchiffrement à l’aide du schéma de remplissage de chiffrement RSA OAEPkey1 avec sha-256 ou SHA-512 digests. L’utilisation de la clé publique est illimitée.

{@code
            KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
                    KeyProperties.KEY_ALGORITHM_RSA, "AndroidKeyStore");
            keyPairGenerator.initialize(
                    new KeyGenParameterSpec.Builder(
                            "key1",
                            KeyProperties.PURPOSE_DECRYPT)
                            .setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
                            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_RSA_OAEP)
                            .build());
            KeyPair keyPair = keyPairGenerator.generateKeyPair();
            Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding");
            cipher.init(Cipher.DECRYPT_MODE, keyPair.getPrivate());
            ...

            // The key pair can also be obtained from the Android Keystore any time as follows:
            KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
            keyStore.load(null);
            PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
            PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
            }

<Exemple h3>: Clé AES pour le chiffrement/déchiffrement en mode< GCM/h3> L’exemple suivant montre comment générer une clé AES dans le système Android KeyStore sous alias key2 autorisé à être utilisé uniquement pour le chiffrement/déchiffrement en mode GCM sans remplissage.

{@code
            KeyGenerator keyGenerator = KeyGenerator.getInstance(
                    KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore");
            keyGenerator.init(
                    new KeyGenParameterSpec.Builder("key2",
                            KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
                            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
                            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
                            .build());
            SecretKey key = keyGenerator.generateKey();

            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
            cipher.init(Cipher.ENCRYPT_MODE, key);
            ...

            // The key can also be obtained from the Android Keystore any time as follows:
            KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
            keyStore.load(null);
            key = (SecretKey) keyStore.getKey("key2", null);
            }

<Exemple h3>: Clé HMAC pour générer un MAC à l’aide de SHA-256</h3> Cet exemple montre comment générer une clé HMAC dans le système Android KeyStore sous alias key2 autorisé à être utilisé uniquement pour générer un HMAC à l’aide de SHA-256.

{@code
            KeyGenerator keyGenerator = KeyGenerator.getInstance(
                    KeyProperties.KEY_ALGORITHM_HMAC_SHA256, "AndroidKeyStore");
            keyGenerator.init(
                    new KeyGenParameterSpec.Builder("key2", KeyProperties.PURPOSE_SIGN).build());
            SecretKey key = keyGenerator.generateKey();
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(key);
            ...

            // The key can also be obtained from the Android Keystore any time as follows:
            KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
            keyStore.load(null);
            key = (SecretKey) keyStore.getKey("key2", null);
            }

<h3 id="example :ecdh">Example : EC key for ECDH key agreement</h3> Cet exemple montre comment générer une paire de clés de courbe elliptique, utilisée pour établir un secret partagé avec une autre partie à l’aide d’un accord de clé ECDH.

{@code
            KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
                    KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
            keyPairGenerator.initialize(
                    new KeyGenParameterSpec.Builder(
                        "eckeypair",
                        KeyProperties.PURPOSE_AGREE_KEY)
                        .setAlgorithmParameterSpec(new ECGenParameterSpec("secp256r1"))
                        .build());
            KeyPair myKeyPair = keyPairGenerator.generateKeyPair();

            // Exchange public keys with server. A new ephemeral key MUST be used for every message.
            PublicKey serverEphemeralPublicKey; // Ephemeral key received from server.

            // Create a shared secret based on our private key and the other party's public key.
            KeyAgreement keyAgreement = KeyAgreement.getInstance("ECDH", "AndroidKeyStore");
            keyAgreement.init(myKeyPair.getPrivate());
            keyAgreement.doPhase(serverEphemeralPublicKey, true);
            byte[] sharedSecret = keyAgreement.generateSecret();

            // sharedSecret cannot safely be used as a key yet. We must run it through a key derivation
            // function with some other data: "salt" and "info". Salt is an optional random value,
            // omitted in this example. It's good practice to include both public keys and any other
            // key negotiation data in info. Here we use the public keys and a label that indicates
            // messages encrypted with this key are coming from the server.
            byte[] salt = {};
            ByteArrayOutputStream info = new ByteArrayOutputStream();
            info.write("ECDH secp256r1 AES-256-GCM-SIV\0".getBytes(StandardCharsets.UTF_8));
            info.write(myKeyPair.getPublic().getEncoded());
            info.write(serverEphemeralPublicKey.getEncoded());

            // This example uses the Tink library and the HKDF key derivation function.
            AesGcmSiv key = new AesGcmSiv(Hkdf.computeHkdf(
                    "HMACSHA256", sharedSecret, salt, info.toByteArray(), 32));
            byte[] associatedData = {};
            return key.decrypt(ciphertext, associatedData);
            }

Java documentation pour android.security.keystore.KeyGenParameterSpec.

Les parties de cette page sont des modifications basées sur le travail créé et partagé par Android Open Source et utilisées en fonction des termes décrits dans la Creative Commons 2.5 Attribution License.