KeyProtection 類別
定義
重要
部分資訊涉及發行前產品,在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。
規範將金鑰或金鑰對匯入 Android Keystore 系統時如何受到保護。
[Android.Runtime.Register("android/security/keystore/KeyProtection", ApiSince=23, DoNotGenerateAcw=true)]
public sealed class KeyProtection : Java.Lang.Object, IDisposable, Java.Security.KeyStore.IProtectionParameter
[<Android.Runtime.Register("android/security/keystore/KeyProtection", ApiSince=23, DoNotGenerateAcw=true)>]
type KeyProtection = class
inherit Object
interface KeyStore.IProtectionParameter
interface IJavaObject
interface IDisposable
interface IJavaPeerable
- 繼承
- 屬性
- 實作
備註
規範將金鑰或金鑰對匯入 Android Keystore 系統時如何受到保護。 此類別規定匯入金鑰的授權用途,例如使用金鑰是否需要使用者驗證、金鑰被授權執行哪些操作(例如解密但不簽名)、參數(例如僅限特定填充方案或摘要)以及金鑰的有效開始與結束日期。 本類別中表達的金鑰使用授權僅適用於秘密金鑰與私鑰——公鑰可用於任何支援的操作。
要將金鑰或金鑰對匯入 Android Keystore,請使用 建立Builder此類別的實例,並將該實例與匯入的金鑰或金鑰對一同傳遞。java.security.KeyStore#setEntry(String, java.security.KeyStore.Entry, ProtectionParameter) KeyStore.setEntry
若要從 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 中的金鑰對的演算法專屬公開參數,其私鑰用於實作 java.security.interfaces.ECKey 或 java.security.interfaces.RSAKey 介面,而公鑰則用於實作 java.security.interfaces.ECPublicKey 或 java.security.interfaces.RSAPublicKey 介面。
注意:儲存在 Android Keystore 的金鑰材料無法存取。
此類別的實例是不可變的。
<h3>已知問題</h3> Android 6.0(API 等級 23)中的一個已知錯誤導致即使是公開金鑰,使用者驗證相關的授權也會被強制執行。 為了解決這個問題,請將公開金鑰資料擷取到用於 Android Keystore 以外的資料。 例如:
{@code
PublicKey unrestrictedPublicKey =
KeyFactory.getInstance(publicKey.getAlgorithm()).generatePublic(
new X509EncodedKeySpec(publicKey.getEncoded()));
}
<h3>範例:用於 GCM 模式</h3> 加密/解密的 AES 金鑰 此範例說明如何將 AES 金鑰匯入 Android KeyStore 中,且該別名 key1 僅允許在 GCM 模式下用於加密/解密,且不加填充。 該金鑰必須以 格式Key#getEncoded()匯出其鍵內容RAW。
{@code
SecretKey key = ...; // AES key
KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
keyStore.setEntry(
"key1",
new KeyStore.SecretKeyEntry(key),
new KeyProtection.Builder(KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
.setBlockMode(KeyProperties.BLOCK_MODE_GCM)
.setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
.build());
// Key imported, obtain a reference to it.
SecretKey keyStoreKey = (SecretKey) keyStore.getKey("key1", null);
// The original key can now be discarded.
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
cipher.init(Cipher.ENCRYPT_MODE, keyStoreKey);
...
}
<h3>範例:使用 SHA-512</h3> 產生 MAC 的 HMAC 金鑰 此範例說明如何將 HMAC 金鑰匯入 Android KeyStore,別名 key1 僅授權用於使用 SHA-512 摘要產生 MAC。 該金鑰必須以 格式Key#getEncoded()匯出其鍵內容RAW。
{@code
SecretKey key = ...; // HMAC key of algorithm "HmacSHA512".
KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
keyStore.setEntry(
"key1",
new KeyStore.SecretKeyEntry(key),
new KeyProtection.Builder(KeyProperties.PURPOSE_SIGN).build());
// Key imported, obtain a reference to it.
SecretKey keyStoreKey = (SecretKey) keyStore.getKey("key1", null);
// The original key can now be discarded.
Mac mac = Mac.getInstance("HmacSHA512");
mac.init(keyStoreKey);
...
}
<h3>範例:使用 ECDSA/<h3> 進行簽署/驗證的 EC 金鑰對 此範例說明如何將 EC 金鑰對以別名 key2 方式匯入 Android KeyStore,私鑰僅授權用於 SHA-256 或 SHA-512 摘要簽署。 公鑰的使用不受限制。 私鑰與公鑰都必須分別透過 Key#getEncoded() 和 PKCS#8X.509 格式匯出其金鑰資料。
{@code
PrivateKey privateKey = ...; // EC private key
Certificate[] certChain = ...; // Certificate chain with the first certificate
// containing the corresponding EC public key.
KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
keyStore.setEntry(
"key2",
new KeyStore.PrivateKeyEntry(privateKey, certChain),
new KeyProtection.Builder(KeyProperties.PURPOSE_SIGN)
.setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
.build());
// Key pair imported, obtain a reference to it.
PrivateKey keyStorePrivateKey = (PrivateKey) keyStore.getKey("key2", null);
PublicKey publicKey = keyStore.getCertificate("key2").getPublicKey();
// The original private key can now be discarded.
Signature signature = Signature.getInstance("SHA256withECDSA");
signature.initSign(keyStorePrivateKey);
...
}
<h3>範例:使用 PKCS#1 填充</h3> 進行簽署/驗證的 RSA 金鑰對 此範例說明如何將 RSA 金鑰對以別名 key2 方式匯入 Android KeyStore,並以授權僅在使用 PKCS#1 簽章填充方案(搭配 SHA-256 摘要)簽署時使用,且使用者在過去十分鐘內已完成驗證。 公開金鑰的使用不受限制(參見已知問題)。 私鑰與公鑰都必須分別透過 Key#getEncoded() 和 PKCS#8X.509 格式匯出其金鑰資料。
{@code
PrivateKey privateKey = ...; // RSA private key
Certificate[] certChain = ...; // Certificate chain with the first certificate
// containing the corresponding RSA public key.
KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
keyStore.setEntry(
"key2",
new KeyStore.PrivateKeyEntry(privateKey, certChain),
new KeyProtection.Builder(KeyProperties.PURPOSE_SIGN)
.setDigests(KeyProperties.DIGEST_SHA256)
.setSignaturePaddings(KeyProperties.SIGNATURE_PADDING_RSA_PKCS1)
// Only permit this key to be used if the user
// authenticated within the last ten minutes.
.setUserAuthenticationRequired(true)
.setUserAuthenticationValidityDurationSeconds(10 * 60)
.build());
// Key pair imported, obtain a reference to it.
PrivateKey keyStorePrivateKey = (PrivateKey) keyStore.getKey("key2", null);
PublicKey publicKey = keyStore.getCertificate("key2").getPublicKey();
// The original private key can now be discarded.
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(keyStorePrivateKey);
...
}
<h3>範例:使用 PKCS#1 填充</h3> 進行加密/解密的 RSA 金鑰對 此範例示範如何將 RSA 金鑰對以別名 key2 方式匯入 Android KeyStore,並以僅授權用於解密的私鑰,使用 PKCS#1 加密填充方案。 公鑰的使用不受限制,因此允許使用任何填充方案和摘要進行加密。 私鑰與公鑰都必須分別透過 Key#getEncoded() 和 PKCS#8X.509 格式匯出其金鑰資料。
{@code
PrivateKey privateKey = ...; // RSA private key
Certificate[] certChain = ...; // Certificate chain with the first certificate
// containing the corresponding RSA public key.
KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
keyStore.setEntry(
"key2",
new KeyStore.PrivateKeyEntry(privateKey, certChain),
new KeyProtection.Builder(KeyProperties.PURPOSE_DECRYPT)
.setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_RSA_PKCS1)
.build());
// Key pair imported, obtain a reference to it.
PrivateKey keyStorePrivateKey = (PrivateKey) keyStore.getKey("key2", null);
PublicKey publicKey = keyStore.getCertificate("key2").getPublicKey();
// The original private key can now be discarded.
Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
cipher.init(Cipher.DECRYPT_MODE, keyStorePrivateKey);
...
}
Java 文件 android.security.keystore.KeyProtection。
本頁部分內容為基於 Open Source Project 所創建與分享的作品,並依授權條款所描述的使用進行修改。
屬性
| 名稱 | Description |
|---|---|
| Class |
回傳此 |
| Handle |
底層 Android 實例的帳號。 (繼承來源 Object) |
| IsDigestsSpecified |
若指定可用於該金鑰的摘要演算法集合,則回傳 |
| IsInvalidatedByBiometricEnrollment |
若在新生物識別註冊或所有註冊生物識別資料被移除後,該金鑰不可逆轉地失效,則會退還 |
| IsMgf1DigestsSpecified |
|
| IsRandomizedEncryptionRequired |
如果使用此金鑰加密,則返回 |
| IsUnlockedDeviceRequired |
若鑰匙被授權只能在裝置解鎖時使用,則會退貨 |
| IsUserAuthenticationRequired |
若金鑰被授權僅在使用者已認證時使用,則會回傳 |
| IsUserAuthenticationValidWhileOnBody |
如果裝置從使用者身上移除時,金鑰會被取消授權,則會回傳 |
| IsUserConfirmationRequired |
若金鑰被授權僅用於使用者確認的訊息,則會回傳 |
| IsUserPresenceRequired |
若金鑰被授權僅在 與 |
| JniIdentityHashCode |
取得由互通執行時指派給此 Java 對等端的身份雜湊碼。 (繼承來源 Object) |
| JniManagedPeerState |
取得執行時最後指派的狀態旗標。 (繼承來源 JavaObject) |
| JniPeerMembers |
取得用於存取此 Java 綁定成員的 JNI 元資料。 |
| KeyValidityForConsumptionEnd |
取得時間瞬間,之後金鑰不再有效,無法進行解密和驗證。 |
| KeyValidityForOriginationEnd |
會立即獲得該金鑰不再有效用於加密和簽署的時間。 |
| KeyValidityStart |
取得金鑰尚未有效的時間。 |
| MaxUsageCount |
回傳有限使用金鑰允許使用的最大次數,或 |
| Mgf1Digests |
回傳 MGF1 遮罩產生函數可用來 的消化集合(例如 |
| PeerReference |
取得這個 Java 節點的 JNI 物件參考。 (繼承來源 Object) |
| Purposes |
取得金鑰可用於的目的集合(例如加密、解密、簽名)。 |
| ThresholdClass |
此 API 支援 Mono for Android 基礎架構,並非直接從你的程式碼中使用。 (繼承來源 Object) |
| ThresholdType |
此 API 支援 Mono for Android 基礎架構,並非直接從你的程式碼中使用。 (繼承來源 Object) |
| UserAuthenticationType |
取得一組可授權使用金鑰的認證類型。 |
| UserAuthenticationValidityDurationSeconds |
取得使用者成功認證後,該金鑰被授權使用的時間(秒數)。 |
方法
| 名稱 | Description |
|---|---|
| Clone() |
建立並回傳此物件的副本。 (繼承來源 Object) |
| Construct(JniObjectReference, JniObjectReferenceOptions) |
將此對等節點的建置委派給執行時的值管理器。 (繼承來源 JavaObject) |
| Dispose() |
釋放該 Java 節點所持有的資源。 (繼承來源 Object) |
| Dispose(Boolean) |
釋放該 Java 節點所持有的資源。 (繼承來源 Object) |
| DisposeUnlessReferenced() |
請求值管理器處置此對等節點,除非其映射保留該受管理實例。 (繼承來源 JavaObject) |
| Equals(Object) |
測試另一個受管理節點是否參考相同的 Java 物件。 (繼承來源 JavaObject) |
| Equals(Object) |
表示是否有其他物體「等同」於此物。 (繼承來源 Object) |
| GetBlockModes() |
取得一組區塊模式(例如, |
| GetDigests() |
取得可使用該鍵的消化演算法集合(例如, |
| GetEncryptionPaddings() |
取得一組填充方案(例如, |
| GetHashCode() |
回傳物件的雜湊碼值。 (繼承來源 Object) |
| GetSignaturePaddings() |
取得一組填充方案(例如, |
| JavaFinalize() |
已淘汰.
當垃圾回收判定該物件不再有相關參考時,由垃圾回收器呼叫。 (繼承來源 Object) |
| Notify() |
喚醒一個正在該物件監視器上等待的執行緒。 (繼承來源 Object) |
| NotifyAll() |
喚醒所有等待該物件監視器的執行緒。 (繼承來源 Object) |
| SetHandle(IntPtr, JniHandleOwnership) |
設定 Handle 屬性。 (繼承來源 Object) |
| SetPeerReference(JniObjectReference, JniObjectReferenceOptions) |
在控制區塊中儲存參考值,但不建立 JNI 參考副本。 (繼承來源 JavaObject) |
| ToArray<T>() |
從這個 Java 陣列包裝器建立一個受管理陣列。 (繼承來源 Object) |
| ToString() |
回傳物件的字串表示。 (繼承來源 Object) |
| UnregisterFromRuntime() |
將此 Java 節點從互通執行時中取消註冊。 (繼承來源 Object) |
| Wait() |
使目前執行緒等待被喚醒,通常是透過 通知 或 中斷。 (繼承來源 Object) |
| Wait(Int64, Int32) |
使目前執行緒等待被喚醒(通常是透過 通知 或 中斷),或等待一定的實際時間過去。 (繼承來源 Object) |
| Wait(Int64) |
使目前執行緒等待被喚醒(通常是透過 通知 或 中斷),或等待一定的實際時間過去。 (繼承來源 Object) |
明確介面實作
| 名稱 | Description |
|---|---|
| IJavaPeerable.Disposed() |
標記此節點為處置,並以 |
| IJavaPeerable.Finalized() |
標記此節點為處置,並以 |
| IJavaPeerable.JniObjectReferenceControlBlock |
取得此對等端使用的原生控制區塊指標。 (繼承來源 JavaObject) |
| IJavaPeerable.SetJniIdentityHashCode(Int32) |
儲存執行時提供的身份雜湊碼。 (繼承來源 JavaObject) |
| IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates) |
取代儲存的受管理對等狀態旗標。 (繼承來源 JavaObject) |
| IJavaPeerable.SetPeerReference(JniObjectReference) |
當引用無效時,更新對等節點並釋放已拋棄節點的控制區塊。 (繼承來源 JavaObject) |
| IJavaPeerable.UnregisterFromRuntime() |
將此實例從執行時的 Java 物件查詢中移除。 |
擴充方法
| 名稱 | Description |
|---|---|
| GetJniTypeName(IJavaPeerable) |
取得實例 |
| JavaAs<TResult>(IJavaPeerable) |
試著強制 |
| JavaCast<TResult>(IJavaObject) |
執行 Android 執行時檢查型別轉換。 |
| JavaCast<TResult>(IJavaObject) |
重用相容的受管理對等端或取得請求型態的包裝器。 |
| TryJavaCast<TResult>(IJavaPeerable, TResult) |
試著強制 |