KeyGenParameterSpec Klasse

Definition

[Android.Runtime.Register("android/security/keystore/KeyGenParameterSpec", ApiSince=23, DoNotGenerateAcw=true)]
public sealed class KeyGenParameterSpec : Java.Lang.Object, IDisposable, Java.Interop.IJavaPeerable, 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

Vererbung

Object

Object

KeyGenParameterSpec

Attribute

RegisterAttribute

Implementiert

IJavaObject IJavaPeerable IAlgorithmParameterSpec IDisposable

Hinweise

AlgorithmParameterSpec für die Initialisierung eines KeyPairGenerator oder eines KeyGenerator Android Keystore-Systems. Die Spezifikation bestimmt autorisierte Verwendungen des Schlüssels, z. B. ob die Benutzerauthentifizierung für die Verwendung des Schlüssels erforderlich ist, welche Vorgänge autorisiert sind (z. B. Signieren, aber nicht Entschlüsseln), mit welchen Parametern (z. B. nur mit einem bestimmten Abstandsschema oder Digest) und den Gültigkeits- und Enddaten des Schlüssels. Schlüsselverwendungsautorisierungen, die in der Spezifikation ausgedrückt werden, gelten nur für geheime Schlüssel und private Schlüssel – öffentliche Schlüssel können für alle unterstützten Vorgänge verwendet werden.

Um ein asymmetrisches Schlüsselpaar oder einen symmetrischen Schlüssel zu generieren, erstellen Sie eine Instanz dieser Klasse mithilfe der Builder, initialisieren sie ein KeyPairGenerator oder einen KeyGenerator des gewünschten Schlüsseltyps (z. B EC . oder AES -- siehe KeyProperties.KEY_ALGORITHM Konstanten) vom AndroidKeyStore Anbieter mit der KeyGenParameterSpec Instanz, und generieren Sie dann ein Schlüssel- oder Schlüsselpaar mit KeyGenerator#generateKey() oder KeyPairGenerator#generateKeyPair().

Das generierte Schlüsselpaar oder der generierte Schlüssel wird vom Generator zurückgegeben und auch im Android Keystore unter dem in dieser Spezifikation angegebenen Alias gespeichert. Um den geheimen oder privaten Schlüssel aus dem Android Keystore zu erhalten, verwenden java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null) oder java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null). Um den öffentlichen Schlüssel aus dem Android Keystore zu erhalten, verwenden java.security.KeyStore#getCertificate(String) Sie und dann Certificate#getPublicKey().

Um algorithmusspezifische öffentliche Parameter von Schlüsselpaaren zu erhalten, die im Android Keystore gespeichert sind, implementieren java.security.interfaces.ECKey oder schnittstellen generierte private Schlüssel, während öffentliche Schlüssel implementiert oder java.security.interfaces.RSAKey schnittstellen implementiert java.security.interfaces.ECPublicKey werden java.security.interfaces.RSAPublicKey .

Bei asymmetrischen Schlüsselpaaren wird auch ein X.509-Zertifikat generiert und im Android Keystore gespeichert. Dies liegt daran, dass die java.security.KeyStore Abstraktion das Speichern von Schlüsselpaaren ohne Zertifikat nicht unterstützt. Die Betreff-, Seriennummer- und Gültigkeitsdaten des Zertifikats können in dieser Spezifikation angepasst werden. Das Zertifikat kann zu einem späteren Zeitpunkt durch ein von einer Zertifizierungsstelle signiertes Zertifikat ersetzt werden.

HINWEIS: Wenn der Nachweis nicht mit der Verwendung Builder#setAttestationChallenge(byte[])angefordert wird, ist das generierte Zertifikat möglicherweise selbstsigniert. Wenn kein privater Schlüssel zum Signieren des Zertifikats autorisiert ist, wird das Zertifikat mit einer ungültigen Signatur erstellt, die nicht überprüft wird. Ein solches Zertifikat ist weiterhin nützlich, da es Zugriff auf den öffentlichen Schlüssel bietet. Um eine gültige Signatur für das Zertifikat zu generieren, muss der Schlüssel für alle folgenden Berechtigungen autorisiert werden: <ul><li>KeyProperties#PURPOSE_SIGN,</li li-Vorgang><>, ohne dass der Benutzer authentifiziert werden muss (siehe Builder#setUserAuthenticationRequired(boolean)),</li li>><signing/origination zu diesem Zeitpunkt (siehe Builder#setKeyValidityStart(Date) und Builder#setKeyValidityForOriginationEnd(Date)),</li li><>geeignet digest,</li>><(nur RSA-Schlüssel) Padding-Schema .<KeyProperties#SIGNATURE_PADDING_RSA_PKCS1/li></ul>

HINWEIS: Auf das Schlüsselmaterial der generierten symmetrischen und privaten Schlüssel kann nicht zugegriffen werden. Auf das Schlüsselmaterial der öffentlichen Schlüssel kann zugegriffen werden.

Instanzen dieser Klasse sind unveränderlich.

<h3>Bekannte Probleme</h3> Ein bekannter Fehler in Android 6.0 (API Level 23) bewirkt, dass benutzerauthentifizierungsbezogene Autorisierungen auch für öffentliche Schlüssel erzwungen werden. Um dieses Problem zu umgehen, extrahieren Sie das öffentliche Schlüsselmaterial, das außerhalb von Android Keystore verwendet werden soll. Beispiel:

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

<h3>Beispiel: NIST P-256 EC-Schlüsselpaar zum Signieren/Überprüfen mithilfe von ECDSA</h3> In diesem Beispiel wird veranschaulicht, wie ein NIST P-256 (aka secp256r1 aka prime256v1) EC-Schlüsselpaar im Android KeyStore-System unter Alias key1 generiert wird, in dem der private Schlüssel nur für die Signierung mit SHA-256 verwendet werden darf. SHA-384 oder SHA-512 Digest und nur, wenn der Benutzer innerhalb der letzten fünf Minuten authentifiziert wurde. Die Verwendung des öffentlichen Schlüssels ist uneingeschränkt (siehe bekannte Probleme).

{@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();
            }

<h3>Beispiel: RSA-Schlüsselpaar zum Signieren/Überprüfen mithilfe von RSA-PSS</h3> In diesem Beispiel wird veranschaulicht, wie sie ein RSA-Schlüsselpaar im Android KeyStore-System unter alias key1 generieren, der autorisiert ist, nur für die Signierung mithilfe des RSA-PSS Signaturabstandsschemas mit SHA-256- oder SHA-512-Digests zu verwenden. Die Verwendung des öffentlichen Schlüssels ist uneingeschränkt.

{@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();
            }

<h3>Beispiel: RSA-Schlüsselpaar für Verschlüsselung/Entschlüsselung mit RSA OAEP</h3> In diesem Beispiel wird veranschaulicht, wie sie ein RSA-Schlüsselpaar im Android KeyStore-System unter Alias key1 generieren, bei dem der private Schlüssel nur für die Entschlüsselung mit RSA OAEP-Verschlüsselungsabstandsschema mit SHA-256- oder SHA-512-Digests verwendet werden kann. Die Verwendung des öffentlichen Schlüssels ist uneingeschränkt.

{@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();
            }

<h3>Beispiel: AES-Schlüssel für Verschlüsselung/Entschlüsselung im GCM-Modus</h3> Im folgenden Beispiel wird veranschaulicht, wie ein AES-Schlüssel im Android KeyStore-System unter alias key2 generiert wird, der berechtigt ist, nur für die Verschlüsselung/Entschlüsselung im GCM-Modus ohne Abstand zu verwenden.

{@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);
            }

<h3>Beispiel: HMAC-Schlüssel zum Generieren eines MAC mithilfe von SHA-256</h3> In diesem Beispiel wird veranschaulicht, wie ein HMAC-Schlüssel im Android KeyStore-System unter alias key2 generiert wird, der berechtigt ist, einen HMAC mit SHA-256 zu generieren.

{@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> This example illustrates how to generate an elliptic curve key pair, used to establish a shared secret with another party using ECDH key agreement<.

{@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 Dokumentation für android.security.keystore.KeyGenParameterSpec.

Teile dieser Seite sind Änderungen auf der Grundlage von Arbeiten, die von der Android Open Source Project erstellt und gemeinsam verwendet und gemäß den in der 2.5 Attribution License beschriebenen Begriffen verwendet werden.