Index: ChangeLog =================================================================== RCS file: /cvsroot/classpath/classpath/ChangeLog,v retrieving revision 1.6111 diff -U3 -r1.6111 ChangeLog --- ChangeLog 18 Jan 2006 11:31:12 -0000 1.6111 +++ ChangeLog 18 Jan 2006 19:34:15 -0000 @@ -1,3 +1,25 @@ +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. + 2006-01-18 Roman Kennke * configure.ac: Added --enable-posix-layer option to enable Index: java/security/AlgorithmParameterGenerator.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/AlgorithmParameterGenerator.java,v retrieving revision 1.13 diff -U3 -r1.13 AlgorithmParameterGenerator.java --- java/security/AlgorithmParameterGenerator.java 2 Jul 2005 20:32:40 -0000 1.13 +++ java/security/AlgorithmParameterGenerator.java 18 Jan 2006 19:34:19 -0000 @@ -43,38 +43,15 @@ import java.security.spec.AlgorithmParameterSpec; /** - *

The AlgorithmParameterGenerator class is used to generate a - * set of parameters to be used with a certain algorithm. Parameter generators - * are constructed using the getInstance() factory methods (static - * methods that return instances of a given class).

- * - *

The object that will generate the parameters can be initialized in two - * different ways: in an algorithm-independent manner, or in an - * algorithm-specific manner:

- * - * - * + * AlgorithmParameterGenerator is used to generate algorithm + * parameters for specified algorithms. + * *

In case the client does not explicitly initialize the - * AlgorithmParameterGenerator (via a call to an init() - * method), each provider must supply (and document) a default initialization. - * For example, the GNU provider uses a default modulus prime size of - * 1024 bits for the generation of DSA parameters. + * AlgorithmParameterGenerator (via a call to an + * init() method), each provider must supply (and document) a + * default initialization. For example, the GNU provider uses a default + * modulus prime size of 1024 bits for the generation of DSA + * parameters. * * @author Mark Benvenuto * @since 1.2 @@ -92,11 +69,14 @@ private String algorithm; /** - * Creates an AlgorithmParameterGenerator object. - * - * @param paramGenSpi the delegate. - * @param provider the provider. - * @param algorithm the algorithm. + * Constructs a new instance of AlgorithmParameterGenerator. + * + * @param paramGenSpi + * the generator to use. + * @param provider + * the provider to use. + * @param algorithm + * the algorithm to use. */ protected AlgorithmParameterGenerator(AlgorithmParameterGeneratorSpi paramGenSpi, Provider provider, @@ -107,30 +87,21 @@ this.algorithm = algorithm; } - /** - * Returns the standard name of the algorithm this parameter generator is - * associated with. - * - * @return the string name of the algorithm. - */ + /** @return the name of the algorithm. */ public final String getAlgorithm() { return algorithm; } /** - * Generates an AlgorithmParameterGenerator object that - * implements the specified digest algorithm. If the default provider package - * provides an implementation of the requested digest algorithm, an instance - * of AlgorithmParameterGenerator containing that implementation - * is returned. If the algorithm is not available in the default package, - * other packages are searched. - * - * @param algorithm the string name of the algorithm this parameter generator - * is associated with. - * @return the new AlgorithmParameterGenerator object. - * @throws NoSuchAlgorithmException if the algorithm is not available in the - * environment. + * Returns a new AlgorithmParameterGenerator instance which + * generates algorithm parameters for the specified algorithm. + * + * @param algorithm + * the name of algorithm to use. + * @return the new instance. + * @throws NoSuchAlgorithmException + * if algorithm is not implemented by any provider. */ public static AlgorithmParameterGenerator getInstance(String algorithm) throws NoSuchAlgorithmException @@ -150,20 +121,18 @@ } /** - * Generates an AlgorithmParameterGenerator object for the - * requested algorithm, as supplied from the specified provider, if such a - * parameter generator is available from the provider. - * - * @param algorithm the string name of the algorithm. - * @param provider the string name of the provider. - * @return the new AlgorithmParameterGenerator object. - * @throws NoSuchAlgorithmException if the algorithm is not - * available from the provider. - * @throws NoSuchProviderException if the provider is not - * available in the environment. - * @throws IllegalArgumentException if the provider name is - * null or empty. - * @see Provider + * Returns a new AlgorithmParameterGenerator instance which + * generates algorithm parameters for the specified algorithm. + * + * @param algorithm + * the name of algorithm to use. + * @param provider + * the name of the address@hidden Provider} to use. + * @return the new instance. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the named provider. + * @throws NoSuchProviderException + * if the named provider was not found. */ public static AlgorithmParameterGenerator getInstance(String algorithm, String provider) @@ -180,17 +149,16 @@ } /** - * Generates an AlgorithmParameterGenerator object for the requested - * algorithm, as supplied from the specified provider, if such a parameter - * generator is available from the provider. Note: the provider - * doesn't have to be registered. - * - * @param algorithm the string name of the algorithm. - * @param provider the provider. - * @return the new AlgorithmParameterGenerator object. - * @throws NoSuchAlgorithmException if the algorithm is not available from - * the provider. - * @throws IllegalArgumentException if the provider is null. + * Returns a new AlgorithmParameterGenerator instance which + * generates algorithm parameters for the specified algorithm. + * + * @param algorithm + * the name of algorithm to use. + * @param provider + * the address@hidden Provider} to use. + * @return the new instance. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by address@hidden Provider}. * @since 1.4 * @see Provider */ @@ -218,24 +186,18 @@ } } - /** - * Returns the provider of this algorithm parameter generator object. - * - * @return the provider of this algorithm parameter generator object. - */ + /** @return the address@hidden Provider} of this generator. */ public final Provider getProvider() { return provider; } /** - * Initializes this parameter generator for a certain size. To create - * the parameters, the address@hidden SecureRandom} implementation of the - * highest-priority installed provider is used as the source of randomness. - * (If none of the installed providers supply an implementation of - * address@hidden SecureRandom}, a system-provided source of randomness is used.) - * - * @param size the size (number of bits). + * Initializes this instance with the specified size. Since no source of + * randomness is supplied, a default one will be used. + * + * @param size + * size (in bits) to use. */ public final void init(int size) { @@ -243,11 +205,13 @@ } /** - * Initializes this parameter generator for a certain size and source of + * Initializes this instance with the specified key-size and source of * randomness. - * - * @param size the size (number of bits). - * @param random the source of randomness. + * + * @param size + * the size (in bits) to use. + * @param random + * the address@hidden SecureRandom} to use. */ public final void init(int size, SecureRandom random) { @@ -255,33 +219,30 @@ } /** - * Initializes this parameter generator with a set of algorithm-specific - * parameter generation values. To generate the parameters, the address@hidden - * SecureRandom} implementation of the highest-priority installed provider is - * used as the source of randomness. (If none of the installed providers - * supply an implementation of address@hidden SecureRandom}, a system-provided source - * of randomness is used.) - * - * @param genParamSpec the set of algorithm-specific parameter generation - * values. - * @throws InvalidAlgorithmParameterException if the given parameter - * generation values are inappropriate for this parameter generator. + * Initializes this instance with the specified address@hidden AlgorithmParameterSpec}. + * Since no source of randomness is supplied, a default one will be used. + * + * @param genParamSpec + * the address@hidden AlgorithmParameterSpec} to use. + * @throws InvalidAlgorithmParameterException + * if genParamSpec is invalid. */ public final void init(AlgorithmParameterSpec genParamSpec) - throws InvalidAlgorithmParameterException + throws InvalidAlgorithmParameterException { init(genParamSpec, new SecureRandom()); } /** - * Initializes this parameter generator with a set of algorithm-specific - * parameter generation values. - * - * @param genParamSpec the set of algorithm-specific parameter generation - * values. - * @param random the source of randomness. - * @throws InvalidAlgorithmParameterException if the given parameter - * generation values are inappropriate for this parameter generator. + * Initializes this instance with the specified address@hidden AlgorithmParameterSpec} + * and source of randomness. + * + * @param genParamSpec + * the address@hidden AlgorithmParameterSpec} to use. + * @param random + * the address@hidden SecureRandom} to use. + * @throws InvalidAlgorithmParameterException + * if genParamSpec is invalid. */ public final void init(AlgorithmParameterSpec genParamSpec, SecureRandom random) @@ -290,11 +251,7 @@ paramGenSpi.engineInit(genParamSpec, random); } - /** - * Generates the parameters. - * - * @return the new address@hidden AlgorithmParameters} object. - */ + /** @return a new instance of address@hidden AlgorithmParameters}. */ public final AlgorithmParameters generateParameters() { return paramGenSpi.engineGenerateParameters(); Index: java/security/AlgorithmParameters.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/AlgorithmParameters.java,v retrieving revision 1.13 diff -U3 -r1.13 AlgorithmParameters.java --- java/security/AlgorithmParameters.java 2 Jul 2005 20:32:40 -0000 1.13 +++ java/security/AlgorithmParameters.java 18 Jan 2006 19:34:19 -0000 @@ -45,36 +45,9 @@ import java.security.spec.InvalidParameterSpecException; /** - *

This class is used as an opaque representation of cryptographic - * parameters.

- * - *

An AlgorithmParameters object for managing the parameters - * for a particular algorithm can be obtained by calling one of the - * getInstance() factory methods (static methods that return - * instances of a given class).

- * - *

There are two ways to request such an implementation: by specifying - * either just an algorithm name, or both an algorithm name and a package - * provider.

- * - * - * - *

Once an AlgorithmParameters object is returned, it must be - * initialized via a call to init(), using an appropriate - * parameter specification or parameter encoding.

- * - *

A transparent parameter specification is obtained from an - * AlgorithmParameters object via a call to - * getParameterSpec(), and a byte encoding of the parameters is - * obtained via a call to getEncoded().

+ * AlgorithmParameters is an Algorithm Parameters class which + * provides an interface through which the user can manage the parameters of an + * Algorithm. * * @author Mark Benvenuto * @since 1.2 @@ -92,11 +65,14 @@ private String algorithm; /** - * Creates an AlgorithmParameters object. - * - * @param paramSpi the delegate. - * @param provider the provider. - * @param algorithm the algorithm. + * Constructs a new instance of AlgorithmParameters. + * + * @param paramSpi + * the engine to use. + * @param provider + * the provider to use. + * @param algorithm + * the algorithm to use. */ protected AlgorithmParameters(AlgorithmParametersSpi paramSpi, Provider provider, String algorithm) @@ -106,32 +82,24 @@ this.algorithm = algorithm; } - /** - * Returns the name of the algorithm associated with this parameter object. - * - * @return the algorithm name. - */ + /** @return A string with the name of the algorithm used. */ public final String getAlgorithm() { return algorithm; } /** - *

Generates a parameter object for the specified algorithm.

- * - *

If the default provider package provides an implementation of the - * requested algorithm, an instance of AlgorithmParameters - * containing that implementation is returned. If the algorithm is not - * available in the default package, other packages are searched.

- * - *

The returned parameter object must be initialized via a call to - * init(), using an appropriate parameter specification or - * parameter encoding.

- * - * @param algorithm the name of the algorithm requested. - * @return the new parameter object. - * @throws NoSuchAlgorithmException if the algorithm is not available in the - * environment. + * Returns a new instance of AlgorithmParameters representing + * the specified algorithm parameters. + * + *

The returned AlgorithmParameters must still be initialized + * with an init() method.

+ * + * @param algorithm + * the algorithm to use. + * @return the new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by any provider. */ public static AlgorithmParameters getInstance(String algorithm) throws NoSuchAlgorithmException @@ -152,23 +120,24 @@ } /** - *

Generates a parameter object for the specified algorithm, as supplied - * by the specified provider, if such an algorithm is available from the - * provider.

- * - *

The returned parameter object must be initialized via a call to - * init(), using an appropriate parameter specification or - * parameter encoding.

- * - * @param algorithm the name of the algorithm requested. - * @param provider the name of the provider. - * @return the new parameter object. - * @throws NoSuchAlgorithmException if the algorithm is not available in the - * package supplied by the requested provider. - * @throws NoSuchProviderException if the provider is not available in the - * environment. - * @throws IllegalArgumentException if the provider name is null or empty. - * @see Provider + * Returns a new instance of AlgorithmParameters representing + * the specified algorithm parameters from a named provider. + * + *

The returned AlgorithmParameters must still be intialized + * with an init() method.

+ * + * @param algorithm + * the algorithm to use. + * @param provider + * the name of the address@hidden Provider} to use. + * @return the new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the named provider. + * @throws NoSuchProviderException + * if the named provider was not found. + * @throws IllegalArgumentException + * if provider is null or is an empty + * string. */ public static AlgorithmParameters getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException @@ -184,18 +153,21 @@ } /** - * Generates an AlgorithmParameterGenerator object for the - * requested algorithm, as supplied from the specified provider, if such a - * parameter generator is available from the provider. Note: the - * provider doesn't have to be registered. - * - * @param algorithm the string name of the algorithm. - * @param provider the provider. - * @return the new AlgorithmParameterGenerator object. - * @throws NoSuchAlgorithmException if the algorithm is not - * available from the provider. - * @throws IllegalArgumentException if the provider is - * null. + * Returns a new instance of AlgorithmParameters representing + * the specified algorithm parameters from the specified address@hidden Provider}. + * + *

The returned AlgorithmParameters must still be intialized + * with an init() method.

+ * + * @param algorithm + * the algorithm to use. + * @param provider + * the address@hidden Provider} to use. + * @return the new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the address@hidden Provider}. + * @throws IllegalArgumentException + * if provider is null. * @since 1.4 */ public static AlgorithmParameters getInstance(String algorithm, @@ -221,24 +193,19 @@ } } - /** - * Returns the provider of this parameter object. - * - * @return the provider of this parameter object. - */ + /** @return the provider of this parameter object. */ public final Provider getProvider() { return provider; } /** - * Initializes this parameter object using the parameters specified in - * paramSpec. - * - * @param paramSpec the parameter specification. - * @throws InvalidParameterSpecException if the given parameter specification - * is inappropriate for the initialization of this parameter object, or if - * this parameter object has already been initialized. + * Initializes the engine with the specified address@hidden AlgorithmParameterSpec}. + * + * @param paramSpec + * A address@hidden AlgorithmParameterSpec} to use. + * @throws InvalidParameterSpecException + * if paramSpec is invalid. */ public final void init(AlgorithmParameterSpec paramSpec) throws InvalidParameterSpecException @@ -247,13 +214,15 @@ } /** - * Imports the specified parameters and decodes them according to the primary - * decoding format for parameters. The primary decoding format for parameters - * is ASN.1, if an ASN.1 specification for this type of parameters exists. - * - * @param params the encoded parameters. - * @throws IOException on decoding errors, or if this parameter object has - * already been initialized. + * Initializes the engine with the specified parameters stored in the byte + * array and decodes them according to the ASN.1 specification. If the ASN.1 + * specification exists then it succeeds otherwise an address@hidden IOException} is + * thrown. + * + * @param params + * the parameters to use. + * @throws IOException + * if a decoding error occurs. */ public final void init(byte[]params) throws IOException { @@ -261,15 +230,18 @@ } /** - * Imports the parameters from params and decodes them according to the - * specified decoding scheme. If format is null, - * the primary decoding format for parameters is used. The primary decoding - * format is ASN.1, if an ASN.1 specification for these parameters exists. - * - * @param params the encoded parameters. - * @param format the name of the decoding scheme. - * @throws IOException on decoding errors, or if this parameter object has - * already been initialized. + * Initializes the engine with the specified parameters stored in the byte + * array and decodes them according to the specified decoding specification. + * If format is null, then this method decodes the + * byte array using the ASN.1 specification if it exists, otherwise it throws + * an address@hidden IOException}. + * + * @param params + * the parameters to use. + * @param format + * the name of decoding format to use. + * @throws IOException + * if a decoding error occurs. */ public final void init(byte[]params, String format) throws IOException { @@ -277,19 +249,14 @@ } /** - * Returns a (transparent) specification of this parameter object. - * paramSpec identifies the specification class in which the - * parameters should be returned. It could, for example, be - * DSAParameterSpec.class, to indicate that the parameters should - * be returned in an instance of the address@hidden java.security.spec.DSAParameterSpec} - * class. - * - * @param paramSpec the specification class in which the parameters should be - * returned. + * Returns a new instance of AlgorithmParameters as a + * designated parameter specification address@hidden Class}. + * + * @param paramSpec + * the address@hidden Class} to use. * @return the parameter specification. - * @throws InvalidParameterSpecException if the requested parameter - * specification is inappropriate for this parameter object, or if this - * parameter object has not been initialized. + * @throws InvalidParameterSpecException + * if paramSpec is invalid. */ public final AlgorithmParameterSpec getParameterSpec(Class paramSpec) throws InvalidParameterSpecException @@ -298,13 +265,10 @@ } /** - * Returns the parameters in their primary encoding format. The primary - * encoding format for parameters is ASN.1, if an ASN.1 specification for - * this type of parameters exists. - * - * @return the parameters encoded using their primary encoding format. - * @throws IOException on encoding errors, or if this parameter object has not - * been initialized. + * Returns the parameters in the default encoding format. The primary encoding + * format is ASN.1 if it exists for the specified type. + * + * @return byte array representing the parameters. */ public final byte[] getEncoded() throws IOException { @@ -312,15 +276,16 @@ } /** - * Returns the parameters encoded in the specified scheme. If format is - * null, the primary encoding format for parameters is used. The - * primary encoding format is ASN.1, if an ASN.1 specification for these - * parameters exists. - * - * @param format the name of the encoding format. + * Returns the parameters in the specified encoding format. If + * format is null then the ASN.1 encoding + * format is used if it exists for the specified type. + * + * @param format + * the name of the encoding format to use. * @return the parameters encoded using the specified encoding scheme. - * @throws IOException on encoding errors, or if this parameter object has - * not been initialized. + * @throws IOException + * if an encoding exception occurs, or if this parameter object has + * not been initialized. */ public final byte[] getEncoded(String format) throws IOException { @@ -328,10 +293,9 @@ } /** - * Returns a formatted string describing the parameters. - * - * @return a formatted string describing the parameters, or null - * if this parameter object has not been initialized. + * Returns a string representation of the encoded form. + * + * @return a string representation of the encoded form. */ public final String toString() { Index: java/security/Identity.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/Identity.java,v retrieving revision 1.11 diff -U3 -r1.11 Identity.java --- java/security/Identity.java 15 Sep 2005 14:42:36 -0000 1.11 +++ java/security/Identity.java 18 Jan 2006 19:34:19 -0000 @@ -41,31 +41,27 @@ import java.util.Vector; /** - *

This class represents identities: real-world objects such as people, - * companies or organizations whose identities can be authenticated using their - * public keys. Identities may also be more abstract (or concrete) constructs, - * such as daemon threads or smart cards.

- * - *

All Identity objects have a name and a public key. Names - * are immutable. Identities may also be scoped. That is, if an - * Identity is specified to have a particular scope, then the - * name and public key of the Identity are unique within - * that scope.

- * - *

An Identity also has a set of certificates (all certifying - * its own public key). The Principal names specified in these - * certificates need not be the same, only the key.

- * - *

An Identity can be subclassed, to include postal and email - * addresses, telephone numbers, images of faces and logos, and so on.

+ * The Identity class is used to represent people and companies + * that can be authenticated using public key encryption. The identities can + * also be abstract objects such as smart cards. + * + *

Identity objects store a name and public key for each + * identity. The names cannot be changed and the identities can be scoped. Each + * identity (name and public key) within a scope are unique to that scope.

+ * + *

Each identity has a set of ceritificates which all specify the same + * public key, but not necessarily the same name.

+ * + *

The Identity class can be subclassed to allow additional + * information to be attached to it.

* * @author Mark Benvenuto * @see IdentityScope * @see Signer * @see Principal - * @deprecated This class is no longer used. Its functionality has been replaced - * by java.security.KeyStore, the java.security.cert - * package, and java.security.Principal. + * @deprecated Replaced by java.security.KeyStore, the + * java.security.cert package, and + * java.security.Principal. */ public abstract class Identity implements Principal, Serializable { @@ -83,12 +79,15 @@ } /** - * Constructs an identity with the specified name and scope. - * - * @param name the identity name. - * @param scope the scope of the identity. - * @throws KeyManagementException if there is already an identity with the - * same name in the scope. + * Constructs a new instance of Identity with the specified + * name and scope. + * + * @param name + * the name to use. + * @param scope + * the scope to use. + * @throws KeyManagementException + * if the identity is already present. */ public Identity(String name, IdentityScope scope) throws KeyManagementException @@ -98,9 +97,11 @@ } /** - * Constructs an identity with the specified name and no scope. - * - * @param name the identity name. + * Constructs a new instance of Identity with the specified + * name and no scope. + * + * @param name + * the name to use. */ public Identity(String name) { @@ -108,30 +109,20 @@ this.scope = null; } - /** - * Returns this identity's name. - * - * @return the name of this identity. - */ + /** @return the name of this identity. */ public final String getName() { return name; } - /** - * Returns this identity's scope. - * - * @return the scope of this identity. - */ + /** @return the scope of this identity. */ public final IdentityScope getScope() { return scope; } /** - * Returns this identity's public key. - * - * @return the public key for this identity. + * @return the public key of this identity. * @see #setPublicKey(java.security.PublicKey) */ public PublicKey getPublicKey() @@ -140,21 +131,17 @@ } /** - *

Sets this identity's public key. The old key and all of this identity's - * certificates are removed by this operation.

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with "setIdentityPublicKey" as its - * argument to see if it's ok to set the public key.

- * - * @param key the public key for this identity. - * @throws KeyManagementException if another identity in the identity's scope - * has the same public key, or if another exception occurs. - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow setting the public - * key. - * @see #getPublicKey() - * @see SecurityManager#checkSecurityAccess(String) + * Sets the public key for this identity. The old key and all certificates + * are removed. + * + * @param key + * the public key to use. + * @throws KeyManagementException + * if this public key is used by another identity in the current + * scope. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public void setPublicKey(PublicKey key) throws KeyManagementException { @@ -166,18 +153,13 @@ } /** - *

Specifies a general information string for this identity.

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with "setIdentityInfo" as its - * argument to see if it's ok to specify the information string.

- * - * @param info the information string. - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow setting the - * information string. - * @see #getInfo() - * @see SecurityManager#checkSecurityAccess(String) + * Sets the general information string. + * + * @param info + * the general information string. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public void setInfo(String info) { @@ -189,9 +171,7 @@ } /** - * Returns general information previously specified for this identity. - * - * @return general information about this identity. + * @return the general information string of this identity. * @see #setInfo(String) */ public String getInfo() @@ -200,23 +180,17 @@ } /** - *

Adds a certificate for this identity. If the identity has a public key, - * the public key in the certificate must be the same, and if the identity - * does not have a public key, the identity's public key is set to be that - * specified in the certificate.

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with "addIdentityCertificate" as its - * argument to see if it's ok to add a certificate.

- * - * @param certificate the certificate to be added. - * @throws KeyManagementException if the certificate is not valid, if the - * public key in the certificate being added conflicts with this identity's - * public key, or if another exception occurs. - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow adding a - * certificate. - * @see SecurityManager#checkSecurityAccess(String) + * Adds a certificate to the list of ceritificates for this identity. The + * public key in this certificate must match the existing public key if it + * exists. + * + * @param certificate + * the certificate to add. + * @throws KeyManagementException + * if the certificate is invalid, or the public key conflicts. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public void addCertificate(Certificate certificate) throws KeyManagementException @@ -235,19 +209,15 @@ } /** - *

Removes a certificate from this identity.

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with "removeIdentityCertificate" as - * its argument to see if it's ok to remove a certificate.

- * - * @param certificate the certificate to be removed. - * @throws KeyManagementException if the certificate is missing, or if - * another exception occurs. - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow removing a - * certificate. - * @see SecurityManager#checkSecurityAccess(String) + * Removes a certificate from the list of ceritificates for this identity. + * + * @param certificate + * the certificate to remove. + * @throws KeyManagementException + * if the certificate is invalid. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public void removeCertificate(Certificate certificate) throws KeyManagementException @@ -262,11 +232,7 @@ certificates.removeElement(certificate); } - /** - * Returns a copy of all the certificates for this identity. - * - * @return a copy of all the certificates for this identity. - */ + /** @return an array of address@hidden Certificate}s for this identity. */ public Certificate[] certificates() { Certificate[] certs = new Certificate[certificates.size()]; @@ -278,17 +244,13 @@ } /** - * Tests for equality between the specified object and this identity. This - * first tests to see if the entities actually refer to the same object, in - * which case it returns true. Next, it checks to see if the - * entities have the same name and the same scope. If they do, - * the method returns true. Otherwise, it calls - * identityEquals(), which subclasses should override. - * - * @param identity the object to test for equality with this identity. - * @return true if the objects are considered equal, false - * otherwise. - * @see #identityEquals(Identity) + * Checks for equality between this Identity and a specified object. It first + * checks if they are the same object, then if the name and scope match and + * returns true if successful. If these tests fail, the + * address@hidden #identityEquals(Identity)} method is called. + * + * @return true if they are equal, false + * otherwise. */ public final boolean equals(Object identity) { @@ -307,15 +269,12 @@ } /** - * Tests for equality between the specified identity and this - * identity. This method should be overriden by subclasses to test for - * equality. The default behavior is to return true if the names - * and public keys are equal. - * - * @param identity the identity to test for equality with this identity. - * @return true if the identities are considered equal, - * false otherwise. - * @see #equals(Object) + * Checks for equality between this Identity and a specified object. A + * subclass should override this method. The default behavior is to return + * true if the public key and names match. + * + * @return true if they are equal, false + * otherwise. */ protected boolean identityEquals(Identity identity) { @@ -324,19 +283,12 @@ } /** - *

Returns a short string describing this identity, telling its name and - * its scope (if any).

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with "printIdentity" as its argument - * to see if it's ok to return the string.

- * - * @return information about this identity, such as its name and the name of - * its scope (if any). - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow returning a string - * describing this identity. - * @see SecurityManager#checkSecurityAccess(String) + * Returns a string representation of this Identity. + * + * @return a string representation of this Identity. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public String toString() { @@ -349,23 +301,14 @@ } /** - *

Returns a string representation of this identity, with optionally more - * details than that provided by the toString() method without - * any arguments.

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with "printIdentity" as its argument - * to see if it's ok to return the string.

- * - * @param detailed whether or not to provide detailed information. - * @return information about this identity. If detailed is true, - * then this method returns more information than that provided by the - * toString() method without any arguments. - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow returning a string - * describing this identity. - * @see #toString() - * @see SecurityManager#checkSecurityAccess(String) + * Returns a detailed string representation of this Identity. + * + * @param detailed + * indicates whether or detailed information is desired. + * @return a string representation of this Identity. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public String toString(boolean detailed) { @@ -385,11 +328,7 @@ } } - /** - * Returns a hashcode for this identity. - * - * @return a hashcode for this identity. - */ + /** @return a hashcode of this identity. */ public int hashCode() { int ret = name.hashCode(); Index: java/security/IdentityScope.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/IdentityScope.java,v retrieving revision 1.10 diff -U3 -r1.10 IdentityScope.java --- java/security/IdentityScope.java 2 Jul 2005 20:32:40 -0000 1.10 +++ java/security/IdentityScope.java 18 Jan 2006 19:34:19 -0000 @@ -40,52 +40,42 @@ import java.util.Enumeration; /** - *

This class represents a scope for identities. It is an Identity itself, - * and therefore has a name and can have a scope. It can also optionally have a - * public key and associated certificates.

- * - *

An IdentityScope can contain address@hidden Identity} objects of all - * kinds, including address@hidden Signer}s. All types of Identity objects - * can be retrieved, added, and removed using the same methods. Note that it is - * possible, and in fact expected, that different types of identity scopes will - * apply different policies for their various operations on the various types of + * IdentityScope represents a scope of an identity. + * IdentityScope is also an address@hidden Identity} and can have a name + * and scope along with the other qualitites identities possess. + * + *

An IdentityScope contains other address@hidden Identity} objects. + * All address@hidden Identity} objects are manipulated in the scope the same way. The + * scope is supposed to apply different scope to different type of * Identities.

- * - *

There is a one-to-one mapping between keys and identities, and there can - * only be one copy of one key per scope. For example, suppose Acme Software, - * Inc is a software publisher known to a user. Suppose it is an Identity, - * that is, it has a public key, and a set of associated certificates. It is - * named in the scope using the name "Acme Software". No other named Identity - * in the scope has the same public key. Of course, none has the same name - * as well.

- * + * + *

No identity within the same scope can have the same public key.

+ * * @author Mark Benvenuto * @see Identity * @see Signer * @see Principal * @see Key - * @deprecated This class is no longer used. Its functionality has been replaced - * by java.security.KeyStore, the java.security.cert - * package, and java.security.Principal. + * @deprecated Use java.security.KeyStore, the java.security.cert package, and + * java.security.Principal. */ public abstract class IdentityScope extends Identity { private static final long serialVersionUID = -2337346281189773310L; private static IdentityScope systemScope; - /** - * This constructor is used for serialization only and should not be used by - * subclasses. - */ + /** Constructor for serialization purposes. */ protected IdentityScope() { super(); } /** - * Constructs a new identity scope with the specified name. - * - * @param name the scope name. + * Constructs a new instance of IdentityScope with the + * specified name and no scope. + * + * @param name + * the name to use. */ public IdentityScope(String name) { @@ -93,12 +83,15 @@ } /** - * Constructs a new identity scope with the specified name and scope. - * - * @param name the scope name. - * @param scope the scope for the new identity scope. - * @throws KeyManagementException if there is already an identity with the - * same name in the scope. + * Constructs a new instance of IdentityScope with the + * specified name and address@hidden IdentityScope}. + * + * @param name + * the name to use. + * @param scope + * the scope to use. + * @throws KeyManagementException + * if the identity scope is already present. */ public IdentityScope(String name, IdentityScope scope) throws KeyManagementException @@ -107,10 +100,9 @@ } /** - * Returns the system's identity scope. - * - * @return the system's identity scope. - * @see #setSystemScope(IdentityScope) + * Returns the system's Scope. + * + * @return the system's Scope. */ public static IdentityScope getSystemScope() { @@ -123,18 +115,13 @@ } /** - * Sets the system's identity scope. - * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with "setSystemScope" as its argument - * to see if it's ok to set the identity scope.

- * - * @param scope the scope to set. - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow setting the - * identity scope. - * @see #getSystemScope() - * @see SecurityManager#checkSecurityAccess(String) + * Sets the scope of the system. + * + * @param scope + * the new system scope. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ protected static void setSystemScope(IdentityScope scope) { @@ -146,29 +133,30 @@ } /** - * Returns the number of identities within this identity scope. - * - * @return the number of identities within this identity scope. + * Returns the number of entries within this IdentityScope. + * + * @return the number of entries within this IdentityScope. */ public abstract int size(); /** - * Returns the identity in this scope with the specified name (if any). - * - * @param name the name of the identity to be retrieved. - * @return the identity named name, or null if there are no - * identities named name in this scope. + * Returns the specified address@hidden Identity}, by name, within this scope. + * + * @param name + * name of address@hidden Identity} to get. + * @return an address@hidden Identity} representing the name or null if + * it cannot be found. */ public abstract Identity getIdentity(String name); /** - * Retrieves the identity whose name is the same as that of the specified - * principal. (Note: Identity implements Principal.) - * - * @param principal the principal corresponding to the identity to be - * retrieved. - * @return the identity whose name is the same as that of the principal, or - * null if there are no identities of the same name in this scope. + * Returns the specified address@hidden Identity}, by address@hidden Principal}, within this + * scope. + * + * @param principal + * the address@hidden Principal} to use. + * @return an identity representing the address@hidden Principal} or null + * if it cannot be found. */ public Identity getIdentity(Principal principal) { @@ -176,48 +164,50 @@ } /** - * Retrieves the identity with the specified public key. - * - * @param key the public key for the identity to be returned. - * @return the identity with the given key, or null if there are - * no identities in this scope with that key. + * Returns the specified address@hidden Identity}, by public key, within this scope. + * + * @param key + * the address@hidden PublicKey} to use. + * @return an identity representing the public key or null if + * it cannot be found. */ public abstract Identity getIdentity(PublicKey key); /** - * Adds an identity to this identity scope. - * - * @param identity the identity to be added. - * @throws KeyManagementException if the identity is not valid, a name - * conflict occurs, another identity has the same public key as the identity - * being added, or another exception occurs. + * Adds an identity to his scope. + * + * @param identity + * the address@hidden Identity} to add. + * @throws KeyManagementException + * if it is an invalid identity, an identity with the same key + * exists, or if another error occurs. */ public abstract void addIdentity(Identity identity) throws KeyManagementException; /** - * Removes an identity from this identity scope. - * - * @param identity the identity to be removed. - * @throws KeyManagementException if the identity is missing, or another - * exception occurs. + * Removes an identity in this scope. + * + * @param identity + * the address@hidden Identity} to remove. + * @throws KeyManagementException + * if it is a missing identity, or if another error occurs. */ public abstract void removeIdentity(Identity identity) throws KeyManagementException; /** - * Returns an enumeration of all identities in this identity scope. - * - * @return an enumeration of all identities in this identity scope. + * Returns an address@hidden Enumeration} of identities in this scope. + * + * @return an address@hidden Enumeration} of the identities in this scope. */ public abstract Enumeration identities(); /** - * Returns a string representation of this identity scope, including its name, - * its scope name, and the number of identities in this identity scope. - * - * @return a string representation of this identity scope. - * @see SecurityManager#checkSecurityAccess(String) + * Returns a string representing this instance. It includes the name, the + * scope name, and number of identities. + * + * @return a string representation of this instance. */ public String toString() { Index: java/security/KeyFactory.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/KeyFactory.java,v retrieving revision 1.12 diff -U3 -r1.12 KeyFactory.java --- java/security/KeyFactory.java 2 Jul 2005 20:32:40 -0000 1.12 +++ java/security/KeyFactory.java 18 Jan 2006 19:34:19 -0000 @@ -44,40 +44,18 @@ 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 * address@hidden 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 address@hidden - * java.security.spec.DSAPublicKeySpec} or address@hidden - * 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 @@ 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 @@ } /** - * 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 @@ } /** - * 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 @@ } /** - * 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 address@hidden Provider}. + * + * @param algorithm + * the name of algorithm to use. + * @param provider + * the address@hidden 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 address@hidden Provider}. * @since 1.4 * @see Provider */ @@ -208,9 +185,9 @@ } /** - * Returns the provider of this key factory object. - * - * @return the provider of this key factory object. + * Returns the address@hidden Provider} of this instance. + * + * @return the address@hidden Provider} of this instance. */ public final Provider getProvider() { @@ -218,10 +195,9 @@ } /** - * 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 @@ } /** - * 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 @@ } /** - * 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 @@ } /** - * 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 address@hidden - * 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 @@ } /** - * 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 { Index: java/security/KeyPairGenerator.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/KeyPairGenerator.java,v retrieving revision 1.15 diff -U3 -r1.15 KeyPairGenerator.java --- java/security/KeyPairGenerator.java 9 Aug 2005 06:13:54 -0000 1.15 +++ java/security/KeyPairGenerator.java 18 Jan 2006 19:34:19 -0000 @@ -43,72 +43,14 @@ import java.security.spec.AlgorithmParameterSpec; /** - *

The KeyPairGenerator class is used to generate pairs of - * public and private keys. Key pair generators are constructed using the - * getInstance() factory methods (static methods that return - * instances of a given class).

+ * KeyPairGenerator is a class used to generate key-pairs for a + * security algorithm. + * + *

The KeyPairGenerator is created with the + * getInstance() Factory methods. It is used to generate a pair of + * public and private keys for a specific algorithm and associate this key-pair + * with the algorithm parameters it was initialized with.

* - *

A Key pair generator for a particular algorithm creates a public/private - * key pair that can be used with this algorithm. It also associates - * algorithm-specific parameters with each of the generated keys.

- * - *

There are two ways to generate a key pair: in an algorithm-independent - * manner, and in an algorithm-specific manner. The only difference between the - * two is the initialization of the object:

- * - * - * - *

In case the client does not explicitly initialize the - * KeyPairGenerator (via a call to an initialize method), each - * provider must supply (and document) a default initialization. For example, - * the GNU provider uses a default modulus size (keysize) of - * 1024 bits.

- * - *

Note that this class is abstract and extends from address@hidden - * KeyPairGeneratorSpi} for historical reasons. Application developers should - * only take notice of the methods defined in this KeyPairGenerator - * class; all the methods in the superclass are intended for cryptographic - * service providers who wish to supply their own implementations of key pair - * generators.

- * - * @see Signature * @see KeyPair * @see AlgorithmParameterSpec * @author Mark Benvenuto @@ -123,13 +65,10 @@ private String algorithm; /** - * Creates a KeyPairGenerator object for the specified - * algorithm. - * - * @param algorithm the standard string name of the algorithm. - * See Appendix A in the Java Cryptography Architecture API - * Specification & Reference for information about standard - * algorithm names. + * Constructs a new instance of KeyPairGenerator. + * + * @param algorithm + * the algorithm to use. */ protected KeyPairGenerator(String algorithm) { @@ -138,11 +77,9 @@ } /** - * Returns the standard name of the algorithm for this key pair generator. - * See Appendix A in the Java Cryptography Architecture API Specification - * & Reference for information about standard algorithm names. - * - * @return the standard string name of the algorithm. + * Returns the name of the algorithm used. + * + * @return the name of the algorithm used. */ public String getAlgorithm() { @@ -150,19 +87,14 @@ } /** - * Generates a KeyPairGenerator object that implements the - * specified digest algorithm. If the default provider package provides an - * implementation of the requested digest algorithm, an instance of - * KeyPairGenerator containing that implementation is returned. - * If the algorithm is not available in the default package, other packages - * are searched. - * - * @param algorithm the standard string name of the algorithm. See Appendix A - * in the Java Cryptography Architecture API Specification & Reference for - * information about standard algorithm names. - * @return the new KeyPairGenerator object. - * @throws NoSuchAlgorithmException if the algorithm is not available in the - * environment. + * Returns a new instance of KeyPairGenerator which generates + * key-pairs for the specified algorithm. + * + * @param algorithm + * the name of the algorithm to use. + * @return a new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by any provider. */ public static KeyPairGenerator getInstance(String algorithm) throws NoSuchAlgorithmException @@ -184,22 +116,18 @@ } /** - * Generates a KeyPairGenerator object implementing the - * specified algorithm, as supplied from the specified provider, if - * such an algorithm is available from the provider. - * - * @param algorithm the standard string name of the algorithm. See - * Appendix A in the Java Cryptography Architecture API Specification - * & Reference for information about standard algorithm names. - * @param provider the string name of the provider. - * @return the new KeyPairGenerator object. - * @throws NoSuchAlgorithmException if the algorithm is not available - * from the provider. - * @throws NoSuchProviderException if the provider is not available in the - * environment. - * @throws IllegalArgumentException if the provider name is null - * or empty. - * @see Provider + * Returns a new instance of KeyPairGenerator which generates + * key-pairs for the specified algorithm from a named provider. + * + * @param algorithm + * the name of the algorithm to use. + * @param provider + * the name of a address@hidden Provider} to use. + * @return a new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the named provider. + * @throws NoSuchProviderException + * if the named provider was not found. */ public static KeyPairGenerator getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException @@ -212,20 +140,18 @@ } /** - * Generates a KeyPairGenerator object implementing the specified - * algorithm, as supplied from the specified provider, if such an algorithm is - * available from the provider. Note: the provider doesn't have to be - * registered. - * - * @param algorithm the standard string name of the algorithm. See Appendix A - * in the Java Cryptography Architecture API Specification & Reference for - * information about standard algorithm names. - * @param provider the provider. - * @return the new KeyPairGenerator object. - * @throws NoSuchAlgorithmException if the algorithm is not - * available from the provider. - * @throws IllegalArgumentException if the provider is - * null. + * Returns a new instance of KeyPairGenerator which generates + * key-pairs for the specified algorithm from a designated address@hidden Provider}. + * + * @param algorithm + * the name of the algorithm to use. + * @param provider + * the address@hidden Provider} to use. + * @return a new insatnce repesenting the desired algorithm. + * @throws IllegalArgumentException + * if provider is null. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the address@hidden Provider}. * @since 1.4 * @see Provider */ @@ -261,9 +187,9 @@ } /** - * Returns the provider of this key pair generator object. - * - * @return the provider of this key pair generator object. + * Returns the address@hidden Provider} of this instance. + * + * @return the address@hidden Provider} of this instance. */ public final Provider getProvider() { @@ -271,16 +197,11 @@ } /** - * Initializes the key pair generator for a certain keysize using a default - * parameter set and the address@hidden SecureRandom} implementation of the - * highest-priority installed provider as the source of randomness. (If none - * of the installed providers supply an implementation of address@hidden SecureRandom}, - * a system-provided source of randomness is used.) - * - * @param keysize the keysize. This is an algorithm-specific metric, such as - * modulus length, specified in number of bits. - * @throws InvalidParameterException if the keysize is not supported by this - * KeyPairGenerator object. + * Initializes this instance for the specified key size. Since no source of + * randomness is specified, a default one will be used. + * + * @param keysize + * the size of keys to use. */ public void initialize(int keysize) { @@ -288,14 +209,13 @@ } /** - * Initializes the key pair generator for a certain keysize with the given - * source of randomness (and a default parameter set). - * - * @param keysize the keysize. This is an algorithm-specific metric, such as - * modulus length, specified in number of bits. - * @param random the source of randomness. - * @throws InvalidParameterException if the keysize is not - * supported by this KeyPairGenerator object. + * Initializes this instance for the specified key size and + * address@hidden SecureRandom}. + * + * @param keysize + * the size of keys to use. + * @param random + * the address@hidden SecureRandom} to use. * @since 1.2 */ public void initialize(int keysize, SecureRandom random) @@ -303,24 +223,14 @@ } /** - *

Initializes the key pair generator using the specified parameter set and - * the address@hidden SecureRandom} implementation of the highest-priority installed - * provider as the source of randomness. (If none of the installed providers - * supply an implementation of address@hidden SecureRandom}, a system-provided source - * of randomness is used.)

- * - *

This concrete method has been added to this previously-defined abstract - * class. This method calls the - * address@hidden KeyPairGeneratorSpi#initialize(AlgorithmParameterSpec, SecureRandom)} - * initialize method, passing it params and a source of - * randomness (obtained from the highest-priority installed provider or - * system-provided if none of the installed providers supply one). That - * initialize method always throws an address@hidden UnsupportedOperationException} - * if it is not overridden by the provider.

- * - * @param params the parameter set used to generate the keys. - * @throws InvalidAlgorithmParameterException if the given parameters are - * inappropriate for this key pair generator. + * Initializes this instance with the specified + * address@hidden AlgorithmParameterSpec}. Since no source of randomness is specified, + * a default one will be used. + * + * @param params + * the address@hidden AlgorithmParameterSpec} to use. + * @throws InvalidAlgorithmParameterException + * if the designated specifications are invalid. * @since 1.2 */ public void initialize(AlgorithmParameterSpec params) @@ -330,20 +240,15 @@ } /** - *

Initializes the key pair generator with the given parameter set and - * source of randomness.

- * - *

This concrete method has been added to this previously-defined abstract - * class. This method calls the - * address@hidden KeyPairGeneratorSpi#initialize(AlgorithmParameterSpec, SecureRandom)} - * initialize method, passing it params and random. - * That initialize method always throws an address@hidden UnsupportedOperationException} - * if it is not overridden by the provider.

- * - * @param params the parameter set used to generate the keys. - * @param random the source of randomness. - * @throws InvalidAlgorithmParameterException if the given parameters are - * inappropriate for this key pair generator. + * Initializes this instance with the specified address@hidden AlgorithmParameterSpec} + * and address@hidden SecureRandom}. + * + * @param params + * the address@hidden AlgorithmParameterSpec} to use. + * @param random + * the address@hidden SecureRandom} to use. + * @throws InvalidAlgorithmParameterException + * if the designated specifications are invalid. * @since 1.2 */ public void initialize(AlgorithmParameterSpec params, SecureRandom random) @@ -353,17 +258,12 @@ } /** - *

Generates a key pair.

- * - *

If this KeyPairGenerator has not been initialized - * explicitly, provider-specific defaults will be used for the size and other - * (algorithm-specific) values of the generated keys.

- * - *

This will generate a new key pair every time it is called.

- * - *

This method is functionally equivalent to address@hidden #generateKeyPair()}.

- * - * @return the generated key pair. + * Generates a new "DSA" address@hidden KeyPair} from the "GNU" security provider. + * + *

This method generates a unique key-pair each time it is called.

+ * + * @return a new unique address@hidden KeyPair}. + * @see #generateKeyPair() * @since 1.2 */ public final KeyPair genKeyPair() @@ -381,17 +281,12 @@ } /** - *

Generates a key pair.

- * - *

If this KeyPairGenerator has not been initialized - * explicitly, provider-specific defaults will be used for the size and other - * (algorithm-specific) values of the generated keys.

- * - *

This will generate a new key pair every time it is called.

- * - *

This method is functionally equivalent to address@hidden #genKeyPair()}.

- * - * @return the generated key pair. + * Generates a new "DSA" address@hidden KeyPair} from the "GNU" security provider. + * + *

This method generates a unique key pair each time it is called.

+ * + * @return a new unique address@hidden KeyPair}. + * @see #genKeyPair() */ public KeyPair generateKeyPair() { Index: java/security/MessageDigest.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/MessageDigest.java,v retrieving revision 1.14 diff -U3 -r1.14 MessageDigest.java --- java/security/MessageDigest.java 1 Jan 2006 14:03:45 -0000 1.14 +++ java/security/MessageDigest.java 18 Jan 2006 19:34:20 -0000 @@ -40,54 +40,10 @@ import gnu.java.security.Engine; /** - *

This MessageDigest class provides applications the - * functionality of a message digest algorithm, such as MD5 or SHA. * Message digests are secure one-way hash functions that take arbitrary-sized - * data and output a fixed-length hash value.

- * - *

A MessageDigest object starts out initialized. The data is - * processed through it using the update() methods. At any point - * reset() can be called to reset the digest. Once all the data to - * be updated has been updated, one of the digest() methods should - * be called to complete the hash computation.

- * - *

The digest() method can be called once for a given - * number of updates. After digest() has been called, the - * MessageDigest object is reset to its initialized state. - *

- * - *

Implementations are free to implement the address@hidden Cloneable} interface. - * Client applications can test cloneability by attempting cloning and catching - * the address@hidden CloneNotSupportedException}: - * - * 

- *    MessageDigest md = MessageDigest.getInstance("SHA");
- *    try
- *      {
- *        md.update(toChapter1);
- *        MessageDigest tc1 = md.clone();
- *        byte[] toChapter1Digest = tc1.digest();
- *        md.update(toChapter2);
- *        // ...
- *      }
- *    catch (CloneNotSupportedException x)
- *      {
- *        throw new DigestException("couldn't make digest of partial content");
- *      }
- *
- * - *

Note that if a given implementation is not cloneable, it is still possible - * to compute intermediate digests by instantiating several instances, if the - * number of digests is known in advance.

- * - *

Note that this class is abstract and extends from address@hidden MessageDigestSpi} - * for historical reasons. Application developers should only take notice of the - * methods defined in this MessageDigest class; all the methods in - * the superclass are intended for cryptographic service providers who wish to - * supply their own implementations of message digest algorithms.

+ * data and output a fixed-length hash value. * * @see MessageDigestSpi - * @see Provider * @since JDK 1.1 */ public abstract class MessageDigest extends MessageDigestSpi @@ -100,12 +56,11 @@ private byte[] lastDigest; /** - * Creates a message digest with the specified algorithm name. - * - * @param algorithm the standard name of the digest algorithm. - * See Appendix A in the Java Cryptography Architecture API - * Specification & Reference for information about standard - * algorithm names. + * Constructs a new instance of MessageDigest representing the + * specified algorithm. + * + * @param algorithm + * the name of the digest algorithm to use. */ protected MessageDigest(String algorithm) { @@ -114,19 +69,14 @@ } /** - * Generates a MessageDigest object that implements the specified - * digest algorithm. If the default provider package provides an - * implementation of the requested digest algorithm, an instance of - * MessageDigest 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 algorithm requested. See Appendix A in the - * Java Cryptography Architecture API Specification & Reference for - * information about standard algorithm names. - * @return a Message Digest object implementing the specified algorithm. - * @throws NoSuchAlgorithmException if the algorithm is not available in the - * caller's environment. + * Returns a new instance of MessageDigest representing the + * specified algorithm. + * + * @param algorithm + * the name of the digest algorithm to use. + * @return a new instance representing the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by any provider. */ public static MessageDigest getInstance(String algorithm) throws NoSuchAlgorithmException @@ -148,21 +98,18 @@ } /** - * Generates a MessageDigest object implementing the specified - * algorithm, as supplied from the specified provider, if such an algorithm is - * available from the provider. - * - * @param algorithm the name of the algorithm requested. 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 Message Digest object implementing the specified algorithm. - * @throws NoSuchAlgorithmException if the algorithm is not available in the - * package supplied by the requested provider. - * @throws NoSuchProviderException if the provider is not available in the - * environment. - * @throws IllegalArgumentException if the provider name is null or empty. - * @see Provider + * Returns a new instance of MessageDigest representing the + * specified algorithm from a named provider. + * + * @param algorithm + * the name of the digest algorithm to use. + * @param provider + * the name of the provider to use. + * @return a new instance representing the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the named provider. + * @throws NoSuchProviderException + * if the named provider was not found. */ public static MessageDigest getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException @@ -181,20 +128,18 @@ } /** - * Generates a MessageDigest object implementing the specified - * algorithm, as supplied from the specified provider, if such an algorithm - * is available from the provider. Note: the provider doesn't have to be - * registered. - * - * @param algorithm the name of the algorithm requested. See Appendix A in - * the Java Cryptography Architecture API Specification & Reference for - * information about standard algorithm names. - * @param provider the provider. - * @return a Message Digest object implementing the specified algorithm. - * @throws NoSuchAlgorithmException if the algorithm is not - * available in the package supplied by the requested provider. - * @throws IllegalArgumentException if the provider is - * null. + * Returns a new instance of MessageDigest representing the + * specified algorithm from a designated address@hidden Provider}. + * + * @param algorithm + * the name of the digest algorithm to use. + * @param provider + * the address@hidden Provider} to use. + * @return a new instance representing the desired algorithm. + * @throws IllegalArgumentException + * if provider is null. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by address@hidden Provider}. * @since 1.4 * @see Provider */ @@ -233,9 +178,9 @@ } /** - * Returns the provider of this message digest object. - * - * @return the provider of this message digest object. + * Returns the address@hidden Provider} of this instance. + * + * @return the address@hidden Provider} of this instance. */ public final Provider getProvider() { @@ -243,9 +188,9 @@ } /** - * Updates the digest using the specified byte. - * - * @param input the byte with which to update the digest. + * Updates the digest with the byte. + * + * @param input byte to update the digest with. */ public void update(byte input) { @@ -253,12 +198,15 @@ } /** - * Updates the digest using the specified array of bytes, starting at the - * specified offset. - * - * @param input the array of bytes. - * @param offset the offset to start from in the array of bytes. - * @param len the number of bytes to use, starting at offset. + * Updates the digest with the bytes from the array starting from the + * specified offset and using the specified length of bytes. + * + * @param input + * bytes to update the digest with. + * @param offset + * the offset to start at. + * @param len + * length of the data to update with. */ public void update(byte[] input, int offset, int len) { @@ -266,9 +214,9 @@ } /** - * Updates the digest using the specified array of bytes. - * - * @param input the array of bytes. + * Updates the digest with the bytes of an array. + * + * @param input bytes to update the digest with. */ public void update(byte[] input) { @@ -276,10 +224,9 @@ } /** - * Completes the hash computation by performing final operations such as - * padding. The digest is reset after this call is made. - * - * @return the array of bytes for the resulting hash value. + * Computes the final digest of the stored data. + * + * @return a byte array representing the message digest. */ public byte[] digest() { @@ -287,14 +234,15 @@ } /** - * Completes the hash computation by performing final operations such as - * padding. The digest is reset after this call is made. - * - * @param buf An output buffer for the computed digest. - * @param offset The offset into the output buffer to begin storing the digest. - * @param len The number of bytes within buf allotted for the digest. - * @return The number of bytes placed into buf. - * @throws DigestException if an error occurs. + * Computes the final digest of the stored bytes and returns the result. + * + * @param buf + * an array of bytes to store the result in. + * @param offset + * an offset to start storing the result at. + * @param len + * the length of the buffer. + * @return Returns the length of the buffer. */ public int digest(byte[] buf, int offset, int len) throws DigestException { @@ -302,13 +250,13 @@ } /** - * Performs a final update on the digest using the specified array of bytes, - * then completes the digest computation. That is, this method first calls - * update(input), passing the input array to the update() - * method, then calls digest(). - * - * @param input the input to be updated before the digest is completed. - * @return the array of bytes for the resulting hash value. + * Computes a final update using the input array of bytes, then computes a + * final digest and returns it. It calls address@hidden #update(byte[])} and then + * address@hidden #digest(byte[])}. + * + * @param input + * an array of bytes to perform final update with. + * @return a byte array representing the message digest. */ public byte[] digest(byte[] input) { @@ -317,9 +265,9 @@ } /** - * Returns a string representation of this message digest object. - * - * @return a string representation of the object. + * Returns a string representation of this instance. + * + * @return a string representation of this instance. */ public String toString() { @@ -327,12 +275,14 @@ } /** - * Compares two digests for equality. Does a simple byte compare. - * - * @param digesta one of the digests to compare. - * @param digestb the other digest to compare. - * @return true if the digests are equal, false - * otherwise. + * Does a simple byte comparison of the two digests. + * + * @param digesta + * first digest to compare. + * @param digestb + * second digest to compare. + * @return true if both are equal, false + * otherwise. */ public static boolean isEqual(byte[] digesta, byte[] digestb) { @@ -346,20 +296,16 @@ return true; } - /** Resets the digest for further use. */ + /** Resets this instance. */ public void reset() { engineReset(); } /** - * Returns a string that identifies the algorithm, independent of - * implementation details. The name should be a standard Java Security name - * (such as "SHA", "MD5", and so on). See Appendix - * A in the Java Cryptography Architecture API Specification & Reference - * for information about standard algorithm names. - * - * @return the name of the algorithm. + * Returns the name of message digest algorithm. + * + * @return the name of message digest algorithm. */ public final String getAlgorithm() { @@ -367,12 +313,10 @@ } /** - * Returns the length of the digest in bytes, or 0 if this - * operation is not supported by the provider and the implementation is not - * cloneable. - * - * @return the digest length in bytes, or 0 if this operation is - * not supported by the provider and the implementation is not cloneable. + * Returns the length of the message digest. The default is zero which means + * that the concrete implementation does not implement this method. + * + * @return length of the message digest. * @since 1.2 */ public final int getDigestLength() @@ -381,11 +325,14 @@ } /** - * Returns a clone if the implementation is cloneable. - * - * @return a clone if the implementation is cloneable. - * @throws CloneNotSupportedException if this is called on an implementation - * that does not support address@hidden Cloneable}. + * Returns a clone of this instance if cloning is supported. If it does not + * then a address@hidden CloneNotSupportedException} is thrown. Cloning depends on + * whether the subclass address@hidden MessageDigestSpi} implements address@hidden Cloneable} + * which contains the actual implementation of the appropriate algorithm. + * + * @return a clone of this instance. + * @throws CloneNotSupportedException + * the implementation does not support cloning. */ public Object clone() throws CloneNotSupportedException { Index: java/security/Policy.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/Policy.java,v retrieving revision 1.13 diff -U3 -r1.13 Policy.java --- java/security/Policy.java 2 Jul 2005 20:32:40 -0000 1.13 +++ java/security/Policy.java 18 Jan 2006 19:34:20 -0000 @@ -43,49 +43,43 @@ import java.util.Map; /** - *

This is an abstract class for representing the system security policy for - * a Java application environment (specifying which permissions are available - * for code from various sources). That is, the security policy is represented - * by a Policy subclass providing an implementation of the abstract - * methods in this Policy class.

- * - *

There is only one Policy object in effect at any given time. - *

- * - *

The source location for the policy information utilized by the - * Policy object is up to the Policy implementation. - * The policy configuration may be stored, for example, as a flat ASCII file, as - * a serialized binary file of the Policy class, or as a database. - *

- * - *

The currently-installed Policy object can be obtained by - * calling the getPolicy() method, and it can be changed by a call - * to the setPolicy() method (by code with permission to reset the - * Policy).

- * - *

The refresh() method causes the policy object to refresh / - * reload its current configuration.

- * - *

This is implementation-dependent. For example, if the policy object stores - * its policy in configuration files, calling refresh() will cause - * it to re-read the configuration policy files. The refreshed policy may not - * have an effect on classes in a particular address@hidden ProtectionDomain}. This is - * dependent on the Policy provider's implementation of the - * implies() method and the address@hidden PermissionCollection} caching - * strategy.

- * + * Policy is an abstract class for managing the system security + * policy for the Java application environment. It specifies which permissions + * are available for code from various sources. The security policy is + * represented through a subclass of Policy. + * + *

Only one Policy is in effect at any time. A + * address@hidden ProtectionDomain} initializes itself with information from this class + * on the set of permssions to grant.

+ * + *

The location for the actual Policy could be anywhere in any + * form because it depends on the Policy implementation. The default system is + * in a flat ASCII file or it could be in a database.

+ * + *

The current installed Policy can be accessed with + * address@hidden #getPolicy()} and changed with address@hidden #setPolicy(Policy)} if the code + * has the correct permissions.

+ * + *

The address@hidden #refresh()} method causes the Policy instance to + * refresh/reload its configuration. The method used to refresh depends on the + * Policy implementation.

+ * + *

When a protection domain initializes its permissions, it uses code like + * the following:

+ * + * + * policy = Policy.getPolicy(); + * PermissionCollection perms = policy.getPermissions(myCodeSource); + * + * + *

The protection domain passes the Policy handler a + * address@hidden CodeSource} instance which contains the codebase URL and a public key. + * The Policy implementation then returns the proper set of + * permissions for that address@hidden CodeSource}.

+ * *

The default Policy implementation can be changed by setting - * the value of the "policy.provider" security property (in the - * Java security properties file) to the fully qualified name of the desired - * Policy implementation class. The Java security properties file - * is located in the file named <JAVA_HOME>/lib/security/java.security - * , where <JAVA_HOME> refers to the directory where the - * SDK was installed.

- * - *

IMPLEMENTATION NOTE: This implementation attempts to read the - * System property named policy.provider to find the concrete - * implementation of the Policy. If/when this fails, it falls back - * to a default implementation, which allows everything. + * the "policy.provider" security provider in the "java.security" file to the + * correct Policy implementation class.

* * @author Mark Benvenuto * @see CodeSource @@ -106,18 +100,14 @@ } /** - * Returns the installed Policy object. This value should not be - * cached, as it may be changed by a call to setPolicy(). This - * method first calls address@hidden SecurityManager#checkPermission(Permission)} with - * a SecurityPermission("getPolicy") permission to ensure it's ok - * to get the Policy object. - * - * @return the installed Policy. - * @throws SecurityException if a security manager exists and its - * checkPermission() method doesn't allow getting the - * Policy object. - * @see SecurityManager#checkPermission(Permission) - * @see #setPolicy(Policy) + * Returns the currently installed Policy handler. The value + * should not be cached as it can be changed any time by + * address@hidden #setPolicy(Policy)}. + * + * @return the current Policy. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public static Policy getPolicy() { @@ -129,17 +119,13 @@ } /** - * Sets the system-wide Policy object. This method first calls - * address@hidden SecurityManager#checkPermission(Permission)} with a - * SecurityPermission("setPolicy") permission to ensure it's ok - * to set the Policy. - * - * @param policy the new system Policy object. - * @throws SecurityException if a security manager exists and its - * checkPermission() method doesn't allow setting the - * Policy. - * @see SecurityManager#checkPermission(Permission) - * @see #getPolicy() + * Sets the Policy handler to a new value. + * + * @param policy + * the new Policy to use. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public static void setPolicy(Policy policy) { @@ -213,28 +199,27 @@ } /** - * Evaluates the global policy and returns a address@hidden PermissionCollection} - * object specifying the set of permissions allowed for code from the - * specified code source. - * - * @param codesource the address@hidden CodeSource} associated with the caller. This - * encapsulates the original location of the code (where the code came from) - * and the public key(s) of its signer. - * @return the set of permissions allowed for code from codesource according - * to the policy. The returned set of permissions must be a new mutable - * instance and it must support heterogeneous address@hidden Permission} types. + * Returns the set of Permissions allowed for a given address@hidden CodeSource}. + * + * @param codesource + * the address@hidden CodeSource} for which, the caller needs to find the + * set of granted permissions. + * @return a set of permissions for address@hidden CodeSource} specified by the + * current Policy. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public abstract PermissionCollection getPermissions(CodeSource codesource); /** - * Evaluates the global policy and returns a address@hidden PermissionCollection} - * object specifying the set of permissions allowed given the characteristics - * of the protection domain. - * - * @param domain the address@hidden ProtectionDomain} associated with the caller. - * @return the set of permissions allowed for the domain according to the - * policy. The returned set of permissions must be a new mutable instance and - * it must support heterogeneous address@hidden Permission} types. + * Returns the set of Permissions allowed for a given address@hidden ProtectionDomain}. + * + * @param domain + * the address@hidden ProtectionDomain} for which, the caller needs to find + * the set of granted permissions. + * @return a set of permissions for address@hidden ProtectionDomain} specified by the + * current Policy.. * @since 1.4 * @see ProtectionDomain * @see SecureClassLoader @@ -270,14 +255,16 @@ } /** - * Evaluates the global policy for the permissions granted to the address@hidden - * ProtectionDomain} and tests whether the permission is granted. - * - * @param domain the address@hidden ProtectionDomain} to test. - * @param permission the address@hidden Permission} object to be tested for - * implication. - * @return true if permission is a proper subset of - * a permission granted to this address@hidden ProtectionDomain}. + * Checks if the designated address@hidden Permission} is granted to a designated + * address@hidden ProtectionDomain}. + * + * @param domain + * the address@hidden ProtectionDomain} to test. + * @param permission + * the address@hidden Permission} to check. + * @return true if permission is implied by a + * permission granted to this address@hidden ProtectionDomain}. Returns + * false otherwise. * @since 1.4 * @see ProtectionDomain */ @@ -302,9 +289,9 @@ } /** - * Refreshes/reloads the policy configuration. The behavior of this method - * depends on the implementation. For example, calling refresh on a file-based - * policy will cause the file to be re-read. + * Causes this Policy instance to refresh / reload its + * configuration. The method used to refresh depends on the concrete + * implementation. */ public abstract void refresh(); } Index: java/security/ProtectionDomain.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/ProtectionDomain.java,v retrieving revision 1.14 diff -U3 -r1.14 ProtectionDomain.java --- java/security/ProtectionDomain.java 16 Nov 2005 18:56:57 -0000 1.14 +++ java/security/ProtectionDomain.java 18 Jan 2006 19:34:20 -0000 @@ -40,17 +40,14 @@ import gnu.classpath.SystemProperties; /** - *

This ProtectionDomain class encapsulates the characteristics - * of a domain, which encloses a set of classes whose instances are granted a - * set of permissions when being executed on behalf of a given set of - * Principals. - * - *

A static set of permissions can be bound to a ProtectionDomain - * when it is constructed; such permissions are granted to the domain regardless - * of the address@hidden Policy} in force. However, to support dynamic security - * policies, a ProtectionDomain can also be constructed such that - * it is dynamically mapped to a set of permissions by the current address@hidden - * Policy} whenever a permission is checked.

+ * This class represents a group of classes, along with their granted + * permissions. The classes are identified by a address@hidden CodeSource}. Thus, any + * class loaded from the specified address@hidden CodeSource} is treated as part of + * this domain. The set of permissions is represented by an instance of + * address@hidden PermissionCollection}. + * + *

Every class in the system will belong to one and only one + * ProtectionDomain.

* * @author Aaron M. Renn (address@hidden) * @version 0.0 @@ -73,15 +70,17 @@ private boolean staticBinding; /** - * Creates a new ProtectionDomain with the given address@hidden - * CodeSource} and address@hidden Permissions}. If the permissions object is not - * null, then setReadOnly() will be called on the - * passed in address@hidden Permissions} object. The only permissions granted to this - * domain are the ones specified; the current address@hidden Policy} will not be - * consulted. - * - * @param codesource the codesource associated with this domain. - * @param permissions the permissions granted to this domain + * Initializes a new instance of ProtectionDomain representing + * the specified address@hidden CodeSource} and set of permissions. No permissions + * can be added later to the address@hidden PermissionCollection} and this contructor + * will call the setReadOnly method on the specified set of + * permissions. + * + * @param codesource + * The address@hidden CodeSource} for this domain. + * @param permissions + * The set of permissions for this domain. + * @see PermissionCollection#setReadOnly() */ public ProtectionDomain(CodeSource codesource, PermissionCollection permissions) { @@ -89,28 +88,25 @@ } /** - *

Creates a new ProtectionDomain qualified by the given CodeSource, - * Permissions, ClassLoader and array of Principals. If the permissions - * object is not null, then setReadOnly() will be called on the - * passed in Permissions object. The permissions granted to this domain are - * dynamic; they include both the static permissions passed to this - * constructor, and any permissions granted to this domain by the current - * Policy at the time a permission is checked.

- * - *

This constructor is typically used by address@hidden ClassLoader}s and address@hidden - * DomainCombiner}s which delegate to Policy to actively - * associate the permissions granted to this domain. This constructor affords - * the Policy provider the opportunity to augment the supplied - * PermissionCollection to reflect policy changes.

- * - * @param codesource the CodeSource associated with this domain. - * @param permissions the permissions granted to this domain. - * @param classloader the ClassLoader associated with this domain. - * @param principals the array of Principals associated with this domain. + * This method initializes a new instance of ProtectionDomain + * given its address@hidden CodeSource}, granted permissions, associated + * address@hidden ClassLoader} and address@hidden Principal}s. + * + *

Similar to the previous constructor, if the designated set of + * permissions is not null, the setReadOnly method + * is called on that set.

+ * + * @param codesource + * The address@hidden CodeSource} for this domain. + * @param permissions + * The permission set for this domain. + * @param classloader + * the ClassLoader associated with this domain. + * @param principals + * the array of address@hidden Principal}s associated with this domain. * @since 1.4 - * @see Policy#refresh() - * @see Policy#getPermissions(ProtectionDomain) - */ + * @see PermissionCollection#setReadOnly() + */ public ProtectionDomain(CodeSource codesource, PermissionCollection permissions, ClassLoader classloader, Principal[] principals) @@ -140,8 +136,8 @@ /** * Returns the address@hidden CodeSource} of this domain. - * - * @return the address@hidden CodeSource} of this domain which may be null. + * + * @return the address@hidden CodeSource} of this domain. * @since 1.2 */ public final CodeSource getCodeSource() @@ -151,9 +147,8 @@ /** * Returns the address@hidden ClassLoader} of this domain. - * - * @return the address@hidden ClassLoader} of this domain which may be - * null. + * + * @return the address@hidden ClassLoader} of this domain. * @since 1.4 */ public final ClassLoader getClassLoader() @@ -162,10 +157,9 @@ } /** - * Returns an array of principals for this domain. - * - * @return returns a non-null array of principals for this domain. Changes to - * this array will have no impact on the ProtectionDomain. + * Returns a clone of the address@hidden Principal}s of this domain. + * + * @return a clone of the address@hidden Principal}s of this domain. * @since 1.4 */ public final Principal[] getPrincipals() @@ -174,12 +168,9 @@ } /** - * Returns the static permissions granted to this domain. - * - * @return the static set of permissions for this domain which may be - * null. - * @see Policy#refresh() - * @see Policy#getPermissions(ProtectionDomain) + * Returns the address@hidden PermissionCollection} of this domain. + * + * @return The address@hidden PermissionCollection} of this domain. */ public final PermissionCollection getPermissions() { @@ -187,26 +178,13 @@ } /** - *

Check and see if this ProtectionDomain implies the - * permissions expressed in the Permission object.

- * - *

The set of permissions evaluated is a function of whether the - * ProtectionDomain was constructed with a static set of - * permissions or it was bound to a dynamically mapped set of permissions.

- * - *

If the ProtectionDomain was constructed to a statically - * bound address@hidden PermissionCollection} then the permission will only be checked - * against the address@hidden PermissionCollection} supplied at construction.

- * - *

However, if the ProtectionDomain was constructed with the - * constructor variant which supports dynamically binding permissions, then - * the permission will be checked against the combination of the - * address@hidden PermissionCollection} supplied at construction and the current - * address@hidden Policy} binding. - * - * @param permission the address@hidden Permission} object to check. - * @return true if permission is implicit to this - * ProtectionDomain. + * Tests whether or not the specified address@hidden Permission} is implied by the + * set of permissions granted to this domain. + * + * @param permission + * the address@hidden Permission} to test. + * @return true if the specified address@hidden Permission} is implied + * for this domain, false otherwise. */ public boolean implies(Permission permission) { @@ -218,9 +196,10 @@ } /** - * Convert a ProtectionDomain to a String. - * - * @return a string representation of the object. + * Returns a string representation of this object. It will include the + * address@hidden CodeSource} and set of permissions associated with this domain. + * + * @return A string representation of this object. */ public String toString() { Index: java/security/Security.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/Security.java,v retrieving revision 1.40 diff -U3 -r1.40 Security.java --- java/security/Security.java 13 Jan 2006 07:56:36 -0000 1.40 +++ java/security/Security.java 18 Jan 2006 19:34:20 -0000 @@ -60,7 +60,7 @@ /** * This class centralizes all security properties and common security methods. - * One of its primary uses is to manage providers. + * One of its primary uses is to manage security providers. * * @author Mark Benvenuto (address@hidden) */ @@ -110,9 +110,9 @@ } /** - * Tries to load the vender specific security providers from the given - * base URL. Returns true if the resource could be read and completely - * parsed successfully, false otherwise. + * Tries to load the vender specific security providers from the given base + * URL. Returns true if the resource could be read and completely parsed + * successfully, false otherwise. */ private static boolean loadProviders(String baseUrl, String vendor) { @@ -166,22 +166,18 @@ } /** - * Gets a specified property for an algorithm. The algorithm name should be a - * standard name. See Appendix A in the Java Cryptography Architecture API - * Specification & Reference for information about standard algorithm - * names. One possible use is by specialized algorithm parsers, which may map - * classes to algorithms which they understand (much like address@hidden Key} parsers - * do). - * - * @param algName the algorithm name. - * @param propName the name of the property to get. - * @return the value of the specified property. - * @deprecated This method used to return the value of a proprietary property - * in the master file of the "SUN" Cryptographic Service Provider in order to - * determine how to parse algorithm-specific parameters. Use the new - * provider-based and algorithm-independent address@hidden AlgorithmParameters} and - * address@hidden KeyFactory} engine classes (introduced in the Java 2 platform) - * instead. + * Returns the value associated to a designated property name for a given + * algorithm. + * + * @param algName + * the algorithm name. + * @param propName + * the name of the property to return. + * @return the value of the specified property or null if none + * found. + * @deprecated Use the provider-based and algorithm-independent + * address@hidden AlgorithmParameters} and address@hidden KeyFactory} engine + * classes instead. */ public static String getAlgorithmProperty(String algName, String propName) { @@ -204,37 +200,21 @@ } /** - *

Adds a new provider, at a specified position. The position is the - * preference order in which providers are searched for requested algorithms. - * Note that it is not guaranteed that this preference will be respected. The - * position is 1-based, that is, 1 is most preferred, followed by - * 2, and so on.

- * - *

If the given provider is installed at the requested position, the - * provider that used to be at that position, and all providers with a - * position greater than position, are shifted up one position (towards the - * end of the list of installed providers).

- * - *

A provider cannot be added if it is already installed.

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with the string "insertProvider."+provider. - * getName() to see if it's ok to add a new provider. If the default - * implementation of checkSecurityAccess() is used (i.e., that - * method is not overriden), then this will result in a call to the security - * manager's checkPermission() method with a - * SecurityPermission("insertProvider."+provider.getName()) - * permission.

- * - * @param provider the provider to be added. - * @param position the preference position that the caller would like for - * this provider. - * @return the actual preference position in which the provider was added, or - * -1 if the provider was not added because it is already - * installed. - * @throws SecurityException if a security manager exists and its - * address@hidden SecurityManager#checkSecurityAccess(String)} method denies access - * to add a new provider. + * Inserts a new designated address@hidden Provider} at a designated (1-based) + * position in the current list of installed address@hidden Provider}s, + * + * @param provider + * the new address@hidden Provider} to add. + * @param position + * the position (starting from 1) of where to install + * provider. + * @return the actual position, in the list of installed Providers. Returns + * -1 if provider was laready in the + * list. The actual position may be different than the desired + * position. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed and it disallows this + * operation. * @see #getProvider(String) * @see #removeProvider(String) * @see SecurityPermission @@ -264,24 +244,17 @@ } /** - *

Adds a provider to the next position available.

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with the string "insertProvider."+provider. - * getName() to see if it's ok to add a new provider. If the default - * implementation of checkSecurityAccess() is used (i.e., that - * method is not overriden), then this will result in a call to the security - * manager's checkPermission() method with a - * SecurityPermission("insertProvider."+provider.getName()) - * permission.

- * - * @param provider the provider to be added. - * @return the preference position in which the provider was added, or - * -1 if the provider was not added because it is already - * installed. - * @throws SecurityException if a security manager exists and its - * address@hidden SecurityManager#checkSecurityAccess(String)} method denies access - * to add a new provider. + * Appends the designated new address@hidden Provider} to the current list of + * installed address@hidden Provider}s. + * + * @param provider + * the new address@hidden Provider} to append. + * @return the position (starting from 1) of provider in the + * current list of address@hidden Provider}s, or -1 if + * provider was already there. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed and it disallows this + * operation. * @see #getProvider(String) * @see #removeProvider(String) * @see SecurityPermission @@ -292,26 +265,14 @@ } /** - *

Removes the provider with the specified name.

- * - *

When the specified provider is removed, all providers located at a - * position greater than where the specified provider was are shifted down - * one position (towards the head of the list of installed providers).

- * - *

This method returns silently if the provider is not installed.

- * - *

First, if there is a security manager, its checkSecurityAccess() - * method is called with the string "removeProvider."+name - * to see if it's ok to remove the provider. If the default implementation of - * checkSecurityAccess() is used (i.e., that method is not - * overriden), then this will result in a call to the security manager's - * checkPermission() method with a SecurityPermission( - * "removeProvider."+name) permission.

- * - * @param name the name of the provider to remove. - * @throws SecurityException if a security manager exists and its - * address@hidden SecurityManager#checkSecurityAccess(String)} method denies access - * to remove the provider. + * Removes an already installed address@hidden Provider}, given its name, from the + * current list of installed address@hidden Provider}s. + * + * @param name + * the name of an already installed address@hidden Provider} to remove. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed and it disallows this + * operation. * @see #getProvider(String) * @see #addProvider(Provider) */ @@ -333,9 +294,9 @@ } /** - * Returns an array containing all the installed providers. The order of the - * providers in the array is their preference order. - * + * Returns the current list of installed address@hidden Provider}s as an array + * ordered according to their installation preference order. + * * @return an array of all the installed providers. */ public static Provider[] getProviders() @@ -346,11 +307,13 @@ } /** - * Returns the provider installed with the specified name, if any. Returns - * null if no provider with the specified name is installed. - * - * @param name the name of the provider to get. - * @return the provider of the specified name. + * Returns an already installed address@hidden Provider} given its name. + * + * @param name + * the name of an already installed address@hidden Provider}. + * @return the address@hidden Provider} known by name. Returns + * null if the current list of address@hidden Provider}s does + * not include one named name. * @see #removeProvider(String) * @see #addProvider(Provider) */ @@ -376,18 +339,16 @@ } /** - *

Gets a security property value.

- * - *

First, if there is a security manager, its checkPermission() - * method is called with a SecurityPermission("getProperty."+key) - * permission to see if it's ok to retrieve the specified security property - * value.

- * - * @param key the key of the property being retrieved. - * @return the value of the security property corresponding to key. - * @throws SecurityException if a security manager exists and its - * address@hidden SecurityManager#checkPermission(Permission)} method denies access - * to retrieve the specified security property value. + * Returns the value associated with a Security propery. + * + * @param key + * the key of the property to fetch. + * @return the value of the Security property associated with + * key. Returns null if no such property + * was found. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed and it disallows this + * operation. * @see #setProperty(String, String) * @see SecurityPermission */ @@ -404,18 +365,15 @@ } /** - *

Sets a security property value.

- * - *

First, if there is a security manager, its checkPermission() - * method is called with a SecurityPermission("setProperty."+key) - * permission to see if it's ok to set the specified security property value. - *

- * - * @param key the name of the property to be set. - * @param datum the value of the property to be set. - * @throws SecurityException if a security manager exists and its - * address@hidden SecurityManager#checkPermission(Permission)} method denies access - * to set the specified security property value. + * Sets or changes a designated Security property to a designated value. + * + * @param key + * the name of the property to set. + * @param datum + * the new value of the property. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed and it disallows this + * operation. * @see #getProperty(String) * @see SecurityPermission */ @@ -432,19 +390,16 @@ } /** - * Returns a Set of Strings containing the names of all available algorithms - * or types for the specified Java cryptographic service (e.g., Signature, - * MessageDigest, Cipher, Mac, KeyStore). Returns an empty Set if there is no - * provider that supports the specified service. For a complete list of Java - * cryptographic services, please see the Java Cryptography Architecture API - * Specification & Reference. Note: the returned set is immutable. - * - * @param serviceName the name of the Java cryptographic service (e.g., - * Signature, MessageDigest, Cipher, Mac, KeyStore). Note: this parameter is - * case-insensitive. - * @return a Set of Strings containing the names of all available algorithms - * or types for the specified Java cryptographic service or an empty set if - * no provider supports the specified service. + * For a given service (e.g. Signature, MessageDigest, etc...) this + * method returns the address@hidden Set} of all available algorithm names (instances + * of address@hidden String}, from all currently installed address@hidden Provider}s. + * + * @param serviceName + * the case-insensitive name of a service (e.g. Signature, + * MessageDigest, etc). + * @return a address@hidden Set} of address@hidden String}s containing the names of all + * algorithm names provided by all of the currently installed + * address@hidden Provider}s. * @since 1.4 */ public static Set getAlgorithms(String serviceName) @@ -477,53 +432,48 @@ } /** - *

Returns an array containing all installed providers that satisfy the - * specified selection criterion, or null if no such providers - * have been installed. The returned providers are ordered according to their - * preference order.

- * - *

A cryptographic service is always associated with a particular - * algorithm or type. For example, a digital signature service is always - * associated with a particular algorithm (e.g., DSA), and a - * CertificateFactory service is always associated with a particular - * certificate type (e.g., X.509).

- * - *

The selection criterion must be specified in one of the following two - * formats:

- * + * Returns an array of currently installed address@hidden Provider}s, ordered + * according to their installation preference order, which satisfy a given + * selection criterion. + * + *

This implementation recognizes a selection criterion written in + * one of two following forms:

+ * * - * - *

See Appendix A in the Java Cryptogaphy Architecture API Specification - * & Reference for information about standard cryptographic service names, - * standard algorithm names and standard attribute names.

- * - * @param filter the criterion for selecting providers. The filter is case- - * insensitive. - * @return all the installed providers that satisfy the selection criterion, - * or null if no such providers have been installed. - * @throws InvalidParameterException if the filter is not in the required - * format. + * + * @param filter + * the selection criterion for selecting among the installed + * address@hidden Provider}s. + * @return all the installed address@hidden Provider}s which satisfy the selection + * criterion. Returns null if no installed + * address@hidden Provider}s were found which satisfy the selection + * criterion. Returns ALL installed address@hidden Provider}s if + * filter is null or is an empty string. + * @throws InvalidParameterException + * if an exception occurs while parsing the filter. * @see #getProviders(Map) */ public static Provider[] getProviders(String filter) @@ -544,48 +494,47 @@ return getProviders(map); } - /** - *

Returns an array containing all installed providers that satisfy the - * specified selection criteria, or null if no such providers - * have been installed. The returned providers are ordered according to their - * preference order.

- * - *

The selection criteria are represented by a map. Each map entry - * represents a selection criterion. A provider is selected iff it satisfies - * all selection criteria. The key for any entry in such a map must be in one - * of the following two formats:

- * - * - * - *

See Appendix A in the Java Cryptogaphy Architecture API Specification - * & Reference for information about standard cryptographic service names, - * standard algorithm names and standard attribute names.

- * - * @param filter the criteria for selecting providers. The filter is case- - * insensitive. - * @return all the installed providers that satisfy the selection criteria, - * or null if no such providers have been installed. - * @throws InvalidParameterException if the filter is not in the required - * format. - * @see #getProviders(String) - */ + /** + * Returns an array of currently installed address@hidden Provider}s which satisfy a + * set of selection criteria. + * + *

The selection criteria are defined in a address@hidden Map} where each + * element specifies a selection querry. The Keys in this + * address@hidden Map} must be in one of the two following forms:

+ * + * + * + * @param filter + * a address@hidden Map} of selection querries. + * @return all currently installed address@hidden Provider}s which satisfy ALL the + * selection criteria defined in filter. + * Returns ALL installed address@hidden Provider}s if filter + * is null or empty. + * @throws InvalidParameterException + * if an exception is encountered while parsing the syntax of the + * address@hidden Map}'s keys. + * @see #getProviders(String) + */ public static Provider[] getProviders(Map filter) { if (providers == null || providers.isEmpty()) Index: java/security/Signature.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/Signature.java,v retrieving revision 1.19 diff -U3 -r1.19 Signature.java --- java/security/Signature.java 2 Jul 2005 20:32:40 -0000 1.19 +++ java/security/Signature.java 18 Jan 2006 19:34:20 -0000 @@ -45,66 +45,36 @@ import java.security.spec.AlgorithmParameterSpec; /** - *

This Signature class is used to provide applications the - * functionality of a digital signature algorithm. Digital signatures are used - * for authentication and integrity assurance of digital data.

- * - *

The signature algorithm can be, among others, the NIST standard DSS, - * using DSA and SHA-1. The DSA algorithm using the - * SHA-1 message digest algorithm can be specified as SHA1withDSA - * . In the case of RSA, there are multiple choices for the - * message digest algorithm, so the signing algorithm could be specified as, for - * example, MD2withRSA, MD5withRSA, or - * SHA1withRSA. The algorithm name must be specified, as there is - * no default.

- * - *

Like other algorithm-based classes in Java Security, Signature - * provides implementation-independent algorithms, whereby a caller (application - * code) requests a particular signature algorithm and is handed back a properly - * initialized Signature object. It is also possible, if desired, - * to request a particular algorithm from a particular provider. See the - * getInstance() methods.

- * - *

Thus, there are two ways to request a Signature algorithm - * object: by specifying either just an algorithm name, or both an algorithm - * name and a package provider.

- * - *

If just an algorithm name is specified, the system will determine if there - * is an implementation of the algorithm requested available in the environment, - * and if there is more than one, if there is a preferred one.

- * - *

If both an algorithm name and a package provider are specified, the system - * will determine if there is an implementation of the algorithm in the package - * requested, and throw an exception if there is not.

- * - *

A Signature object can be used to generate and verify digital - * signatures.

- * - *

There are three phases to the use of a Signature object for - * either signing data or verifying a signature:

- * + * Signature is used to provide an interface to digital signature + * algorithms. Digital signatures provide authentication and data integrity of + * digital data. + * + *

The GNU provider provides the NIST standard DSA which uses DSA and SHA-1. + * It can be specified by SHA/DSA, SHA-1/DSA or its OID. If the RSA signature + * algorithm is provided then it could be MD2/RSA. MD5/RSA, or SHA-1/RSA. The + * algorithm must be specified because there is no default.

+ * + *

Signature provides implementation-independent algorithms which are + * requested by the user through the getInstance() methods. It can + * be requested by specifying just the algorithm name or by specifying both the + * algorithm name and provider name.

+ * + *

The three phases of using Signature are:

+ * *
    - *
  1. Initialization, with either + *
  2. Initializing: *
      - *
    • a public key, which initializes the signature for verification - * (see initVerify()), or
      • - *
    • a private key (and optionally a Secure Random Number Generator), - * which initializes the signature for signing (see - * address@hidden #initSign(PrivateKey)} and address@hidden #initSign(PrivateKey, SecureRandom)} - * ).
      • - *
    3. - *
  3. Updating
    - * Depending on the type of initialization, this will update the bytes to - * be signed or verified. See the update methods.
    4. - *
  4. Signing or Verifying a signature on all updated bytes. See the - * sign() methods and the verify() method.
    5. - *
- * - *

Note that this class is abstract and extends from address@hidden SignatureSpi} for - * historical reasons. Application developers should only take notice of the - * methods defined in this Signature class; all the methods in the - * superclass are intended for cryptographic service providers who wish to - * supply their own implementations of digital signature algorithms. + *

  • It must be initialized with a private key for signing.
    • + *
  • It must be initialized with a public key for verifying.
    • + * + * + *
  • Updating: + *

    Update the bytes for signing or verifying with calls to update.

    + *
    • + * + *
  • Signing or Verify the signature on the currently stored bytes by + * calling sign or verify.
    • + * * * @author Mark Benvenuto (address@hidden) */ @@ -114,38 +84,38 @@ private static final String SIGNATURE = "Signature"; /** - * Possible state value, signifying that this signature object - * has not yet been initialized. + * Possible state value which signifies that this instance has not yet been + * initialized. */ protected static final int UNINITIALIZED = 0; - // Constructor. - // ------------------------------------------------------------------------ - /** - * Possible state value, signifying that this signature object - * has been initialized for signing. + * Possible state value which signifies that this instance has been + * initialized for signing purposes. */ protected static final int SIGN = 2; /** - * Possible state value, signifying that this signature object - * has been initialized for verification. + * Possible state value which signifies that this instance has been + * initialized for verification purposes. */ protected static final int VERIFY = 3; - /** Current state of this signature object. */ + /** Current sate of this instance. */ protected int state = UNINITIALIZED; private String algorithm; Provider provider; + // Constructor. + // ------------------------------------------------------------------------ + /** - * Creates a Signature object for the specified algorithm. - * - * @param algorithm the standard string name of the algorithm. See Appendix A - * in the Java Cryptography Architecture API Specification & Reference for - * information about standard algorithm names. + * Constructs a new Signature instance for a designated digital + * signature algorithm. + * + * @param algorithm + * the algorithm to use. */ protected Signature(String algorithm) { @@ -154,19 +124,14 @@ } /** - * Generates a Signature object that implements the specified - * digest algorithm. If the default provider package provides an - * implementation of the requested digest algorithm, an instance of - * Signature containing that implementation is returned. If the - * algorithm is not available in the default package, other packages are - * searched. - * - * @param algorithm the standard name of the algorithm requested. See Appendix - * A in the Java Cryptography Architecture API Specification & Reference - * for information about standard algorithm names. - * @return the new Signature object. - * @throws NoSuchAlgorithmException if the algorithm is not available in the - * environment. + * Returns an instance of Signature representing the specified + * signature. + * + * @param algorithm + * the algorithm to use. + * @return a new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by any provider. */ public static Signature getInstance(String algorithm) throws NoSuchAlgorithmException @@ -188,22 +153,20 @@ } /** - * Generates a Signature object implementing the specified - * algorithm, as supplied from the specified provider, if such an algorithm - * is available from the provider. - * - * @param algorithm the name of the algorithm requested. 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 the new Signature object. - * @throws NoSuchAlgorithmException if the algorithm is not available in the - * package supplied by the requested provider. - * @throws NoSuchProviderException if the provider is not available in the - * environment. - * @throws IllegalArgumentException if the provider name is null - * or empty. - * @see Provider + * Returns an instance of Signature representing the specified + * signature from the named provider. + * + * @param algorithm + * the 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 NoSuchProviderException + * if the named provider was not found. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the named provider. */ public static Signature getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException @@ -219,22 +182,16 @@ } /** - * Generates a Signature object implementing the specified - * algorithm, as supplied from the specified provider, if such an algorithm - * is available from the provider. Note: the provider doesn't have to be - * registered. - * - * @param algorithm the name of the algorithm requested. See Appendix A in - * the Java Cryptography Architecture API Specification & Reference for - * information about standard algorithm names. - * @param provider the provider. - * @return the new Signature object. - * @throws NoSuchAlgorithmException if the algorithm is not - * available in the package supplied by the requested provider. - * @throws IllegalArgumentException if the provider is - * null. - * @since 1.4 - * @see Provider + * Returns an instance of Signature representing the specified + * signature from the specified address@hidden Provider}. + * + * @param algorithm + * the algorithm to use. + * @param provider + * the address@hidden Provider} to use. + * @return a new instance repesenting the desired algorithm. + * @throws NoSuchAlgorithmException + * if the algorithm is not implemented by the address@hidden Provider}. */ public static Signature getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException @@ -271,9 +228,9 @@ } /** - * Returns the provider of this signature object. - * - * @return the provider of this signature object. + * Returns the address@hidden Provider} of this instance. + * + * @return the address@hidden Provider} of this instance. */ public final Provider getProvider() { @@ -281,12 +238,12 @@ } /** - * Initializes this object for verification. If this method is called again - * with a different argument, it negates the effect of this call. - * - * @param publicKey the public key of the identity whose signature is going - * to be verified. - * @throws InvalidKeyException if the key is invalid. + * Initializes this instance with the public key for verification purposes. + * + * @param publicKey + * the public key to verify with. + * @throws InvalidKeyException + * if the key is invalid. */ public final void initVerify(PublicKey publicKey) throws InvalidKeyException { @@ -295,20 +252,16 @@ } /** - *

    Initializes this object for verification, using the public key from the - * given certificate.

    - * - *

    If the certificate is of type X.509 and has a key usage - * extension field marked as critical, and the value of the key - * usage extension field implies that the public key in the certificate - * and its corresponding private key are not supposed to be used for digital - * signatures, an address@hidden InvalidKeyException} is thrown.

    - * - * @param certificate the certificate of the identity whose signature is - * going to be verified. - * @throws InvalidKeyException if the public key in the certificate is not - * encoded properly or does not include required parameter information or - * cannot be used for digital signature purposes. + * Verify a signature with a designated address@hidden Certificate}. This is a FIPS + * 140-1 compatible method since it verifies a signature with a certificate. + * + *

    If the address@hidden Certificate} is an X.509 one, has a KeyUsage + * parameter and that parameter indicates this key is not to be used for + * signing then an exception is thrown.

    + * + * @param certificate + * a address@hidden Certificate} containing a public key to verify with. + * @throws InvalidKeyException if the key is invalid. */ public final void initVerify(Certificate certificate) throws InvalidKeyException @@ -326,12 +279,12 @@ } /** - * Initialize this object for signing. If this method is called again with a - * different argument, it negates the effect of this call. - * - * @param privateKey the private key of the identity whose signature is going - * to be generated. - * @throws InvalidKeyException if the key is invalid. + * Initializes this class with the private key for signing purposes. + * + * @param privateKey + * the private key to sign with. + * @throws InvalidKeyException + * if the key is invalid. */ public final void initSign(PrivateKey privateKey) throws InvalidKeyException { @@ -340,13 +293,15 @@ } /** - * Initialize this object for signing. If this method is called again with a - * different argument, it negates the effect of this call. - * - * @param privateKey the private key of the identity whose signature is going - * to be generated. - * @param random the source of randomness for this signature. - * @throws InvalidKeyException if the key is invalid. + * Initializes this class with the private key and source of randomness for + * signing purposes. + * + * @param privateKey + * the private key to sign with. + * @param random + * the address@hidden SecureRandom} to use. + * @throws InvalidKeyException + * if the key is invalid. */ public final void initSign(PrivateKey privateKey, SecureRandom random) throws InvalidKeyException @@ -356,18 +311,12 @@ } /** - *

    Returns the signature bytes of all the data updated. The format of the - * signature depends on the underlying signature scheme.

    - * - *

    A call to this method resets this signature object to the state it was - * in when previously initialized for signing via a call to - * initSign(PrivateKey). That is, the object is reset and - * available to generate another signature from the same signer, if desired, - * via new calls to update() and sign().

    - * - * @return the signature bytes of the signing operation's result. - * @throws SignatureException if this signature object is not initialized - * properly. + * Returns the signature bytes of all the data fed to this instance. The + * format of the output depends on the underlying signature algorithm. + * + * @return the signature bytes. + * @throws SignatureException + * if the engine is not properly initialized. */ public final byte[] sign() throws SignatureException { @@ -378,21 +327,27 @@ } /** - *

    Finishes the signature operation and stores the resulting signature - * bytes in the provided buffer outbuf, starting at offset - * . The format of the signature depends on the underlying signature - * scheme.

    - * - *

    This signature object is reset to its initial state (the state it was - * in after a call to one of the initSign() methods) and can be - * reused to generate further signatures with the same private key.

    - * - * @param outbuf buffer for the signature result. - * @param offset offset into outbuf where the signature is stored. - * @param len number of bytes within outbuf allotted for the signature. - * @return the number of bytes placed into outbuf. - * @throws SignatureException if an error occurs or len is less than the - * actual signature length. + * Generates signature bytes of all the data fed to this instance and stores + * it in the designated array. The format of the result depends on the + * underlying signature algorithm. + * + *

    After calling this method, the instance is reset to its initial state + * and can then be used to generate additional signatures.

    + * + *

    IMPLEMENTATION NOTE: Neither this method nor the GNU provider + * will return partial digests. If len is less than the + * signature length, this method will throw a address@hidden SignatureException}. If + * it is greater than or equal then it is ignored.

    + * + * @param outbuf + * array of bytes of where to store the resulting signature bytes. + * @param offset + * the offset to start at in the array. + * @param len + * the number of the bytes to use in the array. + * @return the real number of bytes used. + * @throws SignatureException + * if the engine is not properly initialized. * @since 1.2 */ public final int sign(byte[] outbuf, int offset, int len) @@ -405,20 +360,14 @@ } /** - *

    Verifies the passed-in signature.

    - * - *

    A call to this method resets this signature object to the state it was - * in when previously initialized for verification via a call to - * initVerify(PublicKey). That is, the object is reset and - * available to verify another signature from the identity whose public key - * was specified in the call to initVerify().

    - * - * @param signature the signature bytes to be verified. - * @return true if the signature was verified, false - * if not. - * @throws SignatureException if this signature object is not initialized - * properly, or the passed-in signature is improperly encoded or of the wrong - * type, etc. + * Verifies a designated signature. + * + * @param signature + * the signature bytes to verify. + * @return true if verified, false otherwise. + * @throws SignatureException + * if the engine is not properly initialized or the signature does + * not check. */ public final boolean verify(byte[]signature) throws SignatureException { @@ -429,28 +378,24 @@ } /** - *

    Verifies the passed-in signature in the specified array of - * bytes, starting at the specified offset.

    - * - *

    A call to this method resets this signature object to the state it was - * in when previously initialized for verification via a call to - * initVerify(PublicKey). That is, the object is reset and - * available to verify another signature from the identity whose public key - * was specified in the call to initVerify().

    - * - * @param signature the signature bytes to be verified. - * @param offset the offset to start from in the array of bytes. - * @param length the number of bytes to use, starting at offset. - * @return true if the signature was verified, false - * if not. - * @throws SignatureException if this signature object is not initialized - * properly, or the passed-in signature is improperly encoded or - * of the wrong type, etc. - * @throws IllegalArgumentException if the signature byte array - * is null, or the offset or length is - * less than 0, or the sum of the offset and - * length is greater than the length of the signature - * byte array. + * Verifies a designated signature. + * + * @param signature + * the signature bytes to verify. + * @param offset + * the offset to start at in the array. + * @param length + * the number of the bytes to use from the array. + * @return true if verified, false otherwise. + * @throws IllegalArgumentException + * if the signature byte array is null, + * or the offset or length is less + * than 0, or the sum of the offset + * and length is greater than the length of the + * signature byte array. + * @throws SignatureException + * if the engine is not properly initialized or the signature does + * not check. */ public final boolean verify(byte[] signature, int offset, int length) throws SignatureException @@ -471,11 +416,12 @@ } /** - * Updates the data to be signed or verified by a byte. - * - * @param b the byte to use for the update. - * @throws SignatureException if this signature object is not initialized - * properly. + * Updates the data to be signed or verified with the specified byte. + * + * @param b + * the byte to update with. + * @throws SignatureException + * if the engine is not properly initialized. */ public final void update(byte b) throws SignatureException { @@ -486,12 +432,12 @@ } /** - * Updates the data to be signed or verified, using the specified array of - * bytes. - * - * @param data the byte array to use for the update. - * @throws SignatureException if this signature object is not initialized - * properly. + * Updates the data to be signed or verified with the specified bytes. + * + * @param data + * the array of bytes to use. + * @throws SignatureException + * if the engine is not properly initialized. */ public final void update(byte[]data) throws SignatureException { @@ -502,14 +448,16 @@ } /** - * Updates the data to be signed or verified, using the specified array of - * bytes, starting at the specified offset. - * - * @param data the array of bytes. - * @param off the offset to start from in the array of bytes. - * @param len the number of bytes to use, starting at offset. - * @throws SignatureException if this signature object is not initialized - * properly. + * Updates the data to be signed or verified with the specified bytes. + * + * @param data + * an array of bytes to use. + * @param off + * the offset to start at in the array. + * @param len + * the number of bytes to use from the array. + * @throws SignatureException + * if the engine is not properly initialized. */ public final void update(byte[]data, int off, int len) throws SignatureException @@ -521,9 +469,10 @@ } /** - * Returns the name of the algorithm for this signature object. - * - * @return the name of the algorithm for this signature object. + * Returns the name of the algorithm currently used. The names of algorithms + * are usually SHA/DSA or SHA/RSA. + * + * @return name of algorithm. */ public final String getAlgorithm() { @@ -531,11 +480,9 @@ } /** - * Returns a string representation of this signature object, providing - * information that includes the state of the object and the name of the - * algorithm used. - * - * @return a string representation of this signature object. + * Returns a rstring representation of this instance. + * + * @return a rstring representation of this instance. */ public String toString() { @@ -543,22 +490,16 @@ } /** - * Sets the specified algorithm parameter to the specified value. This method - * supplies a general-purpose mechanism through which it is possible to set - * the various parameters of this object. A parameter may be any settable - * parameter for the algorithm, such as a parameter size, or a source of - * random bits for signature generation (if appropriate), or an indication of - * whether or not to perform a specific but optional computation. A uniform - * algorithm-specific naming scheme for each parameter is desirable but left - * unspecified at this time. - * - * @param param the string identifier of the parameter. - * @param value the parameter value. - * @throws InvalidParameterException if param is an invalid parameter for this - * signature algorithm engine, the parameter is already set and cannot be set - * again, a security exception occurs, and so on. - * @see #getParameter(String) - * @deprecated Use setParameter(AlgorithmParameterSpec). + * Sets the specified algorithm parameter to the specified value. + * + * @param param + * the parameter name. + * @param value + * the parameter value. + * @throws InvalidParameterException + * if the parameter is invalid, the parameter is already set and + * can not be changed, a security exception occured, etc. + * @deprecated use the other setParameter */ public final void setParameter(String param, Object value) throws InvalidParameterException @@ -567,12 +508,16 @@ } /** - * Initializes this signature engine with the specified parameter set. - * - * @param params the parameters. - * @throws InvalidAlgorithmParameterException if the given parameters are - * inappropriate for this signature engine. - * @see #getParameters() + * Sets the signature engine with the specified address@hidden AlgorithmParameterSpec}. + * + *

    By default, and unless overriden by the concrete SPI, this method always + * throws an address@hidden UnsupportedOperationException}.

    + * + * @param params + * the parameters to use for intializing this instance. + * @throws InvalidParameterException + * if the parameter is invalid, the parameter is already set and + * cannot be changed, a security exception occured, etc. */ public final void setParameter(AlgorithmParameterSpec params) throws InvalidAlgorithmParameterException @@ -581,17 +526,11 @@ } /** - *

    Returns the parameters used with this signature object.

    - * - *

    The returned parameters may be the same that were used to initialize - * this signature, or may contain a combination of default and randomly - * generated parameter values used by the underlying signature implementation - * if this signature requires algorithm parameters but was not initialized - * with any. - * - * @return the parameters used with this signature, or null if - * this signature does not use any parameters. - * @see #setParameter(AlgorithmParameterSpec) + * Return the parameters of the algorithm used in this instance as an + * address@hidden AlgorithmParameters}. + * + * @return the parameters used with this instance, or null if + * this instance does not use any parameters. */ public final AlgorithmParameters getParameters() { @@ -599,22 +538,14 @@ } /** - * Gets the value of the specified algorithm parameter. This method supplies - * a general-purpose mechanism through which it is possible to get the various - * parameters of this object. A parameter may be any settable parameter for - * the algorithm, such as a parameter size, or a source of random bits for - * signature generation (if appropriate), or an indication of whether or not - * to perform a specific but optional computation. A uniform - * algorithm-specific naming scheme for each parameter is desirable but left - * unspecified at this time. - * - * @param param the string name of the parameter. - * @return the object that represents the parameter value, or null if there - * is none. - * @throws InvalidParameterException if param is an invalid parameter for this - * engine, or another exception occurs while trying to get this parameter. - * @see #setParameter(String, Object) - * @deprecated + * Returns the value for the specified algorithm parameter. + * + * @param param + * the parameter name. + * @return the parameter value. + * @throws InvalidParameterException + * if the parameter is invalid. + * @deprecated use the other getParameter */ public final Object getParameter(String param) throws InvalidParameterException @@ -623,11 +554,11 @@ } /** - * Returns a clone if the implementation is cloneable. - * - * @return a clone if the implementation is cloneable. - * @throws CloneNotSupportedException if this is called on an implementation - * that does not support address@hidden Cloneable}. + * Returns a clone of this instance. + * + * @return a clone of this instace. + * @throws CloneNotSupportedException + * if the implementation does not support cloning. */ public Object clone() throws CloneNotSupportedException { Index: java/security/SignatureSpi.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/SignatureSpi.java,v retrieving revision 1.11 diff -U3 -r1.11 SignatureSpi.java --- java/security/SignatureSpi.java 2 Jul 2005 20:32:40 -0000 1.11 +++ java/security/SignatureSpi.java 18 Jan 2006 19:34:20 -0000 @@ -40,14 +40,10 @@ import java.security.spec.AlgorithmParameterSpec; /** - *

    This class defines the Service Provider Interface (SPI) for the - * address@hidden Signature} class, which is used to provide the functionality of a + * SignatureSpi defines the Service Provider Interface (SPI) for + * the address@hidden Signature} class. The signature class provides an interface to a * digital signature algorithm. Digital signatures are used for authentication - * and integrity assurance of digital data.

    - * - *

    All the abstract methods in this class must be implemented by each - * cryptographic service provider who wishes to supply the implementation of a - * particular signature algorithm. + * and integrity of data. * * @author Mark Benvenuto (address@hidden) * @since 1.2 @@ -55,50 +51,51 @@ */ public abstract class SignatureSpi { - /** Application-specified source of randomness. */ + /** Source of randomness. */ protected SecureRandom appRandom; + /** + * Creates a new instance of SignatureSpi. + */ public SignatureSpi() { appRandom = null; } /** - * Initializes this signature object with the specified public key for - * verification operations. - * - * @param publicKey the public key of the identity whose signature is going - * to be verified. - * @throws InvalidKeyException if the key is improperly encoded, parameters - * are missing, and so on. + * Initializes this instance with the public key for verification purposes. + * + * @param publicKey + * the public key to verify with. + * @throws InvalidKeyException + * if the key is invalid. */ protected abstract void engineInitVerify(PublicKey publicKey) throws InvalidKeyException; /** - * Initializes this signature object with the specified private key for - * signing operations. - * - * @param privateKey the private key of the identity whose signature will be - * generated. - * @throws InvalidKeyException if the key is improperly encoded, parameters - * are missing, and so on. + * Initializes this instance with the private key for signing purposes. + * + * @param privateKey + * the private key to sign with. + * @throws InvalidKeyException + * if the key is invalid. */ protected abstract void engineInitSign(PrivateKey privateKey) throws InvalidKeyException; /** - *

    Initializes this signature object with the specified private key and - * source of randomness for signing operations.

    - * - *

    This concrete method has been added to this previously-defined abstract - * class. (For backwards compatibility, it cannot be abstract.)

    - * - * @param privateKey the private key of the identity whose signature will be - * generated. - * @param random the source of randomness. - * @throws InvalidKeyException if the key is improperly encoded, parameters - * are missing, and so on. + * Initializes this instance with the private key and source of randomness for + * signing purposes. + * + *

    This method cannot be abstract for backward compatibility reasons.

    + * + * @param privateKey + * the private key to sign with. + * @param random + * the address@hidden SecureRandom} to use. + * @throws InvalidKeyException + * if the key is invalid. * @since 1.2 */ protected void engineInitSign(PrivateKey privateKey, SecureRandom random) @@ -109,57 +106,63 @@ } /** - * Updates the data to be signed or verified using the specified byte. - * - * @param b the byte to use for the update. - * @throws SignatureException if the engine is not initialized properly. + * Updates the data to be signed or verified with the specified byte. + * + * @param b + * byte to update with. + * @throws SignatureException + * if the engine is not properly initialized. */ protected abstract void engineUpdate(byte b) throws SignatureException; /** - * Updates the data to be signed or verified, using the specified array of - * bytes, starting at the specified offset. - * - * @param b the array of bytes. - * @param off the offset to start from in the array of bytes. - * @param len the number of bytes to use, starting at offset. - * @throws SignatureException if the engine is not initialized properly. + * Updates the data to be signed or verified with the specified bytes. + * + * @param b + * the array of bytes to use. + * @param off + * the offset to start at in the array. + * @param len + * the number of the bytes to use from the array. + * @throws SignatureException + * if the engine is not properly initialized. */ protected abstract void engineUpdate(byte[] b, int off, int len) throws SignatureException; /** - * Returns the signature bytes of all the data updated so far. The format of - * the signature depends on the underlying signature scheme. - * - * @return the signature bytes of the signing operation's result. - * @throws SignatureException if the engine is not initialized properly. + * Returns the signature bytes of all the data fed to this instance. The + * format of the output depends on the underlying signature algorithm. + * + * @return the signature bytes. + * @throws SignatureException + * if the engine is not properly initialized. */ protected abstract byte[] engineSign() throws SignatureException; /** - *

    Finishes this signature operation and stores the resulting signature - * bytes in the provided buffer outbuf, starting at offset - * . The format of the signature depends on the underlying signature - * scheme.

    - * - *

    The signature implementation is reset to its initial state (the state it - * was in after a call to one of the engineInitSign() methods) - * and can be reused to generate further signatures with the same private key. - * This method should be abstract, but we leave it concrete for binary - * compatibility. Knowledgeable providers should override this method.

    - * - * @param outbuf buffer for the signature result. - * @param offset offset into outbuf where the signature is stored. - * @param len number of bytes within outbuf allotted for the signature. Both - * this default implementation and the GNU provider do not return - * partial digests. If the value of this parameter is less than the actual - * signature length, this method will throw a address@hidden SignatureException}. This - * parameter is ignored if its value is greater than or equal to the actual - * signature length. - * @return the number of bytes placed into outbuf. - * @throws SignatureException if an error occurs or len is less than the - * actual signature length. + * Generates signature bytes of all the data fed to this instance and stores + * the result in the designated array. The format of the output depends on + * the underlying signature algorithm. + * + *

    This method cannot be abstract for backward compatibility reasons. + * After calling this method, the signature is reset to its initial state and + * can be used to generate additional signatures.

    + * + *

    IMPLEMENTATION NOTE:: Neither this method nor the GNU provider + * will return partial digests. If len is less than the + * signature length, this method will throw a address@hidden SignatureException}. If + * it is greater than or equal then it is ignored.

    + * + * @param outbuf + * the array of bytes to store the result in. + * @param offset + * the offset to start at in the array. + * @param len + * the number of the bytes to use in the array. + * @return the real number of bytes used. + * @throws SignatureException + * if the engine is not properly initialized. * @since 1.2 */ protected int engineSign(byte[] outbuf, int offset, int len) @@ -174,31 +177,32 @@ } /** - * Verifies the passed-in signature. - * - * @param sigBytes the signature bytes to be verified. - * @return true if the signature was verified, false - * if not. - * @throws SignatureException if the engine is not initialized properly, or - * the passed-in signature is improperly encoded or of the wrong type, etc. + * Verifies a designated signature. + * + * @param sigBytes + * the signature bytes to verify. + * @return true if verified, false otherwise. + * @throws SignatureException + * if the engine is not properly initialized or if it is the wrong + * signature. */ protected abstract boolean engineVerify(byte[] sigBytes) throws SignatureException; /** - *

    Verifies the passed-in signature in the specified array of - * bytes, starting at the specified offset.

    - * - *

    Note: Subclasses should overwrite the default implementation.

    - * - * @param sigBytes the signature bytes to be verified. - * @param offset the offset to start from in the array of bytes. - * @param length the number of bytes to use, starting at offset. - * @return true if the signature was verified, false - * if not. - * @throws SignatureException if the engine is not initialized properly, or - * the passed-in signature is improperly encoded or of the wrong - * type, etc. + * Convenience method which calls the method with the same name and one + * argument after copying the designated bytes into a temporary byte array. + * Subclasses may override this method for performance reasons. + * + * @param sigBytes + * the array of bytes to use. + * @param offset + * the offset to start from in the array of bytes. + * @param length + * the number of bytes to use, starting at offset. + * @return true if verified, false otherwise. + * @throws SignatureException + * if the engine is not properly initialized. */ protected boolean engineVerify(byte[] sigBytes, int offset, int length) throws SignatureException @@ -209,35 +213,32 @@ } /** - * Sets the specified algorithm parameter to the specified value. This method - * supplies a general-purpose mechanism through which it is possible to set - * the various parameters of this object. A parameter may be any settable - * parameter for the algorithm, such as a parameter size, or a source of - * random bits for signature generation (if appropriate), or an indication of - * whether or not to perform a specific but optional computation. A uniform - * algorithm-specific naming scheme for each parameter is desirable but left - * unspecified at this time. - * - * @param param the string identifier of the parameter. - * @param value the parameter value. - * @throws InvalidParameterException if param is an invalid - * parameter for this signature algorithm engine, the parameter is already set - * and cannot be set again, a security exception occurs, and so on. - * @deprecated Replaced by engineSetParameter(AlgorithmParameterSpec). + * Sets the specified algorithm parameter to the specified value. + * + * @param param + * the parameter name. + * @param value + * the parameter value. + * @throws InvalidParameterException + * if the parameter invalid, the parameter is already set and + * cannot be changed, a security exception occured, etc. + * @deprecated use the other setParameter. */ protected abstract void engineSetParameter(String param, Object value) throws InvalidParameterException; /** - * This method is overridden by providers to initialize this signature engine - * with the specified parameter set. - * - * @param params the parameters. - * @throws UnsupportedOperationException if this method is not overridden by - * a provider. - * @throws InvalidAlgorithmParameterException if this method is overridden by - * a provider and the the given parameters are inappropriate for this - * signature engine. + * Sets the signature engine with the specified address@hidden AlgorithmParameterSpec}. + * + *

    This method cannot be abstract for backward compatibility reasons. By + * default it always throws address@hidden UnsupportedOperationException} unless + * overridden.

    + * + * @param params + * the parameters. + * @throws InvalidParameterException + * if the parameter is invalid, the parameter is already set and + * cannot be changed, a security exception occured, etc. */ protected void engineSetParameter(AlgorithmParameterSpec params) throws InvalidAlgorithmParameterException @@ -246,20 +247,16 @@ } /** - *

    This method is overridden by providers to return the parameters used - * with this signature engine, or null if this signature engine - * does not use any parameters.

    - * - *

    The returned parameters may be the same that were used to initialize - * this signature engine, or may contain a combination of default and randomly - * generated parameter values used by the underlying signature implementation - * if this signature engine requires algorithm parameters but was not - * initialized with any.

    - * - * @return the parameters used with this signature engine, or null - * if this signature engine does not use any parameters. - * @throws UnsupportedOperationException if this method is not overridden by - * a provider. + * The default implementaion of this method always throws a + * address@hidden UnsupportedOperationException}. It MUST be overridden by concrete + * implementations to return the appropriate address@hidden AlgorithmParameters} for + * this signature engine (or null when that engine does not use + * any parameters. + * + * @return the parameters used with this signature engine, or + * null if it does not use any parameters. + * @throws UnsupportedOperationException + * always. */ protected AlgorithmParameters engineGetParameters() { @@ -267,33 +264,24 @@ } /** - * Gets the value of the specified algorithm parameter. This method supplies - * a general-purpose mechanism through which it is possible to get the various - * parameters of this object. A parameter may be any settable parameter for - * the algorithm, such as a parameter size, or a source of random bits for - * signature generation (if appropriate), or an indication of whether or not - * to perform a specific but optional computation. A uniform algorithm-specific - * naming scheme for each parameter is desirable but left unspecified at this - * time. - * - * @param param the string name of the parameter. - * @return the object that represents the parameter value, or null - * if there is none. - * @throws InvalidParameterException if param is an invalid - * parameter for this engine, or another exception occurs while trying to get - * this parameter. - * @deprecated + * Returns the value for the specified algorithm parameter. + * + * @param param + * the parameter name. + * @return the parameter value. + * @throws InvalidParameterException + * if the parameter is invalid. + * @deprecated use the other getParameter */ protected abstract Object engineGetParameter(String param) throws InvalidParameterException; /** - * Returns a clone if the implementation is cloneable. - * - * @return a clone if the implementation is cloneable. - * @throws CloneNotSupportedException if this is called on an implementation - * that does not support address@hidden Cloneable}. - * @see Cloneable + * Returns a clone of this instance. + * + * @return a clone of this instance. + * @throws CloneNotSupportedException + * if the implementation does not support cloning. */ public Object clone() throws CloneNotSupportedException { Index: java/security/SignedObject.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/SignedObject.java,v retrieving revision 1.12 diff -U3 -r1.12 SignedObject.java --- java/security/SignedObject.java 2 Jul 2005 20:32:40 -0000 1.12 +++ java/security/SignedObject.java 18 Jan 2006 19:34:21 -0000 @@ -46,82 +46,34 @@ import java.io.Serializable; /** - *

    SignedObject is a class for the purpose of creating authentic - * runtime objects whose integrity cannot be compromised without being detected. - *

    - * - *

    More specifically, a SignedObject contains another - * address@hidden Serializable} object, the (to-be-)signed object and its signature.

    - * - *

    The signed object is a "deep copy" (in serialized form) of an - * original object. Once the copy is made, further manipulation of the original - * object has no side effect on the copy.

    - * - *

    The underlying signing algorithm is designated by the address@hidden Signature} - * object passed to the constructor and the verify() method. A - * typical usage for signing is the following:

    - * - * 
    - * Signature signingEngine = Signature.getInstance(algorithm, provider);
- * SignedObject so = new SignedObject(myobject, signingKey, signingEngine);
- *
    - * - *

    A typical usage for verification is the following (having received - * SignedObject so):

    - * - * 
    - * Signature verificationEngine = Signature.getInstance(algorithm, provider);
- * if (so.verify(publickey, verificationEngine))
- *   try
- *     {
- *       Object myobj = so.getObject();
- *     }
- *   catch (ClassNotFoundException ignored) {};
- *
    - * - *

    Several points are worth noting. First, there is no need to initialize the - * signing or verification engine, as it will be re-initialized inside the - * constructor and the verify() method. Secondly, for verification - * to succeed, the specified public key must be the public key corresponding to - * the private key used to generate the SignedObject.

    - * - *

    More importantly, for flexibility reasons, the constructor - * and verify() method allow for customized signature engines, - * which can implement signature algorithms that are not installed formally as - * part of a crypto provider. However, it is crucial that the programmer writing - * the verifier code be aware what address@hidden Signature} engine is being used, as - * its own implementation of the verify() method is invoked to - * verify a signature. In other words, a malicious address@hidden Signature} may choose - * to always return true on verification in an attempt to bypass a - * security check.

    - * - *

    The signature algorithm can be, among others, the NIST standard DSS, - * using DSA and SHA-1. The algorithm is specified using the same - * convention as that for signatures. The DSA algorithm using the - * SHA-1 message digest algorithm can be specified, for example, as - * "SHA/DSA" or "SHA-1/DSA" (they are equivalent). In - * the case of RSA, there are multiple choices for the message digest - * algorithm, so the signing algorithm could be specified as, for example, - * "MD2/RSA", "MD5/RSA" or "SHA-1/RSA". - * The algorithm name must be specified, as there is no default.

    - * - *

    The name of the Cryptography Package Provider is designated also by the - * address@hidden Signature} parameter to the constructor and the - * verify() method. If the provider is not specified, the default - * provider is used. Each installation can be configured to use a particular - * provider as default.

    - * - *

    Potential applications of SignedObject include:

    - * - *
      - *
    • It can be used internally to any Java runtime as an unforgeable - * authorization token -- one that can be passed around without the fear that - * the token can be maliciously modified without being detected.
      • - *
    • It can be used to sign and serialize data/object for storage outside the - * Java runtime (e.g., storing critical access control data on disk).
      • - *
    • Nested SignedObjects can be used to construct a logical sequence - * of signatures, resembling a chain of authorization and delegation.
      • - *
    + * SignedObject is used for storing runtime objects whose + * integrity cannot be compromised without being detected. + * + *

    SignedObject contains a address@hidden Serializable} object which is + * yet to be signed and a digital signature of that object.

    + * + *

    The signed copy is a "deep copy" (in serialized form) of an original + * object. Any changes to that original instance are not reflected in the + * enclosed copy inside this SignedObject.

    + * + *

    Several things to note are that, first there is no need to initialize the + * signature engine as this class will handle that automatically. Second, + * verification will only succeed if the public key corresponds to the private + * key used to generate the digital signature inside this + * SignedObject.

    + * + *

    For fexibility, the signature engine can be specified in the constructor + * or the verify() method. Programmers wishing to verify + * SignedObjects should be aware of the address@hidden Signature} engine + * they use. A malicious or flawed address@hidden Signature} implementation may always + * return true on verification thus circumventing the intended secrity check + * provided by the SignedObject.

    + * + *

    The GNU security provider offers an implementation of the standard NIST + * DSA which uses "DSA" and "SHA-1". It can be specified by "SHA/DSA", + * "SHA-1/DSA" or its OID. If the RSA signature algorithm is provided then it + * could be "MD2/RSA". "MD5/RSA", or "SHA-1/RSA". The algorithm must be + * specified because there is no default.

    * * @author Mark Benvenuto (address@hidden) * @since 1.2 @@ -139,16 +91,22 @@ private String thealgorithm; /** - * Constructs a SignedObject from any address@hidden Serializable} - * object. The given object is signed with the given signing key, using the - * designated signature engine. - * - * @param object the object to be signed. - * @param signingKey the private key for signing. - * @param signingEngine the signature signing engine. - * @throws IOException if an error occurs during serialization. - * @throws InvalidKeyException if the key is invalid. - * @throws SignatureException if signing fails. + * Constructs a new instance of SignedObject from a + * address@hidden Serializable} object. The object is signed with a designated + * private key and a signature engine. + * + * @param object + * the object to sign. + * @param signingKey + * the key to use. + * @param signingEngine + * the signature engine to use. + * @throws IOException + * if a serialization error occurred. + * @throws InvalidKeyException + * if the key is invalid. + * @throws SignatureException + * if a signing error occurs. */ public SignedObject(Serializable object, PrivateKey signingKey, Signature signingEngine) @@ -170,12 +128,14 @@ } /** - * Retrieves the encapsulated object. The encapsulated object is de-serialized - * before it is returned. - * + * Returns the encapsulated object. The object is de-serialized before being + * returned. + * * @return the encapsulated object. - * @throws IOException if an error occurs during de-serialization. - * @throws ClassNotFoundException if an error occurs during de-serialization. + * @throws IOException + * if a de-serialization error occurs. + * @throws ClassNotFoundException + * if the encapsulated object's class was not found. */ public Object getObject() throws IOException, ClassNotFoundException { @@ -189,9 +149,9 @@ } /** - * Retrieves the signature on the signed object, in the form of a byte array. - * - * @return a copy of the signature. + * Returns the signature bytes of the encapsulated object. + * + * @return the signature bytes of the encapsulated object. */ public byte[] getSignature() { @@ -200,9 +160,9 @@ } /** - * Retrieves the name of the signature algorithm. - * - * @return the signature algorithm name. + * Returns the name of the signature algorithm. + * + * @return the name of the signature algorithm. */ public String getAlgorithm() { @@ -210,16 +170,19 @@ } /** - * Verifies that the signature in this SignedObject is the valid - * signature for the object stored inside, with the given verification key, - * using the designated verification engine. - * - * @param verificationKey the public key for verification. - * @param verificationEngine the signature verification engine. - * @return true if the signature is valid, false - * otherwise. - * @throws SignatureException if signature verification failed. - * @throws InvalidKeyException if the verification key is invalid. + * Verifies the encapsulated digital signature by checking that it was + * generated by the owner of a designated public key. + * + * @param verificationKey + * the public key to use. + * @param verificationEngine + * the signature engine to use. + * @return true if signature is correct, false + * otherwise. + * @throws InvalidKeyException + * if the key is invalid. + * @throws SignatureException + * if verification fails. */ public boolean verify(PublicKey verificationKey, Signature verificationEngine) throws InvalidKeyException, SignatureException Index: java/security/Signer.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/Signer.java,v retrieving revision 1.11 diff -U3 -r1.11 Signer.java --- java/security/Signer.java 2 Jul 2005 20:32:40 -0000 1.11 +++ java/security/Signer.java 18 Jan 2006 19:34:21 -0000 @@ -38,35 +38,29 @@ package java.security; /** - *

    This class is used to represent an address@hidden Identity} that can also - * digitally sign data.

    - * - *

    The management of a signer's private keys is an important and sensitive - * issue that should be handled by subclasses as appropriate to their intended - * use.

    + * Signer is a subclass of address@hidden Identity}. It is used to store a + * digital signature key with an Identity. * * @author Mark Benvenuto (address@hidden) - * @deprecated This class is no longer used. Its functionality has been replaced - * by java.security.KeyStore, the java.security.cert - * package, and java.security.Principal. + * @deprecated Replaced by java.security.KeyStore, the + * java.security.cert package, and java.security.Principal. */ public abstract class Signer extends Identity { private static final long serialVersionUID = -1763464102261361480L; private PrivateKey privateKey = null; - /** - * Creates a Signer. This constructor should only be used for - * serialization. - */ + /** Trivial constructor for serialization purposes. */ protected Signer() { } /** - * Creates a Signer with the specified identity name. - * - * @param name the identity name. + * Constructs a new instance of Signer with the specified + * identity name. + * + * @param name + * the name of the identity to use. */ public Signer(String name) { @@ -74,12 +68,16 @@ } /** - * Creates a Signer with the specified identity name and scope. - * - * @param name the identity name. - * @param scope the scope of the identity. - * @throws KeyManagementException if there is already an identity with the - * same name in the scope. + * Constructs a new instance of Signer with the specified + * identity name and address@hidden IdentityScope}. + * + * @param name + * the name of the the identity to use. + * @param scope + * the address@hidden IdentityScope} to use. + * @throws KeyManagementException + * if a duplicate identity name exists within + * scope. */ public Signer(String name, IdentityScope scope) throws KeyManagementException { @@ -87,18 +85,12 @@ } /** - *

    Returns this signer's private key.

    - * - *

    First, if there is a security manager, its checkSecurityAccess() - * method is called with "getSignerPrivateKey" as its - * argument to see if it's ok to return the private key.

    - * - * @return this signer's private key, or null if the private key - * has not yet been set. - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow returning the - * private key. - * @see SecurityManager#checkSecurityAccess(String) + * Returns the private key of this Signer. + * + * @returns the private key of this Signer. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public PrivateKey getPrivateKey() { @@ -110,20 +102,17 @@ } /** - *

    Sets the key pair (public key and private key) for this signer.

    - * - *

    First, if there is a security manager, its checkSecurityAccess() - * method is called with "setSignerKeyPair" as its - * argument to see if it's ok to set the key pair.

    - * - * @param pair an initialized key pair. - * @throws InvalidParameterException if the key pair is not properly - * initialized. - * @throws KeyException if the key pair cannot be set for any other reason. - * @throws SecurityException if a security manager exists and its - * checkSecurityAccess() method doesn't allow setting the key - * pair. - * @see SecurityManager#checkSecurityAccess(String) + * Specifies the address@hidden KeyPair} associated with this Signer. + * + * @param pair + * the address@hidden KeyPair} to use. + * @throws InvalidParameterException + * if the key-pair is invalid. + * @throws KeyException + * if any another key-related error occurs. + * @throws SecurityException + * if a address@hidden SecurityManager} is installed which disallows this + * operation. */ public final void setKeyPair(KeyPair pair) throws InvalidParameterException, KeyException @@ -151,12 +140,7 @@ throw new InvalidParameterException(); } - /** - * Returns a string of information about the signer. - * - * @return a string of information about the signer. - * @see SecurityManager#checkSecurityAccess(String) - */ + /** @returns a string representing this Signer. */ public String toString() { return (getName() + ": " + privateKey); Index: java/security/interfaces/RSAMultiPrimePrivateCrtKey.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/interfaces/RSAMultiPrimePrivateCrtKey.java,v retrieving revision 1.3 diff -U3 -r1.3 RSAMultiPrimePrivateCrtKey.java --- java/security/interfaces/RSAMultiPrimePrivateCrtKey.java 2 Jul 2005 20:32:41 -0000 1.3 +++ java/security/interfaces/RSAMultiPrimePrivateCrtKey.java 18 Jan 2006 19:34:21 -0000 @@ -54,6 +54,7 @@ { // Constants // -------------------------------------------------------------------------- + long serialVersionUID = 618058533534628008L; // Methods @@ -67,45 +68,45 @@ BigInteger getPublicExponent(); /** - * Returns the primeP. + * Returns the prime p. * - * @return the primeP. + * @return the prime p. */ BigInteger getPrimeP(); /** - * Returns the primeQ. + * Returns the prime q. * - * @return the primeQ. + * @return the prime q. */ BigInteger getPrimeQ(); /** - * Returns the primeExponentP. + * Returns the prime's exponent p. * - * @return the primeExponentP. + * @return the prime's exponent p. */ BigInteger getPrimeExponentP(); /** - * Returns the primeExponentQ. + * Returns the prime's exponent q. * - * @return the primeExponentQ. + * @return the prime's exponent q. */ BigInteger getPrimeExponentQ(); /** - * Returns the crtCoefficient. + * Returns the CRT Coefficient. * - * @return the crtCoefficient. + * @return the CRT Coefficient. */ BigInteger getCrtCoefficient(); /** - * Returns the otherPrimeInfo or null if there are only two - * prime factors (p and q). + * Returns the OtherPrimeInfo triplet MPIs or null if + * there are only two known prime factors (p and q). * - * @return the otherPrimeInfo. + * @return the OtherPrimeInfo INTEGERs. */ RSAOtherPrimeInfo[] getOtherPrimeInfo(); } Index: java/security/spec/PSSParameterSpec.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/spec/PSSParameterSpec.java,v retrieving revision 1.2 diff -U3 -r1.2 PSSParameterSpec.java --- java/security/spec/PSSParameterSpec.java 2 Jul 2005 20:32:41 -0000 1.2 +++ java/security/spec/PSSParameterSpec.java 18 Jan 2006 19:34:21 -0000 @@ -38,9 +38,9 @@ package java.security.spec; /** - * This class specifies a parameter spec for RSA PSS encoding scheme, as - * defined in the PKCS#1 v2.1. - * + * An implementation of address@hidden AlgorithmParameterSpec} for the RSA PSS encoding + * scheme. + * * @since 1.4 * @see AlgorithmParameterSpec * @see java.security.Signature @@ -56,12 +56,13 @@ // -------------------------------------------------------------------------- /** - * Creates a new PSSParameterSpec given the salt length as - * defined in PKCS#1. - * - * @param saltLen the length of salt in bits to be used in PKCS#1 PSS encoding. - * @throws IllegalArgumentException if saltLen is less than - * 0. + * Construct a new instance of PSSParameterSpec given a salt + * length. + * + * @param saltLen + * the length in bits of the salt. + * @throws IllegalArgumentException + * if saltLen is less than 0. */ public PSSParameterSpec(int saltLen) { @@ -78,11 +79,7 @@ // Instance methods // -------------------------------------------------------------------------- - /** - * Returns the salt length in bits. - * - * @return the salt length. - */ + /** @return the length (in bits) of the salt. */ public int getSaltLength() { return this.saltLen; Index: java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java,v retrieving revision 1.3 diff -U3 -r1.3 RSAMultiPrimePrivateCrtKeySpec.java --- java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java 2 Jul 2005 20:32:41 -0000 1.3 +++ java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java 18 Jan 2006 19:34:21 -0000 @@ -40,9 +40,9 @@ import java.math.BigInteger; /** - * This class specifies an RSA multi-prime private key, as defined in the + * This class represents an RSA multi-prime private key, as defined in the * PKCS#1 v2.1, using the Chinese Remainder Theorem (CRT) information - * values for efficiency. + * values. * * @since 1.4 * @see java.security.Key @@ -70,29 +70,35 @@ // -------------------------------------------------------------------------- /** - *

    Creates a new RSAMultiPrimePrivateCrtKeySpec given the - * modulus, publicExponent, privateExponent, primeP, primeQ, primeExponentP, - * primeExponentQ, crtCoefficient, and otherPrimeInfo as defined in PKCS#1 - * v2.1.

    - * + * Constructs a new instance of RSAMultiPrimePrivateCrtKeySpec + * given the various PKCS#1 v2.1 parameters. + * *

    Note that otherPrimeInfo is cloned when constructing this * object.

    - * - * @param modulus the modulus n. - * @param publicExponent the public exponent e. - * @param privateExponent the private exponent d. - * @param primeP the prime factor p of n. - * @param primeQ the prime factor q of n. - * @param primeExponentP this is d mod (p-1). - * @param primeExponentQ this is d mod (q-1). - * @param crtCoefficient the Chinese Remainder Theorem coefficient q-1 mod p. - * @param otherPrimeInfo triplets of the rest of primes, null - * can be specified if there are only two prime factors (p and q). - * @throws NullPointerException if any of the parameters, i.e. modulus, - * publicExponent, privateExponent, primeP, primeQ, primeExponentP, - * primeExponentQ, crtCoefficient, is null. - * @throws IllegalArgumentException if an empty, i.e. 0-length, - * otherPrimeInfo is specified. + * + * @param modulus + * the modulus n. + * @param publicExponent + * the public exponent e. + * @param privateExponent + * the private exponent d. + * @param primeP + * the prime factor p of n. + * @param primeQ + * the prime factor q of n. + * @param primeExponentP + * this is d mod (p-1). + * @param primeExponentQ + * this is d mod (q-1). + * @param crtCoefficient + * the Chinese Remainder Theorem coefficient q-1 mod p. + * @param otherPrimeInfo + * triplets of the rest of primes, null can be + * specified if there are only two prime factors (p and q). + * @throws NullPointerException + * if any of the parameters is null. + * @throws IllegalArgumentException + * if an empty otherPrimeInfo is specified. */ public RSAMultiPrimePrivateCrtKeySpec(BigInteger modulus, BigInteger publicExponent, @@ -153,9 +159,9 @@ } /** - * Returns the primeP. + * Returns the prime p. * - * @return the primeP. + * @return the prime p. */ public BigInteger getPrimeP() { @@ -163,9 +169,9 @@ } /** - * Returns the primeQ. + * Returns the prime q. * - * @return the primeQ. + * @return the prime q. */ public BigInteger getPrimeQ() { @@ -173,9 +179,9 @@ } /** - * Returns the primeExponentP. + * Returns d mod (p-1). * - * @return the primeExponentP. + * @return d mod (p-1). */ public BigInteger getPrimeExponentP() { @@ -183,9 +189,9 @@ } /** - * Returns the primeExponentQ. + * Returns d mod (q-1). * - * @return the primeExponentQ. + * @return d mod (q-1). */ public BigInteger getPrimeExponentQ() { @@ -193,9 +199,9 @@ } /** - * Returns the crtCoefficient. + * Returns the CRT Coefficient q-1 mod p. * - * @return the crtCoefficient. + * @return the CRT Coefficient q-1 mod p. */ public BigInteger getCrtCoefficient() { @@ -203,10 +209,10 @@ } /** - * Returns a copy of the otherPrimeInfo or null if there are - * only two prime factors (p and q). + * Returns a clone of otherPrimeInfo or null if + * it was null at construction time. * - * @return the otherPrimeInfo. + * @return a cloned copy of otherPrimeInfo. */ public RSAOtherPrimeInfo[] getOtherPrimeInfo() { Index: java/security/spec/RSAOtherPrimeInfo.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/security/spec/RSAOtherPrimeInfo.java,v retrieving revision 1.2 diff -U3 -r1.2 RSAOtherPrimeInfo.java --- java/security/spec/RSAOtherPrimeInfo.java 2 Jul 2005 20:32:41 -0000 1.2 +++ java/security/spec/RSAOtherPrimeInfo.java 18 Jan 2006 19:34:21 -0000 @@ -40,17 +40,8 @@ import java.math.BigInteger; /** - * This class represents the triplet (prime, exponent, and coefficient) inside - * RSA's OtherPrimeInfo structure, as defined in the PKCS#1 v2.1. The ASN.1 - * syntax of RSA's OtherPrimeInfo is as follows: - * - * 
    - *  OtherPrimeInfo ::= SEQUENCE {
- *    prime INTEGER,
- *    exponent INTEGER,
- *    coefficient INTEGER
- *  }
- *
    + * An in-memory representation of the RSA triplet (prime, exponent, and + * coefficient) inside a PKCS#1 v2.1 OtherPrimeInfo structure. * * @since 1.4 * @see RSAPrivateCrtKeySpec @@ -69,14 +60,16 @@ // -------------------------------------------------------------------------- /** - * Creates a new RSAOtherPrimeInfo given the prime, - * primeExponent, and crtCoefficient as defined in PKCS#1. - * - * @param prime the prime factor of n. - * @param primeExponent the exponent. - * @param crtCoefficient the Chinese Remainder Theorem coefficient. - * @throws NullPointerException if any of the parameters, i.e. prime, - * primeExponent, crtCoefficient, is null. + * Constructs a new RSAOtherPrimeInfo given the PKCS#1 MPIs. + * + * @param prime + * the prime factor of n. + * @param primeExponent + * the exponent. + * @param crtCoefficient + * the Chinese Remainder Theorem coefficient. + * @throws NullPointerException + * if any of the parameters is null. */ public RSAOtherPrimeInfo(BigInteger prime, BigInteger primeExponent, BigInteger crtCoefficient) @@ -122,9 +115,9 @@ } /** - * Returns the prime's crtCoefficient. + * Returns the CRT Coefficient. * - * @return the crtCoefficient. + * @return the CRT Coefficient. */ public final BigInteger getCrtCoefficient() {