Merge "docs: Clarify when certificate is self-signed" into main (69bbd1c8) · Commits · e / os / android_frameworks_base

keystore/java/android/security/keystore/KeyGenParameterSpec.java

+15 −21

Original line number	Diff line number	Diff line
		@@ -75,16 +75,18 @@ import javax.security.auth.x500.X500Principal;
		* {@link java.security.interfaces.ECPublicKey} or {@link java.security.interfaces.RSAPublicKey}
		* interfaces.
		*
		* <p>For asymmetric key pairs, a self-signed X.509 certificate will be also generated and stored in
		* the Android Keystore. This is because the {@link java.security.KeyStore} abstraction does not
		* support storing key pairs without a certificate. The subject, serial number, and validity dates
		* of the certificate can be customized in this spec. The self-signed certificate may be replaced at
		* a later time by a certificate signed by a Certificate Authority (CA).
		*
		* <p>NOTE: If a private key is not authorized to sign the self-signed certificate, then the
		* certificate will be created with an invalid signature which will not verify. Such a certificate
		* is still useful because it provides access to the public key. To generate a valid signature for
		* the certificate the key needs to be authorized for all of the following:
		* <p>For asymmetric key pairs, a X.509 certificate will be also generated and stored in the Android
		* Keystore. This is because the {@link java.security.KeyStore} abstraction does not support storing
		* key pairs without a certificate. The subject, serial number, and validity dates of the
		* certificate can be customized in this spec. The certificate may be replaced at a later time by a
		* certificate signed by a Certificate Authority (CA).
		*
		* <p>NOTE: If attestation is not requested using {@link Builder#setAttestationChallenge(byte[])},
		* generated certificate may be self-signed. If a private key is not authorized to sign the
		* certificate, then the certificate will be created with an invalid signature which will not
		* verify. Such a certificate is still useful because it provides access to the public key. To
		* generate a valid signature for the certificate the key needs to be authorized for all of the
		* following:
		* <ul>
		* <li>{@link KeyProperties#PURPOSE_SIGN},</li>
		* <li>operation without requiring the user to be authenticated (see
		@@ -989,12 +991,6 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		* @param purposes set of purposes (e.g., encrypt, decrypt, sign) for which the key can be
		* used. Attempts to use the key for any other purpose will be rejected.
		*
		* <p>If the set of purposes for which the key can be used does not contain
		* {@link KeyProperties#PURPOSE_SIGN}, the self-signed certificate generated by
		* {@link KeyPairGenerator} of {@code AndroidKeyStore} provider will contain an
		* invalid signature. This is OK if the certificate is only used for obtaining the
		* public key from Android KeyStore.
		*
		* <p>See {@link KeyProperties}.{@code PURPOSE} flags.
		*/
		public Builder(@NonNull String keystoreAlias, @KeyProperties.PurposeEnum int purposes) {
		@@ -1140,7 +1136,7 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		}

		/**
		* Sets the subject used for the self-signed certificate of the generated key pair.
		* Sets the subject used for the certificate of the generated key pair.
		*
		* <p>By default, the subject is {@code CN=fake}.
		*/
		@@ -1154,7 +1150,7 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		}

		/**
		* Sets the serial number used for the self-signed certificate of the generated key pair.
		* Sets the serial number used for the certificate of the generated key pair.
		*
		* <p>By default, the serial number is {@code 1}.
		*/
		@@ -1168,8 +1164,7 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		}

		/**
		* Sets the start of the validity period for the self-signed certificate of the generated
		* key pair.
		* Sets the start of the validity period for the certificate of the generated key pair.
		*
		* <p>By default, this date is {@code Jan 1 1970}.
		*/
		@@ -1183,8 +1178,7 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		}

		/**
		* Sets the end of the validity period for the self-signed certificate of the generated key
		* pair.
		* Sets the end of the validity period for the certificate of the generated key pair.
		*
		* <p>By default, this date is {@code Jan 1 2048}.
		*/