From 069a0af41ff85f37b25ca90e197fe0c00eebf114 Mon Sep 17 00:00:00 2001 From: "Raif S. Naffah" Date: Thu, 19 Jan 2006 09:51:53 +0000 Subject: 2006-01-19 Raif S. Naffah * java/security/interfaces/RSAMultiPrimePrivateCrtKey.java: Replaced what looked like proprietary documentation with original or new one. * java/security/spec/PSSParameterSpec.java: Likewise. * java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java: Likewise. * java/security/spec/RSAOtherPrimeInfo.java: Likewise. * java/security/AlgorithmParameterGenerator.java: Likewise. * java/security/AlgorithmParameters.java: Likewise. * java/security/Identity.java: Likewise. * java/security/IdentityScope.java: Likewise. * java/security/KeyFactory.java: Likewise. * java/security/KeyPairGenerator.java: Likewise. * java/security/MessageDigest.java: Likewise. * java/security/Policy.java: Likewise. * java/security/ProtectionDomain.java: Likewise. * java/security/Security.java: Likewise. * java/security/Signature.java: Likewise. * java/security/SignatureSpi.java: Likewise. * java/security/SignedObject.java: Likewise. * java/security/Signer.java: Likewise. --- java/security/KeyFactory.java | 204 ++++++++++++++++++------------------------ 1 file changed, 89 insertions(+), 115 deletions(-) (limited to 'java/security/KeyFactory.java') diff --git a/java/security/KeyFactory.java b/java/security/KeyFactory.java index 64ce841fa..edb2a87da 100644 --- a/java/security/KeyFactory.java +++ b/java/security/KeyFactory.java @@ -44,40 +44,18 @@ import java.security.spec.InvalidKeySpecException; import java.security.spec.KeySpec; /** - *

Key factories are used to convert keys (opaque cryptographic keys of type + * Key factories are used to convert keys (opaque cryptographic keys of type * {@link Key}) into key specifications (transparent representations of the - * underlying key material), and vice versa.

- * - *

Key factories are bi-directional. That is, they allow you to build an - * opaque key object from a given key specification (key material), or to - * retrieve the underlying key material of a key object in a suitable format.

- * - *

Multiple compatible key specifications may exist for the same key. For - * example, a DSA public key may be specified using {@link - * java.security.spec.DSAPublicKeySpec} or {@link - * java.security.spec.X509EncodedKeySpec}. A key factory can be used to - * translate between compatible key specifications.

- * - *

The following is an example of how to use a key factory in order to - * instantiate a DSA public key from its encoding. Assume Alice has - * received a digital signature from Bob. Bob also sent her his public key (in - * encoded format) to verify his signature. Alice then performs the following - * actions: - * - * 

- *  X509EncodedKeySpec bobPubKeySpec = new X509EncodedKeySpec(bobEncodedPubKey);
- *  KeyFactory keyFactory = KeyFactory.getInstance("DSA");
- *  PublicKey bobPubKey = keyFactory.generatePublic(bobPubKeySpec);
- *  Signature sig = Signature.getInstance("DSA");
- *  sig.initVerify(bobPubKey);
- *  sig.update(data);
- *  sig.verify(signature);
- *
+ * underlying key material). + * + *

Key factories are bi-directional. They allow a key class to be converted + * into a key specification (key material) and back again. For example DSA + * public keys can be specified as DSAPublicKeySpec or + * X509EncodedKeySpec. A key factory translates these key + * specifications.

* * @since 1.2 * @see Key - * @see PublicKey - * @see PrivateKey * @see KeySpec * @see java.security.spec.DSAPublicKeySpec * @see java.security.spec.X509EncodedKeySpec @@ -93,12 +71,15 @@ public class KeyFactory private String algorithm; /** - * Creates a KeyFactory object. - * - * @param keyFacSpi the delegate. - * @param provider the provider. - * @param algorithm the name of the algorithm to associate with this - * KeyFactory. + * Constructs a new instance of KeyFactory with the specified + * parameters. + * + * @param keyFacSpi + * the key factory to use. + * @param provider + * the provider to use. + * @param algorithm + * the name of the key algorithm to use. */ protected KeyFactory(KeyFactorySpi keyFacSpi, Provider provider, String algorithm) @@ -109,19 +90,14 @@ public class KeyFactory } /** - * Generates a KeyFactory object that implements the specified - * algorithm. If the default provider package provides an implementation of - * the requested algorithm, an instance of KeyFactory containing - * that implementation is returned. If the algorithm is not available in the - * default package, other packages are searched. - * - * @param algorithm the name of the requested key algorithm. See Appendix A - * in the Java Cryptography Architecture API Specification & Reference - * for information about standard algorithm names. - * @return a KeyFactory object for the specified algorithm. - * @throws NoSuchAlgorithmException if the requested algorithm is not - * available in the default provider package or any of the other provider - * packages that were searched. + * Returns a new instance of KeyFactory representing the + * specified key factory. + * + * @param algorithm + * the name of algorithm to use. + * @return a new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by any provider. */ public static KeyFactory getInstance(String algorithm) throws NoSuchAlgorithmException @@ -141,19 +117,21 @@ public class KeyFactory } /** - * Generates a KeyFactory object for the specified algorithm - * from the specified provider. - * - * @param algorithm the name of the requested key algorithm. See Appendix A - * in the Java Cryptography Architecture API Specification & Reference - * for information about standard algorithm names. - * @param provider the name of the provider. - * @return a KeyFactory object for the specified algorithm. - * @throws NoSuchAlgorithmException if the algorithm is not available from - * the specified provider. - * @throws NoSuchProviderException if the provider has not been configured. - * @throws IllegalArgumentException if the provider name is null or empty. - * @see Provider + * Returns a new instance of KeyFactory representing the + * specified key factory from the specified provider. + * + * @param algorithm + * the name of algorithm to use. + * @param provider + * the name of the provider to use. + * @return a new instance repesenting the desired algorithm. + * @throws IllegalArgumentException + * if provider is null or is an empty + * string. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the named provider. + * @throws NoSuchProviderException + * if the named provider was not found. */ public static KeyFactory getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException @@ -169,19 +147,18 @@ public class KeyFactory } /** - * Generates a KeyFactory object for the specified algorithm from - * the specified provider. Note: the provider doesn't have to be - * registered. - * - * @param algorithm the name of the requested key algorithm. See Appendix A - * in the Java Cryptography Architecture API Specification & Reference for - * information about standard algorithm names. - * @param provider the provider. - * @return a KeyFactory object for the specified algorithm. - * @throws NoSuchAlgorithmException if the algorithm is not available from - * the specified provider. - * @throws IllegalArgumentException if the provider is - * null. + * Returns a new instance of KeyFactory representing the + * specified key factory from the designated {@link Provider}. + * + * @param algorithm + * the name of algorithm to use. + * @param provider + * the {@link Provider} to use. + * @return a new instance repesenting the desired algorithm. + * @throws IllegalArgumentException + * if provider is null. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by {@link Provider}. * @since 1.4 * @see Provider */ @@ -208,9 +185,9 @@ public class KeyFactory } /** - * Returns the provider of this key factory object. - * - * @return the provider of this key factory object. + * Returns the {@link Provider} of this instance. + * + * @return the {@link Provider} of this instance. */ public final Provider getProvider() { @@ -218,10 +195,9 @@ public class KeyFactory } /** - * Gets the name of the algorithm associated with this KeyFactory. - * - * @return the name of the algorithm associated with this - * KeyFactory. + * Returns the name of the algorithm used. + * + * @return the name of the algorithm used. */ public final String getAlgorithm() { @@ -229,13 +205,13 @@ public class KeyFactory } /** - * Generates a public key object from the provided key specification (key - * material). - * - * @param keySpec the specification (key material) of the public key. + * Generates a public key from the provided key specification. + * + * @param keySpec + * the key specification. * @return the public key. - * @throws InvalidKeySpecException if the given key specification is - * inappropriate for this key factory to produce a public key. + * @throws InvalidKeySpecException + * if the key specification is invalid. */ public final PublicKey generatePublic(KeySpec keySpec) throws InvalidKeySpecException @@ -244,13 +220,13 @@ public class KeyFactory } /** - * Generates a private key object from the provided key specification (key - * material). - * - * @param keySpec the specification (key material) of the private key. + * Generates a private key from the provided key specification. + * + * @param keySpec + * the key specification. * @return the private key. - * @throws InvalidKeySpecException if the given key specification is - * inappropriate for this key factory to produce a private key. + * @throws InvalidKeySpecException + * if the key specification is invalid. */ public final PrivateKey generatePrivate(KeySpec keySpec) throws InvalidKeySpecException @@ -259,21 +235,18 @@ public class KeyFactory } /** - * Returns a specification (key material) of the given key object. - * keySpec identifies the specification class in which the key - * material should be returned. It could, for example, be - * DSAPublicKeySpec.class, to indicate that the key material - * should be returned in an instance of the {@link - * java.security.spec.DSAPublicKeySpec} class. - * - * @param key the key. - * @param keySpec the specification class in which the key material should be - * returned. - * @return the underlying key specification (key material) in an instance of - * the requested specification class. - * @throws InvalidKeySpecException if the requested key specification is - * inappropriate for the given key, or the given key cannot be processed - * (e.g., the given key has an unrecognized algorithm or format). + * Returns a key specification for the given key. keySpec + * identifies the specification class to return the key material in. + * + * @param key + * the key to use. + * @param keySpec + * the specification class to use. + * @return the key specification in an instance of the requested specification + * class. + * @throws InvalidKeySpecException + * the requested key specification is inappropriate for this key or + * the key is unrecognized. */ public final KeySpec getKeySpec(Key key, Class keySpec) throws InvalidKeySpecException @@ -282,13 +255,14 @@ public class KeyFactory } /** - * Translates a key object, whose provider may be unknown or potentially - * untrusted, into a corresponding key object of this key factory. - * - * @param key the key whose provider is unknown or untrusted. + * Translates the key from an unknown or untrusted provider into a key from + * this key factory. + * + * @param key + * the key to translate from. * @return the translated key. - * @throws InvalidKeyException if the given key cannot be processed by this - * key factory. + * @throws InvalidKeyException + * if the key cannot be processed by this key factory. */ public final Key translateKey(Key key) throws InvalidKeyException { -- cgit v1.2.1