KeyProtection.Builder

KeyProtection.Builder

KeyProtection.Builder (int purposes)

创建 Builder的新实例。

build

KeyProtection build ()

构建一个 KeyProtection的实例。

setBlockModes

KeyProtection.Builder setBlockModes (String... blockModes)

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

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

见KeyProperties 。 BLOCK_MODE常量。

setDigests

KeyProtection.Builder setDigests (String... digests)

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

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

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

见KeyProperties 。 DIGEST常数。

setEncryptionPaddings

KeyProtection.Builder setEncryptionPaddings (String... paddings)

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

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

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

见KeyProperties 。 ENCRYPTION_PADDING常数。

setInvalidatedByBiometricEnrollment

KeyProtection.Builder setInvalidatedByBiometricEnrollment (boolean invalidateKey)

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

默认情况下， invalidateKey为true ，因此，仅用于指纹认证的密钥在注册新指纹时或者删除所有现有指纹时都会不可逆转地失效 。 可以通过调用invalidateKey设置为false方法来更改此方法。

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

setKeyValidityEnd

KeyProtection.Builder setKeyValidityEnd (Date endDate)

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

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

setKeyValidityForConsumptionEnd

KeyProtection.Builder setKeyValidityForConsumptionEnd (Date endDate)

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

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

setKeyValidityForOriginationEnd

KeyProtection.Builder setKeyValidityForOriginationEnd (Date endDate)

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

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

setKeyValidityStart

KeyProtection.Builder setKeyValidityStart (Date startDate)

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

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

setRandomizedEncryptionRequired

KeyProtection.Builder setRandomizedEncryptionRequired (boolean required)

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

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

当需要 IND-CPA时：

• transformation which do not offer IND-CPA, such as symmetric ciphers using ECB mode or RSA encryption without padding, are prohibited;
• in transformations which use an IV, such as symmetric ciphers in GCM, CBC, and CTR block modes, 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 padding schemes which offer IND-CPA, such as PKCS#1 or OAEP.

Parameters
required	boolean

Returns
KeyProtection.Builder

setSignaturePaddings

KeyProtection.Builder setSignaturePaddings (String... paddings)

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

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

见KeyProperties 。 SIGNATURE_PADDING常量。

setUserAuthenticationRequired

KeyProtection.Builder setUserAuthenticationRequired (boolean required)

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

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

当需要用户认证时：

• The key can only be import 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

KeyProtection.Builder setUserAuthenticationValidWhileOnBody (boolean remainsValid)

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

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

setUserAuthenticationValidityDurationSeconds

KeyProtection.Builder setUserAuthenticationValidityDurationSeconds (int seconds)

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

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

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

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