KeyGenParameterSpec 類別

定義

[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

繼承

Object

JavaObject

Object

KeyGenParameterSpec

屬性

RegisterAttribute

實作

IJavaObject IJavaPeerable IAlgorithmParameterSpec IDisposable

備註

AlgorithmParameterSpec用於初始化 KeyPairGenerator的 a KeyGenerator 或 a。 規範決定金鑰的授權用途，例如使用金鑰是否需要使用者驗證、授權哪些操作（例如簽名但不需解密）、參數（例如僅限特定填充方案或摘要），以及金鑰的有效開始與結束日期。 規範中所描述的金鑰使用授權僅適用於秘密金鑰與私鑰——公鑰可用於任何支援的操作。

要產生非對稱金鑰對或對稱金鑰，請使用Builder該類別的實例，從提供KeyPairGenerator者初始KeyGeneratorEC化所需金鑰類型（例如，AESKeyProperties或 -- 見 KEY_ALGORITHM. 常AndroidKeyStore數），KeyGenParameterSpec然後使用 KeyGenerator#generateKey() 或 KeyPairGenerator#generateKeyPair()產生金鑰或金鑰對。

產生的金鑰對或金鑰將由產生器回傳，並以本規範指定的別名儲存在 Android 金鑰庫中。若要從 Android Keystore 取得秘密或私密金鑰，請使用 java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null) 或 java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null)。 要從 Android Keystore 取得公鑰，請使用 java.security.KeyStore#getCertificate(String) ，然後 Certificate#getPublicKey()。

為了幫助取得儲存在 Android Keystore 中的密鑰對的演算法專屬公開參數，產生私鑰的 Implement java.security.interfaces.ECKey 或 java.security.interfaces.RSAKey 介面，而公鑰則是 Implement java.security.interfaces.ECPublicKey 或 java.security.interfaces.RSAPublicKey interface。

對於非對稱金鑰對，也會產生並儲存在 Android 金鑰庫中的 X.509 憑證。 這是因為抽象 java.security.KeyStore 化不支援在沒有憑證的情況下儲存金鑰對。 證書的主題、序號及有效日期可在此規範中自訂。該證書可在日後由憑證授權機構（CA）簽署的證書取代。

注意：若未使用 Builder#setAttestationChallenge(byte[])請求認證，產生的證書可自行簽署。 若私鑰未被授權簽署該憑證，則憑證將以無效的簽章建立，無法進行驗證。 這類憑證仍然有用，因為它提供公開金鑰的存取權限。 要產生有效的憑證簽章，金鑰必須獲得以下所有授權<：ul><li>KeyProperties#PURPOSE_SIGN、</li><li>操作且不需使用者認證（參見Builder#setUserAuthenticationRequired(boolean)）、</li><li 此>刻簽署/發起（參見 Builder#setKeyValidityStart(Date) 及Builder#setKeyValidityForOriginationEnd(Date)）、</li><li>適合摘要，</li><li>（僅限 RSA 金鑰）填充方案。KeyProperties#SIGNATURE_PADDING_RSA_PKCS1</li></ul>

注意：產生的對稱與私鑰的金鑰材料無法存取。 公鑰的鑰匙資料是可存取的。

此類別的實例是不可變的。

<h3>已知問題</h3> Android 6.0（API Level 23）中的一個已知錯誤，導致即使是公開金鑰也被強制執行與使用者驗證相關的授權。 為了解決這個問題，請將公開金鑰資料擷取到用於 Android Keystore 以外的資料。 例如：

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

<h3>範例：NIST P-256 EC 金鑰對，用於使用 ECDSA/<h3> 進行簽署/驗證 此範例說明如何在 Android KeyStore 系統中以別名 key1 方式產生 NIST P-256（又名 secp256r1，或 prime256v1）EC 金鑰對，該私鑰僅被授權用於使用 SHA-256、SHA-384 或 SHA-512 摘要簽署，且僅限於使用者在過去五分鐘內完成驗證。 公開金鑰的使用不受限制（參見已知問題）。

{@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>範例：使用 RSA-PSS</h3> 進行簽署/驗證的 RSA 金鑰對 本範例說明如何在 Android KeyStore 系統中產生 RSA 金鑰對，該別名 key1 授權僅用於使用 RSA-PSS 簽名填充方案與 SHA-256 或 SHA-512 摘要進行簽署。 公鑰的使用不受限制。

{@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>範例：使用 RSA OAEP</h3> 進行加密/解密的 RSA 金鑰對 本範例說明如何在 Android KeyStore 系統中以別名 key1 方式產生 RSA 金鑰對，其中私鑰僅被授權用於 RSA OAEP 加密填充方案與 SHA-256 或 SHA-512 摘要進行解密。 公鑰的使用不受限制。

{@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>範例：用於 GCM 模式</h3> 加密/解密的 AES 金鑰 以下範例說明如何在 Android KeyStore 系統中產生 AES 金鑰，該金鑰授權 key2 僅用於 GCM 模式的加密/解密，且無填充。

{@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>範例：使用 SHA-256</h3> 產生 MAC 的 HMAC 金鑰 本範例說明如何在 Android KeyStore 系統中產生 HMAC 金鑰，該別名 key2 僅授權用於使用 SHA-256 產生 HMAC。

{@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”> 範例：ECD 金鑰協議<的 EC 金鑰 - h3> 此範例說明如何產生橢圓曲線金鑰對，用於利用 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 文件 android.security.keystore.KeyGenParameterSpec。

本頁部分內容為基於 Open Source Project 所創建與分享的作品，並依授權條款所描述的使用進行修改。