KeyGenParameterSpec.Builder

KeyGenParameterSpec.Builder

KeyGenParameterSpec.Builder (String keystoreAlias, 
                int purposes)

创建 Builder的新实例。

build

KeyGenParameterSpec build ()

构建一个 KeyGenParameterSpec的实例。

setAlgorithmParameterSpec

KeyGenParameterSpec.Builder setAlgorithmParameterSpec (AlgorithmParameterSpec spec)

设置算法特定的密钥生成参数。 例如，对于RSA密钥，这可以是RSAKeyGenParameterSpec的实例，而对于EC密钥，这可以是ECGenParameterSpec的实例。

这些密钥生成参数必须与其他明确设置的参数（如果有）匹配，例如密钥大小。

setAttestationChallenge

KeyGenParameterSpec.Builder setAttestationChallenge (byte[] attestationChallenge)

设置是否为该密钥对生成证明证书，以及将在证书中放置什么质询值。 认证证书链可以与getCertificateChain(String)一起检索。

如果attestationChallenge不是null ，则此密钥对的公钥证书将包含描述密钥配置和授权详细信息（包括attestationChallenge值）的attestationChallenge 。 如果密钥处于安全硬件中，并且安全硬件支持证明，则证书将通过以可信CA密钥为根的证书链进行签名。 否则，该链将植根于不受信任的证书。

挑战价值的目的是使依赖方能够验证密钥是根据特定请求创建的。 如果需要证明，但不需要挑战，则可以使用任何非null值，包括空字节数组。

如果attestationChallenge为null ，并且此规范用于生成非对称（RSA或EC）密钥对，则如果密钥具有目的PURPOSE_SIGN ，则公钥证书将为自签名。 如果密钥不具有目的PURPOSE_SIGN ，则不可能使用该密钥签署证书，因此公钥证书将包含虚拟签名。

对称密钥（如AES和HMAC密钥）没有公钥证书。 如果getAttestationChallenge()返回非空并且该规范用于生成对称（AES或HMAC）密钥，则generateKey()将抛出InvalidAlgorithmParameterException 。

setBlockModes

KeyGenParameterSpec.Builder setBlockModes (String... blockModes)

设置组的块模式（例如， GCM ， CBC ）与该密钥可以加密/解密时使用。 试图在任何其他模块模式下使用密钥将被拒绝。

这必须为对称加密/解密密钥指定。

见KeyProperties 。 BLOCK_MODE常数。

setCertificateNotAfter

KeyGenParameterSpec.Builder setCertificateNotAfter (Date date)

设置生成的密钥对的自签名证书的有效期结束。

默认情况下，这个日期是 Jan 1 2048 。

setCertificateNotBefore

KeyGenParameterSpec.Builder setCertificateNotBefore (Date date)

设置生成的密钥对的自签名证书的有效期开始。

默认情况下，这个日期是 Jan 1 1970 。

setCertificateSerialNumber

KeyGenParameterSpec.Builder setCertificateSerialNumber (BigInteger serialNumber)

设置用于生成密钥对的自签名证书的序列号。

默认情况下，序列号是 1 。

setCertificateSubject

KeyGenParameterSpec.Builder setCertificateSubject (X500Principal subject)

设置用于生成的密钥对的自签名证书的主题。

默认情况下，主题是 CN=fake 。

setDigests

KeyGenParameterSpec.Builder setDigests (String... digests)

设置组的摘要算法（例如， SHA-256 ， SHA-384 ）与该键可被使用。 试图将密钥与任何其他摘要算法一起使用将被拒绝。

这必须指定用于RSA OAEP填充方案的签名/验证密钥和RSA加密/解密密钥，因为这些操作涉及摘要。 为HMAC键，默认是与密钥算法（例如，相关联的摘要SHA-256为密钥算法HmacSHA256 ）。 HMAC密钥不能被授权用于多个摘要。

对于用于TLS / SSL客户端或服务器身份验证的私钥，通常需要授权使用无摘要（ DIGEST_NONE ）。 这是因为TLS / SSL堆栈通常会自己生成必要的摘要，然后使用私钥对其进行签名。

见KeyProperties 。 DIGEST常数。

setEncryptionPaddings

KeyGenParameterSpec.Builder setEncryptionPaddings (String... paddings)

设置组填充方案（例如， PKCS7Padding ， OAEPPadding ， PKCS1Padding ， NoPadding ）与该密钥可以加密/解密时使用。 尝试将密钥与任何其他填充方案一起使用将被拒绝。

这必须为用于加密/解密的密钥指定。

对于TLS / SSL服务器用于向客户端认证自己的RSA私钥，通常需要授权使用不/任何填充（ ENCRYPTION_PADDING_NONE ）和/或PKCS＃1加密填充（ ENCRYPTION_PADDING_RSA_PKCS1 ）。 这是因为某些密码套件需要RSA解密，并且某些堆栈请求使用不填充的解密，而另一些则请求PKCS＃1填充。

见KeyProperties 。 ENCRYPTION_PADDING常量。

setInvalidatedByBiometricEnrollment

KeyGenParameterSpec.Builder setInvalidatedByBiometricEnrollment (boolean invalidateKey)

设置此密钥是否应在指纹登记时失效。 这仅适用于需要用户身份验证的密钥（请参阅setUserAuthenticationRequired(boolean) ），并且未设置正确的有效持续时间（请参阅setUserAuthenticationValidityDurationSeconds(int) ，这意味着密钥仅对指纹身份验证有效。

默认情况下， invalidateKey为true ，因此只有在指纹认证有效的密钥才会在注册新指纹或删除所有现有指纹时发生不可逆转的无效 。 通过调用invalidateKey设置为false方法可能会改变这种false 。

在注册新手指或取消所有手指注册时使密钥无效可通过确保获得密码的未授权人员无法通过注册自己的手指来获得使用经过指纹认证的密钥来提高安全性。 但是，使密钥无效使得不可能进行与密钥相关的操作，需要一些回退过程来验证用户并设置新的密钥。

setKeySize

KeyGenParameterSpec.Builder setKeySize (int keySize)

设置要生成的密钥的大小（以位为单位）。 例如，对于RSA密钥，这设置模数大小，对于EC密钥，这选择具有匹配字段大小的曲线，并且对于对称密钥，这设置作为其密钥材料的位串的大小。

默认密钥大小是每个密钥算法特有的。 如果密钥大小未通过此方法设置，则应从通过setAlgorithmParameterSpec提供的算法特定参数（如果有）中setAlgorithmParameterSpec 。

setKeyValidityEnd

KeyGenParameterSpec.Builder setKeyValidityEnd (Date endDate)

设置密钥不再有效的时间。

默认情况下，密钥在任何时刻均有效。

setKeyValidityForConsumptionEnd

KeyGenParameterSpec.Builder setKeyValidityForConsumptionEnd (Date endDate)

设置密钥不再有效用于解密和验证的时间。

默认情况下，密钥在任何时刻均有效。

setKeyValidityForOriginationEnd

KeyGenParameterSpec.Builder setKeyValidityForOriginationEnd (Date endDate)

设置密钥不再有效用于加密和签名的时间。

默认情况下，密钥在任何时刻均有效。

setKeyValidityStart

KeyGenParameterSpec.Builder setKeyValidityStart (Date startDate)

设置密钥尚未生效的时间。

默认情况下，密钥在任何时刻均有效。

setRandomizedEncryptionRequired

KeyGenParameterSpec.Builder setRandomizedEncryptionRequired (boolean required)

设置使用此密钥的加密是否必须充分随机化，以便每次为相同的明文生成不同的密文。 所需的正式密码属性在选择明文攻击（ IND-CPA ）下不可区分 。 这个属性很重要，因为它可以缓解由于密文泄露明文信息而导致的几类弱点。 例如，如果一个给定的明文总是产生相同的密文，攻击者可能会看到重复的密文，并能够推断出有关明文的信息。

默认情况下，需要 IND-CPA 。

当需要 IND-CPA时：

• encryption/decryption transformation which do not offer IND-CPA, such as ECB with a symmetric encryption algorithm, or RSA encryption/decryption without padding, are prohibited;
• in block modes which use an IV, such as GCM, CBC, and CTR, caller-provided IVs are rejected when encrypting, to ensure that only random IVs are used.

在禁用此要求之前，请考虑采用以下方法：

• If you are generating a random IV for encryption and then initializing a Cipher using the IV, the solution is to let the Cipher generate a random IV instead. This will occur if the Cipher is initialized for encryption without an IV. The IV can then be queried via getIV().
• If you are generating a non-random IV (e.g., an IV derived from something not fully random, such as the name of the file being encrypted, or transaction ID, or password, or a device identifier), consider changing your design to use a random IV which will then be provided in addition to the ciphertext to the entities which need to decrypt the ciphertext.
• If you are using RSA encryption without padding, consider switching to encryption padding schemes which offer IND-CPA, such as PKCS#1 or OAEP.

setSignaturePaddings

KeyGenParameterSpec.Builder setSignaturePaddings (String... paddings)

设置组填充方案（例如， PSS ， PKCS#1 ）与该密钥可以签名/验证时使用。 尝试将密钥与任何其他填充方案一起使用将被拒绝。

这必须为用于签名/验证的RSA密钥指定。

见KeyProperties 。 SIGNATURE_PADDING常量。

setUserAuthenticationRequired

KeyGenParameterSpec.Builder setUserAuthenticationRequired (boolean required)

设置此密钥是否仅在用户已通过身份验证时才有权使用。

默认情况下，无论用户是否通过身份验证，密钥都有权使用。

当需要用户认证时：

• The key can only be generated if secure lock screen is set up (see isDeviceSecure()). Additionally, if the key requires that user authentication takes place for every use of the key (see setUserAuthenticationValidityDurationSeconds(int)), at least one fingerprint must be enrolled (see hasEnrolledFingerprints()).
• The use of the key must be authorized by the user by authenticating to this Android device using a subset of their secure lock screen credentials such as password/PIN/pattern or fingerprint. More information.
• The key will become irreversibly invalidated once the secure lock screen is disabled (reconfigured to None, Swipe or other mode which does not authenticate the user) or when the secure lock screen is forcibly reset (e.g., by a Device Administrator). Additionally, if the key requires that user authentication takes place for every use of the key, it is also irreversibly invalidated once a new fingerprint is enrolled or once\ no more fingerprints are enrolled, unless setInvalidatedByBiometricEnrollment(boolean) is used to allow validity after enrollment. Attempts to initialize cryptographic operations using such keys will throw KeyPermanentlyInvalidatedException.

此授权仅适用于密钥和私钥操作。 公钥操作不受限制。

setUserAuthenticationValidWhileOnBody

KeyGenParameterSpec.Builder setUserAuthenticationValidWhileOnBody (boolean remainsValid)

设置密钥是否保持授权状态，直到设备从用户身上移除到验证有效期限setUserAuthenticationValidityDurationSeconds(int) （请参阅setUserAuthenticationValidityDurationSeconds(int)和setUserAuthenticationRequired(boolean) ）。 一旦设备从用户身上移除，该密钥将被视为未经授权，用户需要重新进行身份验证才能使用该密钥。 对于没有认证有效期的密钥，此参数不起作用。

同样，在没有身上传感器的设备上，该参数将不起作用; 该设备将始终被视为“贴身”，因此该钥匙将保持授权，直至有效期结束。

setUserAuthenticationValidityDurationSeconds

KeyGenParameterSpec.Builder setUserAuthenticationValidityDurationSeconds (int seconds)

设置用户成功通过身份验证后授权使用此密钥的持续时间（秒）。 如果密钥需要用户身份验证才能使用（请参阅setUserAuthenticationRequired(boolean) ），这会起作用。

默认情况下，如果需要用户身份验证，则必须在每次使用密钥时进行。

涉及需要对每个操作进行用户认证的密钥的加密操作只能使用指纹认证。 这是通过初始化密码操作（实现Signature ， Cipher ， Mac ）与密钥，包成一个FingerprintManager.CryptoObject ，调用FingerprintManager.authenticate与CryptoObject ，并用仅当所述认证成功流密码操作进行。

涉及在成功的用户认证事件之后被授权使用一段时间的密钥的加密操作只能使用安全锁屏认证。 如果用户需要进行身份验证才能继续，则这些加密操作将在初始化期间抛出UserNotAuthenticatedException 。 这种情况可以通过用户解锁Android的安全锁屏或者通过createConfirmDeviceCredentialIntent(CharSequence, CharSequence)启动的确认凭证流程来createConfirmDeviceCredentialIntent(CharSequence, CharSequence) 。 一旦解决，在用户身份验证流程成功完成的情况下，使用此密钥（或任何其他授权在用户身份验证后使用一段固定时间的密钥）初始化新的加密操作应能成功。