archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-26 22:34:27 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8284851: Update javax.crypto files to use proper javadoc for mentioned classes

Browse source 
Reviewed-by: weijun, valeriep
This commit is contained in:
Mark Powers 2022-07-07 23:20:58 +00:00 • committed by Valerie Peng
parent 8cdead0c94
commit f804f2ce8e
92 changed files with 2142 additions and 2010 deletions
Download patch file Download diff file Expand all files Collapse all files

74
src/java.base/share/classes/java/security/AccessControlContext.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -34,28 +34,28 @@ import sun.security.util.SecurityConstants;
/** /**
* An AccessControlContext is used to make system resource access decisions * An {@code AccessControlContext} is used to make system resource access
* based on the context it encapsulates. * decisions based on the context it encapsulates.
* *
* <p>More specifically, it encapsulates a context and * <p>More specifically, it encapsulates a context and
* has a single method, {@code checkPermission}, * has a single method, {@code checkPermission},
* that is equivalent to the {@code checkPermission} method * that is equivalent to the {@code checkPermission} method
* in the AccessController class, with one difference: The AccessControlContext * in the {@code AccessController} class, with one difference:
* {@code checkPermission} method makes access decisions based on the * The {@code checkPermission} method makes access decisions based on the
* context it encapsulates, * context it encapsulates,
* rather than that of the current execution thread. * rather than that of the current execution thread.
* *
* <p>Thus, the purpose of AccessControlContext is for those situations where * <p>Thus, the purpose of {@code AccessControlContext} is for those
* a security check that should be made within a given context * situations where a security check that should be made within a given context
* actually needs to be done from within a * actually needs to be done from within a
* <i>different</i> context (for example, from within a worker thread). * <i>different</i> context (for example, from within a worker thread).
* *
* <p> An AccessControlContext is created by calling the * <p> An {@code AccessControlContext} is created by calling the
* {@code AccessController.getContext} method. * {@code AccessController.getContext} method.
* The {@code getContext} method takes a "snapshot" * The {@code getContext} method takes a "snapshot"
* of the current calling context, and places * of the current calling context, and places
* it in an AccessControlContext object, which it returns. A sample call is * it in an {@code AccessControlContext} object, which it returns.
* the following: * A sample call is the following:
* *
* <pre> * <pre>
* AccessControlContext acc = AccessController.getContext() * AccessControlContext acc = AccessController.getContext()
@ -64,7 +64,7 @@ import sun.security.util.SecurityConstants;
* <p> * <p>
* Code within a different context can subsequently call the * Code within a different context can subsequently call the
* {@code checkPermission} method on the * {@code checkPermission} method on the
* previously-saved AccessControlContext object. A sample call is the * previously-saved {@code AccessControlContext} object. A sample call is the
* following: * following:
* *
* <pre> * <pre>
@ -125,13 +125,14 @@ public final class AccessControlContext {
} }
/** /**
* Create an AccessControlContext with the given array of ProtectionDomains. * Create an {@code AccessControlContext} with the given array of
* Context must not be null. Duplicate domains will be removed from the * {@code ProtectionDomain} objects.
* context. * Context must not be {@code null}. Duplicate domains will be removed
* from the context.
* *
* @param context the ProtectionDomains associated with this context. * @param context the {@code ProtectionDomain} objects associated with this
* The non-duplicate domains are copied from the array. Subsequent * context. The non-duplicate domains are copied from the array. Subsequent
* changes to the array will not affect this AccessControlContext. * changes to the array will not affect this {@code AccessControlContext}.
* @throws NullPointerException if {@code context} is {@code null} * @throws NullPointerException if {@code context} is {@code null}
*/ */
public AccessControlContext(ProtectionDomain[] context) public AccessControlContext(ProtectionDomain[] context)
@ -185,9 +186,9 @@ public final class AccessControlContext {
} }
/** /**
* package private to allow calls from ProtectionDomain without performing * package private to allow calls from (@code ProtectionDomain} without
* the security check for {@linkplain SecurityConstants#CREATE_ACC_PERMISSION} * performing the security check for
* permission * {@linkplain SecurityConstants#CREATE_ACC_PERMISSION} permission
*/ */
AccessControlContext(AccessControlContext acc, AccessControlContext(AccessControlContext acc,
@SuppressWarnings("removal") DomainCombiner combiner, @SuppressWarnings("removal") DomainCombiner combiner,
@ -215,7 +216,7 @@ public final class AccessControlContext {
} }
/** /**
* package private for AccessController * package private for {@code AccessController}
* *
* This "argument wrapper" context will be passed as the actual context * This "argument wrapper" context will be passed as the actual context
* parameter on an internal doPrivileged() call used in the implementation. * parameter on an internal doPrivileged() call used in the implementation.
@ -292,7 +293,7 @@ public final class AccessControlContext {
/** /**
* package private constructor for AccessController.getContext() * package private constructor for {@code AccessController.getContext()}
*/ */
AccessControlContext(ProtectionDomain[] context, AccessControlContext(ProtectionDomain[] context,
@ -304,7 +305,7 @@ public final class AccessControlContext {
} }
/** /**
* Constructor for JavaSecurityAccess.doIntersectionPrivilege() * Constructor for {@code JavaSecurityAccess.doIntersectionPrivilege()}
*/ */
AccessControlContext(ProtectionDomain[] context, AccessControlContext(ProtectionDomain[] context,
AccessControlContext privilegedContext) AccessControlContext privilegedContext)
@ -322,7 +323,7 @@ public final class AccessControlContext {
} }
/** /**
* Returns true if this context is privileged. * Returns {@code true} if this context is privileged.
*/ */
boolean isPrivileged() boolean isPrivileged()
{ {
@ -370,7 +371,7 @@ public final class AccessControlContext {
} }
/** /**
* package private for AccessController * package private for {@code AccessController}
*/ */
@SuppressWarnings("removal") @SuppressWarnings("removal")
DomainCombiner getCombiner() { DomainCombiner getCombiner() {
@ -385,20 +386,22 @@ public final class AccessControlContext {
* Determines whether the access request indicated by the * Determines whether the access request indicated by the
* specified permission should be allowed or denied, based on * specified permission should be allowed or denied, based on
* the security policy currently in effect, and the context in * the security policy currently in effect, and the context in
* this object. The request is allowed only if every ProtectionDomain * this object. The request is allowed only if every
* in the context implies the permission. Otherwise the request is * {@code ProtectionDomain} in the context implies the permission.
* denied. * Otherwise the request is denied.
* *
* <p> * <p>
* This method quietly returns if the access request * This method quietly returns if the access request
* is permitted, or throws a suitable AccessControlException otherwise. * is permitted, or throws a suitable {@code AccessControlException}
* otherwise.
* *
* @param perm the requested permission. * @param perm the requested permission.
* *
* @throws AccessControlException if the specified permission * @throws AccessControlException if the specified permission
* is not permitted, based on the current security policy and the * is not permitted, based on the current security policy and the
* context encapsulated by this object. * context encapsulated by this object.
* @throws NullPointerException if the permission to check for is null. * @throws NullPointerException if the permission to check for is
* {@code null}.
*/ */
@SuppressWarnings("removal") @SuppressWarnings("removal")
public void checkPermission(Permission perm) public void checkPermission(Permission perm)
@ -751,14 +754,15 @@ public final class AccessControlContext {
/** /**
* Checks two AccessControlContext objects for equality. * Checks two {@code AccessControlContext} objects for equality.
* Checks that {@code obj} is * Checks that {@code obj} is
* an AccessControlContext and has the same set of ProtectionDomains * an {@code AccessControlContext} and has the same set of
* as this context. * {@code ProtectionDomain} objects as this context.
* *
* @param obj the object we are testing for equality with this object. * @param obj the object we are testing for equality with this object.
* @return true if {@code obj} is an AccessControlContext, and has the * @return {@code true} if {@code obj} is an {@code AccessControlContext},
* same set of ProtectionDomains as this context, false otherwise. * and has the same set of {@code ProtectionDomain} objects as this context,
* {@code false} otherwise.
*/ */
public boolean equals(Object obj) { public boolean equals(Object obj) {
if (obj == this) if (obj == this)

10
src/java.base/share/classes/java/security/AccessControlException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -26,12 +26,12 @@
package java.security; package java.security;
/** /**
* <p> This exception is thrown by the AccessController to indicate * <p> This exception is thrown by the {@code AccessController} to indicate
* that a requested access (to a critical system resource such as the * that a requested access (to a critical system resource such as the
* file system or the network) is denied. * file system or the network) is denied.
* *
* <p> The reason to deny access can vary. For example, the requested * <p> The reason to deny access can vary. For example, the requested
* permission might be of an incorrect type, contain an invalid * permission might be of an incorrect type, contain an invalid
* value, or request access that is not allowed according to the * value, or request access that is not allowed according to the
* security policy. Such information should be given whenever * security policy. Such information should be given whenever
* possible at the time the exception is thrown. * possible at the time the exception is thrown.
@ -81,8 +81,8 @@ public class AccessControlException extends SecurityException {
} }
/** /**
* Gets the Permission object associated with this exception, or * Gets the {@code Permission} object associated with this exception, or
* null if there was no corresponding Permission object. * {@code null} if there was no corresponding {@code Permission} object.
* *
* @return the Permission object. * @return the Permission object.
*/ */

75
src/java.base/share/classes/java/security/AccessController.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -41,10 +41,10 @@ import jdk.internal.vm.annotation.ForceInline;
import jdk.internal.vm.annotation.ReservedStackAccess; import jdk.internal.vm.annotation.ReservedStackAccess;
/** /**
* <p> The AccessController class is used for access control operations * <p> The {@code AccessController} class is used for access control operations
* and decisions. * and decisions.
* *
* <p> More specifically, the AccessController class is used for * <p> More specifically, the {@code AccessController} class is used for
* three purposes: * three purposes:
* *
* <ul> * <ul>
@ -73,8 +73,8 @@ import jdk.internal.vm.annotation.ReservedStackAccess;
* *
* <p> If a requested access is allowed, * <p> If a requested access is allowed,
* {@code checkPermission} returns quietly. If denied, an * {@code checkPermission} returns quietly. If denied, an
* AccessControlException is * {@code AccessControlException} is
* thrown. AccessControlException can also be thrown if the requested * thrown. {@code AccessControlException} can also be thrown if the requested
* permission is of an incorrect type or contains an invalid value. * permission is of an incorrect type or contains an invalid value.
* Such information is given whenever possible. * Such information is given whenever possible.
* *
@ -147,15 +147,15 @@ import jdk.internal.vm.annotation.ReservedStackAccess;
* }}</pre> * }}</pre>
* *
* <p> * <p>
* PrivilegedAction is an interface with a single method, named * {@code PrivilegedAction} is an interface with a single method, named
* {@code run}. * {@code run}.
* The above example shows creation of an implementation * The above example shows creation of an implementation
* of that interface; a concrete implementation of the * of that interface; a concrete implementation of the
* {@code run} method is supplied. * {@code run} method is supplied.
* When the call to {@code doPrivileged} is made, an * When the call to {@code doPrivileged} is made, an
* instance of the PrivilegedAction implementation is passed * instance of the {@code PrivilegedAction} implementation is passed
* to it. The {@code doPrivileged} method calls the * to it. The {@code doPrivileged} method calls the
* {@code run} method from the PrivilegedAction * {@code run} method from the {@code PrivilegedAction}
* implementation after enabling privileges, and returns the * implementation after enabling privileges, and returns the
* {@code run} method's return value as the * {@code run} method's return value as the
* {@code doPrivileged} return value (which is * {@code doPrivileged} return value (which is
@ -212,10 +212,10 @@ import jdk.internal.vm.annotation.ReservedStackAccess;
* will actually need to be done from within a * will actually need to be done from within a
* <i>different</i> context (for example, from within a worker thread). * <i>different</i> context (for example, from within a worker thread).
* The {@link #getContext() getContext} method and * The {@link #getContext() getContext} method and
* AccessControlContext class are provided * {@code AccessControlContext} class are provided
* for this situation. The {@code getContext} method takes a "snapshot" * for this situation. The {@code getContext} method takes a "snapshot"
* of the current calling context, and places * of the current calling context, and places
* it in an AccessControlContext object, which it returns. A sample call is * it in an {@code AccessControlContext} object, which it returns. A sample call is
* the following: * the following:
* *
* <pre> * <pre>
@ -225,11 +225,11 @@ import jdk.internal.vm.annotation.ReservedStackAccess;
* </pre> * </pre>
* *
* <p> * <p>
* AccessControlContext itself has a {@code checkPermission} method * {@code AccessControlContext} itself has a {@code checkPermission} method
* that makes access decisions based on the context <i>it</i> encapsulates, * that makes access decisions based on the context <i>it</i> encapsulates,
* rather than that of the current execution thread. * rather than that of the current execution thread.
* Code within a different context can thus call that method on the * Code within a different context can thus call that method on the
* previously-saved AccessControlContext object. A sample call is the * previously-saved {@code AccessControlContext} object. A sample call is the
* following: * following:
* *
* <pre> * <pre>
@ -240,8 +240,8 @@ import jdk.internal.vm.annotation.ReservedStackAccess;
* *
* <p> There are also times where you don't know a priori which permissions * <p> There are also times where you don't know a priori which permissions
* to check the context against. In these cases you can use the * to check the context against. In these cases you can use the
* doPrivileged method that takes a context. You can also limit the scope * {@code doPrivileged} method that takes a context. You can also limit the
* of the privileged code by passing additional {@code Permission} * scope of the privileged code by passing additional {@code Permission}
* parameters. * parameters.
* *
* <pre> {@code * <pre> {@code
@ -282,7 +282,7 @@ import jdk.internal.vm.annotation.ReservedStackAccess;
public final class AccessController { public final class AccessController {
/** /**
* Don't allow anyone to instantiate an AccessController * Don't allow anyone to instantiate an {@code AccessController}
*/ */
private AccessController() { } private AccessController() { }
@ -294,8 +294,9 @@ public final class AccessController {
* <p> If the action's {@code run} method throws an (unchecked) * <p> If the action's {@code run} method throws an (unchecked)
* exception, it will propagate through this method. * exception, it will propagate through this method.
* *
* <p> Note that any DomainCombiner associated with the current * <p> Note that any {@code DomainCombiner} associated with the current
* AccessControlContext will be ignored while the action is performed. * {@code AccessControlContext} will be ignored while the action is
* performed.
* *
* @param <T> the type of the value returned by the PrivilegedAction's * @param <T> the type of the value returned by the PrivilegedAction's
* {@code run} method. * {@code run} method.
@ -327,7 +328,7 @@ public final class AccessController {
* exception, it will propagate through this method. * exception, it will propagate through this method.
* *
* <p> This method preserves the current AccessControlContext's * <p> This method preserves the current AccessControlContext's
* DomainCombiner (which may be null) while the action is performed. * {@code DomainCombiner} (which may be null) while the action is performed.
* *
* @param <T> the type of the value returned by the PrivilegedAction's * @param <T> the type of the value returned by the PrivilegedAction's
* {@code run} method. * {@code run} method.
@ -477,7 +478,7 @@ public final class AccessController {
* it will propagate through this method. * it will propagate through this method.
* *
* <p> This method preserves the current AccessControlContext's * <p> This method preserves the current AccessControlContext's
* DomainCombiner (which may be null) while the action is performed. * {@code DomainCombiner} (which may be null) while the action is performed.
* <p> * <p>
* If a security manager is installed and the specified * If a security manager is installed and the specified
* {@code AccessControlContext} was not created by system code and the * {@code AccessControlContext} was not created by system code and the
@ -538,8 +539,9 @@ public final class AccessController {
* <p> If the action's {@code run} method throws an <i>unchecked</i> * <p> If the action's {@code run} method throws an <i>unchecked</i>
* exception, it will propagate through this method. * exception, it will propagate through this method.
* *
* <p> Note that any DomainCombiner associated with the current * <p> Note that any {@code DomainCombiner} associated with the current
* AccessControlContext will be ignored while the action is performed. * {@code AccessControlContext} will be ignored while the action is
* performed.
* *
* @param <T> the type of the value returned by the * @param <T> the type of the value returned by the
* PrivilegedExceptionAction's {@code run} method. * PrivilegedExceptionAction's {@code run} method.
@ -583,7 +585,7 @@ public final class AccessController {
* exception, it will propagate through this method. * exception, it will propagate through this method.
* *
* <p> This method preserves the current AccessControlContext's * <p> This method preserves the current AccessControlContext's
* DomainCombiner (which may be null) while the action is performed. * {@code DomainCombiner} (which may be null) while the action is performed.
* *
* @param <T> the type of the value returned by the * @param <T> the type of the value returned by the
* PrivilegedExceptionAction's {@code run} method. * PrivilegedExceptionAction's {@code run} method.
@ -744,7 +746,7 @@ public final class AccessController {
/** /**
* Sanity check that the caller context is indeed privileged. * Sanity check that the caller context is indeed privileged.
* *
* Used by executePrivileged to make sure the frame is properly * Used by {@code executePrivileged} to make sure the frame is properly
* recognized by the VM. * recognized by the VM.
*/ */
private static boolean isPrivileged() { private static boolean isPrivileged() {
@ -907,7 +909,7 @@ public final class AccessController {
* it will propagate through this method. * it will propagate through this method.
* *
* <p> This method preserves the current AccessControlContext's * <p> This method preserves the current AccessControlContext's
* DomainCombiner (which may be null) while the action is performed. * {@code DomainCombiner} (which may be null) while the action is performed.
* <p> * <p>
* If a security manager is installed and the specified * If a security manager is installed and the specified
* {@code AccessControlContext} was not created by system code and the * {@code AccessControlContext} was not created by system code and the
@ -964,13 +966,13 @@ public final class AccessController {
} }
/** /**
* Returns the AccessControl context. i.e., it gets * Returns the {@code AccessControlContext}. i.e., it gets
* the protection domains of all the callers on the stack, * the protection domains of all the callers on the stack,
* starting at the first class with a non-null * starting at the first class with a non-null
* ProtectionDomain. * {@code ProtectionDomain}.
* *
* @return the access control context based on the current stack or * @return the access control context based on the current stack or
* null if there was only privileged system code. * {@code null} if there was only privileged system code.
*/ */
@SuppressWarnings("removal") @SuppressWarnings("removal")
@ -978,9 +980,9 @@ public final class AccessController {
/** /**
* Returns the "inherited" AccessControl context. This is the context * Returns the "inherited" {@code AccessControlContext}. This is the context
* that existed when the thread was created. Package private so * that existed when the thread was created. Package private so
* AccessControlContext can use it. * {@code AccessControlContext} can use it.
*/ */
@SuppressWarnings("removal") @SuppressWarnings("removal")
@ -988,13 +990,14 @@ public final class AccessController {
/** /**
* This method takes a "snapshot" of the current calling context, which * This method takes a "snapshot" of the current calling context, which
* includes the current Thread's inherited AccessControlContext and any * includes the current thread's inherited {@code AccessControlContext}
* limited privilege scope, and places it in an AccessControlContext object. * and any limited privilege scope, and places it in an
* {@code AccessControlContext} object.
* This context may then be checked at a later point, possibly in another thread. * This context may then be checked at a later point, possibly in another thread.
* *
* @see AccessControlContext * @see AccessControlContext
* *
* @return the AccessControlContext based on the current context. * @return the {@code AccessControlContext} based on the current context.
*/ */
@SuppressWarnings("removal") @SuppressWarnings("removal")
@ -1013,11 +1016,11 @@ public final class AccessController {
/** /**
* Determines whether the access request indicated by the * Determines whether the access request indicated by the
* specified permission should be allowed or denied, based on * specified permission should be allowed or denied, based on
* the current AccessControlContext and security policy. * the current {@code AccessControlContext} and security policy.
* This method quietly returns if the access request * This method quietly returns if the access request
* is permitted, or throws an AccessControlException otherwise. The * is permitted, or throws an {@code AccessControlException} otherwise. The
* getPermission method of the AccessControlException returns the * {@code getPermission} method of the {@code AccessControlException}
* {@code perm} Permission object instance. * returns the {@code Permission} object instance ({@code perm}}.
* *
* @param perm the requested permission. * @param perm the requested permission.
* *

28
src/java.base/share/classes/java/security/AlgorithmConstraints.java
View file

@ -57,14 +57,14 @@ public interface AlgorithmConstraints {
* *
* @param primitives a set of cryptographic primitives * @param primitives a set of cryptographic primitives
* @param algorithm the algorithm name * @param algorithm the algorithm name
* @param parameters the algorithm parameters, or null if no additional * @param parameters the algorithm parameters, or {@code null}
* parameters * if no additional parameters
* *
* @return true if the algorithm is permitted and can be used for all * @return {@code true} if the algorithm is permitted and can be used for
* the specified cryptographic primitives * all the specified cryptographic primitives
* *
* @throws IllegalArgumentException if primitives or algorithm is null * @throws IllegalArgumentException if primitives or algorithm is
* or empty * {@code null} or empty
*/ */
boolean permits(Set<CryptoPrimitive> primitives, boolean permits(Set<CryptoPrimitive> primitives,
String algorithm, AlgorithmParameters parameters); String algorithm, AlgorithmParameters parameters);
@ -78,11 +78,11 @@ public interface AlgorithmConstraints {
* @param primitives a set of cryptographic primitives * @param primitives a set of cryptographic primitives
* @param key the key * @param key the key
* *
* @return true if the key can be used for all the specified * @return {@code true} if the key can be used for all the specified
* cryptographic primitives * cryptographic primitives
* *
* @throws IllegalArgumentException if primitives is null or empty, * @throws IllegalArgumentException if primitives is {@code null}
* or the key is null * or empty, or the key is {@code null}
*/ */
boolean permits(Set<CryptoPrimitive> primitives, Key key); boolean permits(Set<CryptoPrimitive> primitives, Key key);
@ -93,14 +93,14 @@ public interface AlgorithmConstraints {
* @param primitives a set of cryptographic primitives * @param primitives a set of cryptographic primitives
* @param algorithm the algorithm name * @param algorithm the algorithm name
* @param key the key * @param key the key
* @param parameters the algorithm parameters, or null if no additional * @param parameters the algorithm parameters, or {@code null}
* parameters * if no additional parameters
* *
* @return true if the key and the algorithm can be used for all the * @return {@code true} if the key and the algorithm can be used for all the
* specified cryptographic primitives * specified cryptographic primitives
* *
* @throws IllegalArgumentException if primitives or algorithm is null * @throws IllegalArgumentException if primitives or algorithm is
* or empty, or the key is null * {@code null} or empty, or the key is {@code null}
*/ */
boolean permits(Set<CryptoPrimitive> primitives, boolean permits(Set<CryptoPrimitive> primitives,
String algorithm, Key key, AlgorithmParameters parameters); String algorithm, Key key, AlgorithmParameters parameters);

43
src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java
View file

@ -62,7 +62,7 @@ import sun.security.jca.JCAUtil;
* </ul> * </ul>
* *
* <P>In case the client does not explicitly initialize the * <P>In case the client does not explicitly initialize the
* AlgorithmParameterGenerator (via a call to an {@code init} method), * {@code AlgorithmParameterGenerator} (via a call to an {@code init} method),
* each provider must supply (and document) a default initialization. * each provider must supply (and document) a default initialization.
* See the Keysize Restriction sections of the * See the Keysize Restriction sections of the
* {@extLink security_guide_jdk_providers JDK Providers} * {@extLink security_guide_jdk_providers JDK Providers}
@ -71,7 +71,8 @@ import sun.security.jca.JCAUtil;
* However, note that defaults may vary across different providers. * However, note that defaults may vary across different providers.
* Additionally, the default value for a provider may change in a future * Additionally, the default value for a provider may change in a future
* version. Therefore, it is recommended to explicitly initialize the * version. Therefore, it is recommended to explicitly initialize the
* AlgorithmParameterGenerator instead of relying on provider-specific defaults. * {@code AlgorithmParameterGenerator} instead of relying on provider-specific
* defaults.
* *
* <p> Every implementation of the Java platform is required to support the * <p> Every implementation of the Java platform is required to support the
* following standard {@code AlgorithmParameterGenerator} algorithms and * following standard {@code AlgorithmParameterGenerator} algorithms and
@ -108,7 +109,7 @@ public class AlgorithmParameterGenerator {
private final String algorithm; private final String algorithm;
/** /**
* Creates an AlgorithmParameterGenerator object. * Creates an {@code AlgorithmParameterGenerator} object.
* *
* @param paramGenSpi the delegate * @param paramGenSpi the delegate
* @param provider the provider * @param provider the provider
@ -133,14 +134,14 @@ public class AlgorithmParameterGenerator {
} }
/** /**
* Returns an AlgorithmParameterGenerator object for generating * Returns an {@code AlgorithmParameterGenerator} object for generating
* a set of parameters to be used with the specified algorithm. * a set of parameters to be used with the specified algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new AlgorithmParameterGenerator object encapsulating the * A new {@code AlgorithmParameterGenerator} object encapsulating the
* AlgorithmParameterGeneratorSpi implementation from the first * {@code AlgorithmParameterGeneratorSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -187,13 +188,13 @@ public class AlgorithmParameterGenerator {
} }
/** /**
* Returns an AlgorithmParameterGenerator object for generating * Returns an {@code AlgorithmParameterGenerator} object for generating
* a set of parameters to be used with the specified algorithm. * a set of parameters to be used with the specified algorithm.
* *
* <p> A new AlgorithmParameterGenerator object encapsulating the * <p> A new {@code AlgorithmParameterGenerator} object encapsulating the
* AlgorithmParameterGeneratorSpi implementation from the specified provider * {@code AlgorithmParameterGeneratorSpi} implementation from the
* is returned. The specified provider must be registered * specified provider is returned. The specified provider must be
* in the security provider list. * registered in the security provider list.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -205,7 +206,7 @@ public class AlgorithmParameterGenerator {
* Java Security Standard Algorithm Names Specification</a> * Java Security Standard Algorithm Names Specification</a>
* for information about standard algorithm names. * for information about standard algorithm names.
* *
* @param provider the string name of the Provider. * @param provider the string name of the {@code Provider}.
* *
* @return the new {@code AlgorithmParameterGenerator} object * @return the new {@code AlgorithmParameterGenerator} object
* *
@ -240,13 +241,13 @@ public class AlgorithmParameterGenerator {
} }
/** /**
* Returns an AlgorithmParameterGenerator object for generating * Returns an {@code AlgorithmParameterGenerator} object for generating
* a set of parameters to be used with the specified algorithm. * a set of parameters to be used with the specified algorithm.
* *
* <p> A new AlgorithmParameterGenerator object encapsulating the * <p> A new {@code AlgorithmParameterGenerator} object encapsulating the
* AlgorithmParameterGeneratorSpi implementation from the specified Provider * {@code AlgorithmParameterGeneratorSpi} implementation from the specified
* object is returned. Note that the specified Provider object * provider is returned. Note that the specified provider does not
* does not have to be registered in the provider list. * have to be registered in the provider list.
* *
* @param algorithm the string name of the algorithm this * @param algorithm the string name of the algorithm this
* parameter generator is associated with. * parameter generator is associated with.
@ -362,7 +363,7 @@ public class AlgorithmParameterGenerator {
/** /**
* Generates the parameters. * Generates the parameters.
* *
* @return the new AlgorithmParameters object. * @return the new {@code AlgorithmParameters} object.
*/ */
public final AlgorithmParameters generateParameters() { public final AlgorithmParameters generateParameters() {
return paramGenSpi.engineGenerateParameters(); return paramGenSpi.engineGenerateParameters();

7
src/java.base/share/classes/java/security/AlgorithmParameterGeneratorSpi.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -46,7 +46,8 @@ import java.security.spec.AlgorithmParameterSpec;
* However, note that defaults may vary across different providers. * However, note that defaults may vary across different providers.
* Additionally, the default value for a provider may change in a future * Additionally, the default value for a provider may change in a future
* version. Therefore, it is recommended to explicitly initialize the * version. Therefore, it is recommended to explicitly initialize the
* AlgorithmParameterGenerator instead of relying on provider-specific defaults. * {@code AlgorithmParameterGenerator} instead of relying on
* provider-specific defaults.
* *
* @author Jan Luehe * @author Jan Luehe
* *
@ -91,7 +92,7 @@ public abstract class AlgorithmParameterGeneratorSpi {
/** /**
* Generates the parameters. * Generates the parameters.
* *
* @return the new AlgorithmParameters object. * @return the new {@code AlgorithmParameters} object.
*/ */
protected abstract AlgorithmParameters engineGenerateParameters(); protected abstract AlgorithmParameters engineGenerateParameters();
} }

30
src/java.base/share/classes/java/security/AlgorithmParameters.java
View file

@ -87,7 +87,7 @@ public class AlgorithmParameters {
private boolean initialized = false; private boolean initialized = false;
/** /**
* Creates an AlgorithmParameters object. * Creates an {@code AlgorithmParameters} object.
* *
* @param paramSpi the delegate * @param paramSpi the delegate
* @param provider the provider * @param provider the provider
@ -113,11 +113,11 @@ public class AlgorithmParameters {
/** /**
* Returns a parameter object for the specified algorithm. * Returns a parameter object for the specified algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new AlgorithmParameters object encapsulating the * A new {@code AlgorithmParameters} object encapsulating the
* AlgorithmParametersSpi implementation from the first * {@code AlgorithmParametersSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -167,8 +167,8 @@ public class AlgorithmParameters {
/** /**
* Returns a parameter object for the specified algorithm. * Returns a parameter object for the specified algorithm.
* *
* <p> A new AlgorithmParameters object encapsulating the * <p> A new {@code AlgorithmParameters} object encapsulating the
* AlgorithmParametersSpi implementation from the specified provider * {@code AlgorithmParametersSpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -220,9 +220,9 @@ public class AlgorithmParameters {
/** /**
* Returns a parameter object for the specified algorithm. * Returns a parameter object for the specified algorithm.
* *
* <p> A new AlgorithmParameters object encapsulating the * <p> A new {@code AlgorithmParameters} object encapsulating the
* AlgorithmParametersSpi implementation from the specified Provider * {@code AlgorithmParametersSpi} implementation from the specified
* object is returned. Note that the specified Provider object * provider is returned. Note that the specified provider
* does not have to be registered in the provider list. * does not have to be registered in the provider list.
* *
* <p>The returned parameter object must be initialized via a call to * <p>The returned parameter object must be initialized via a call to
@ -315,7 +315,7 @@ public class AlgorithmParameters {
/** /**
* Imports the parameters from {@code params} and decodes them * Imports the parameters from {@code params} and decodes them
* according to the specified decoding scheme. * according to the specified decoding scheme.
* If {@code format} is null, the * If {@code format} is {@code null}, the
* primary decoding format for parameters is used. The primary decoding * primary decoding format for parameters is used. The primary decoding
* format is ASN.1, if an ASN.1 specification for these parameters * format is ASN.1, if an ASN.1 specification for these parameters
* exists. * exists.
@ -382,7 +382,7 @@ public class AlgorithmParameters {
/** /**
* Returns the parameters encoded in the specified scheme. * Returns the parameters encoded in the specified scheme.
* If {@code format} is null, the * If {@code format} is {@code null}, the
* primary encoding format for parameters is used. The primary encoding * primary encoding format for parameters is used. The primary encoding
* format is ASN.1, if an ASN.1 specification for these parameters * format is ASN.1, if an ASN.1 specification for these parameters
* exists. * exists.
@ -405,8 +405,8 @@ public class AlgorithmParameters {
/** /**
* Returns a formatted string describing the parameters. * Returns a formatted string describing the parameters.
* *
* @return a formatted string describing the parameters, or null if this * @return a formatted string describing the parameters, or {@code null}
* parameter object has not been initialized. * if this parameter object has not been initialized.
*/ */
public final String toString() { public final String toString() {
if (!this.initialized) { if (!this.initialized) {

6
src/java.base/share/classes/java/security/AlgorithmParametersSpi.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -84,7 +84,7 @@ public abstract class AlgorithmParametersSpi {
/** /**
* Imports the parameters from {@code params} and * Imports the parameters from {@code params} and
* decodes them according to the specified decoding format. * decodes them according to the specified decoding format.
* If {@code format} is null, the * If {@code format} is {@code null}, the
* primary decoding format for parameters is used. The primary decoding * primary decoding format for parameters is used. The primary decoding
* format is ASN.1, if an ASN.1 specification for these parameters * format is ASN.1, if an ASN.1 specification for these parameters
* exists. * exists.
@ -135,7 +135,7 @@ public abstract class AlgorithmParametersSpi {
/** /**
* Returns the parameters encoded in the specified format. * Returns the parameters encoded in the specified format.
* If {@code format} is null, the * If {@code format} is {@code null}, the
* primary encoding format for parameters is used. The primary encoding * primary encoding format for parameters is used. The primary encoding
* format is ASN.1, if an ASN.1 specification for these parameters * format is ASN.1, if an ASN.1 specification for these parameters
* exists. * exists.

54
src/java.base/share/classes/java/security/AllPermission.java
View file

@ -30,9 +30,9 @@ import sun.security.util.SecurityConstants;
import java.util.Enumeration; import java.util.Enumeration;
/** /**
* The AllPermission is a permission that implies all other permissions. * The {@code AllPermission} is a permission that implies all other permissions.
* <p> * <p>
* <b>Note:</b> Granting AllPermission should be done with extreme care, * <b>Note:</b> Granting {@code AllPermission} should be done with extreme care,
* as it implies all other permissions. Thus, it grants code the ability * as it implies all other permissions. Thus, it grants code the ability
* to run with security * to run with security
* disabled. Extreme caution should be taken before granting such * disabled. Extreme caution should be taken before granting such
@ -60,7 +60,7 @@ public final class AllPermission extends Permission {
private static final long serialVersionUID = -2916474571451318075L; private static final long serialVersionUID = -2916474571451318075L;
/** /**
* Creates a new AllPermission object. * Creates a new {@code AllPermission} object.
*/ */
public AllPermission() { public AllPermission() {
super("<all permissions>"); super("<all permissions>");
@ -68,9 +68,9 @@ public final class AllPermission extends Permission {
/** /**
* Creates a new AllPermission object. This * Creates a new {@code AllPermission} object. This
* constructor exists for use by the {@code Policy} object * constructor exists for use by the {@code Policy} object
* to instantiate new Permission objects. * to instantiate new {@code Permission} objects.
* *
* @param name ignored * @param name ignored
* @param actions ignored. * @param actions ignored.
@ -81,7 +81,7 @@ public final class AllPermission extends Permission {
/** /**
* Checks if the specified permission is "implied" by * Checks if the specified permission is "implied" by
* this object. This method always returns true. * this object. This method always returns {@code true}.
* *
* @param p the permission to check against. * @param p the permission to check against.
* *
@ -92,11 +92,11 @@ public final class AllPermission extends Permission {
} }
/** /**
* Checks two AllPermission objects for equality. Two AllPermission * Checks two {@code AllPermission} objects for equality.
* objects are always equal. * Two {@code AllPermission} objects are always equal.
* *
* @param obj the object we are testing for equality with this object. * @param obj the object we are testing for equality with this object.
* @return true if {@code obj} is an AllPermission, false otherwise. * @return true if {@code obj} is an {@code AllPermission}, false otherwise.
*/ */
public boolean equals(Object obj) { public boolean equals(Object obj) {
return (obj instanceof AllPermission); return (obj instanceof AllPermission);
@ -122,11 +122,11 @@ public final class AllPermission extends Permission {
} }
/** /**
* Returns a new PermissionCollection object for storing AllPermission * Returns a new {@code PermissionCollection} for storing
* objects. * {@code AllPermission} objects.
* *
* @return a new PermissionCollection object suitable for * @return a new {@code PermissionCollection} suitable for
* storing AllPermissions. * storing {@code AllPermission} objects.
*/ */
public PermissionCollection newPermissionCollection() { public PermissionCollection newPermissionCollection() {
return new AllPermissionCollection(); return new AllPermissionCollection();
@ -135,8 +135,8 @@ public final class AllPermission extends Permission {
} }
/** /**
* A AllPermissionCollection stores a collection * An {@code AllPermissionCollection} stores a collection
* of AllPermission permissions. AllPermission objects * of {@code AllPermission} permissions. {@code AllPermission} objects
* must be stored in a manner that allows them to be inserted in any * must be stored in a manner that allows them to be inserted in any
* order, but enable the implies function to evaluate the implies * order, but enable the implies function to evaluate the implies
* method in an efficient (and consistent) manner. * method in an efficient (and consistent) manner.
@ -160,12 +160,12 @@ final class AllPermissionCollection
private static final long serialVersionUID = -4023755556366636806L; private static final long serialVersionUID = -4023755556366636806L;
/** /**
* True if any AllPermissions have been added. * True if any {@code AllPermissionCollection} objects have been added.
*/ */
private boolean all_allowed; private boolean all_allowed;
/** /**
* Create an empty AllPermissions object. * Create an empty {@code AllPermissionCollection} object.
* *
*/ */
@ -174,16 +174,16 @@ final class AllPermissionCollection
} }
/** /**
* Adds a permission to the AllPermissions. The key for the hash is * Adds a permission to the {@code AllPermissionCollection} object.
* permission.path. * The key for the hash is {@code permission.path}.
* *
* @param permission the Permission object to add. * @param permission the {@code Permission} object to add.
* *
* @throws IllegalArgumentException if the permission is not an * @throws IllegalArgumentException if the permission is not an
* AllPermission * {@code AllPermission}
* *
* @throws SecurityException if this AllPermissionCollection object * @throws SecurityException if this {@code AllPermissionCollection}
* has been marked readonly * object has been marked readonly
*/ */
public void add(Permission permission) { public void add(Permission permission) {
@ -200,9 +200,9 @@ final class AllPermissionCollection
* Check and see if this set of permissions implies the permissions * Check and see if this set of permissions implies the permissions
* expressed in "permission". * expressed in "permission".
* *
* @param permission the Permission object to compare * @param permission the {@code Permission} object to compare
* *
* @return always returns true. * @return always returns {@code true}.
*/ */
public boolean implies(Permission permission) { public boolean implies(Permission permission) {
@ -210,10 +210,10 @@ final class AllPermissionCollection
} }
/** /**
* Returns an enumeration of all the AllPermission objects in the * Returns an enumeration of all the {@code AllPermission} objects in the
* container. * container.
* *
* @return an enumeration of all the AllPermission objects. * @return an enumeration of all the {@code AllPermission} objects.
*/ */
public Enumeration<Permission> elements() { public Enumeration<Permission> elements() {
return new Enumeration<>() { return new Enumeration<>() {

120
src/java.base/share/classes/java/security/BasicPermission.java
View file

@ -34,11 +34,11 @@ import java.util.Hashtable;
import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentHashMap;
/** /**
* The BasicPermission class extends the Permission class, and * The {@code BasicPermission} class extends the {@code Permission} class, and
* can be used as the base class for permissions that want to * can be used as the base class for permissions that want to
* follow the same naming convention as BasicPermission. * follow the same naming convention as {@code BasicPermission}.
* <P> * <P>
* The name for a BasicPermission is the name of the given permission * The name for a {@code BasicPermission} is the name of the given permission
* (for example, "exit", * (for example, "exit",
* "setFactory", "print.queueJob", etc.). The naming * "setFactory", "print.queueJob", etc.). The naming
* convention follows the hierarchical property naming convention. * convention follows the hierarchical property naming convention.
@ -47,12 +47,12 @@ import java.util.concurrent.ConcurrentHashMap;
* For example, "*" and "java.*" signify a wildcard match, while "*java", "a*b", * For example, "*" and "java.*" signify a wildcard match, while "*java", "a*b",
* and "java*" do not. * and "java*" do not.
* <P> * <P>
* The action string (inherited from Permission) is unused. * The action string (inherited from {@code Permission}) is unused.
* Thus, BasicPermission is commonly used as the base class for * Thus, {@code BasicPermission} is commonly used as the base class for
* "named" permissions * "named" permissions
* (ones that contain a name but no actions list; you either have the * (ones that contain a name but no actions list; you either have the
* named permission or you don't.) * named permission or you don't.)
* Subclasses may implement actions on top of BasicPermission, * Subclasses may implement actions on top of {@code BasicPermission},
* if desired. * if desired.
* *
* @see java.security.Permission * @see java.security.Permission
@ -82,7 +82,7 @@ public abstract class BasicPermission extends Permission
private transient boolean exitVM; private transient boolean exitVM;
/** /**
* initialize a BasicPermission object. Common to all constructors. * initialize a {@code BasicPermission} object. Common to all constructors.
*/ */
private void init(String name) { private void init(String name) {
if (name == null) if (name == null)
@ -116,12 +116,12 @@ public abstract class BasicPermission extends Permission
} }
/** /**
* Creates a new BasicPermission with the specified name. * Creates a new {@code BasicPermission} with the specified name.
* Name is the symbolic name of the permission, such as * Name is the symbolic name of the permission, such as
* "setFactory", * "setFactory",
* "print.queueJob", or "topLevelWindow", etc. * "print.queueJob", or "topLevelWindow", etc.
* *
* @param name the name of the BasicPermission. * @param name the name of the {@code BasicPermission}.
* *
* @throws NullPointerException if {@code name} is {@code null}. * @throws NullPointerException if {@code name} is {@code null}.
* @throws IllegalArgumentException if {@code name} is empty. * @throws IllegalArgumentException if {@code name} is empty.
@ -133,11 +133,11 @@ public abstract class BasicPermission extends Permission
/** /**
* Creates a new BasicPermission object with the specified name. * Creates a new {@code BasicPermission} object with the specified name.
* The name is the symbolic name of the BasicPermission, and the * The name is the symbolic name of the {@code BasicPermission}, and the
* actions String is currently unused. * actions {@code String} is currently unused.
* *
* @param name the name of the BasicPermission. * @param name the name of the {@code BasicPermission}.
* @param actions ignored. * @param actions ignored.
* *
* @throws NullPointerException if {@code name} is {@code null}. * @throws NullPointerException if {@code name} is {@code null}.
@ -152,7 +152,7 @@ public abstract class BasicPermission extends Permission
* Checks if the specified permission is "implied" by * Checks if the specified permission is "implied" by
* this object. * this object.
* <P> * <P>
* More specifically, this method returns true if: * More specifically, this method returns {@code true} if:
* <ul> * <ul>
* <li> {@code p}'s class is the same as this object's class, and * <li> {@code p}'s class is the same as this object's class, and
* <li> {@code p}'s name equals or (in the case of wildcards) * <li> {@code p}'s name equals or (in the case of wildcards)
@ -162,8 +162,8 @@ public abstract class BasicPermission extends Permission
* *
* @param p the permission to check against. * @param p the permission to check against.
* *
* @return true if the passed permission is equal to or * @return {@code true} if the passed permission is equal to or
* implied by this permission, false otherwise. * implied by this permission, {@code false} otherwise.
*/ */
@Override @Override
public boolean implies(Permission p) { public boolean implies(Permission p) {
@ -193,13 +193,14 @@ public abstract class BasicPermission extends Permission
} }
/** /**
* Checks two BasicPermission objects for equality. * Checks two {@code BasicPermission} objects for equality.
* Checks that {@code obj}'s class is the same as this object's class * Checks that {@code obj}'s class is the same as this object's class
* and has the same name as this object. * and has the same name as this object.
* *
* @param obj the object we are testing for equality with this object. * @param obj the object we are testing for equality with this object.
* @return true if {@code obj}'s class is the same as this object's class * @return {@code true} if {@code obj}'s class is the same as this
* and has the same name as this BasicPermission object, false otherwise. * object's class and has the same name as this {@code BasicPermission}
* object, {@code false} otherwise.
*/ */
@Override @Override
public boolean equals(Object obj) { public boolean equals(Object obj) {
@ -219,7 +220,7 @@ public abstract class BasicPermission extends Permission
* Returns the hash code value for this object. * Returns the hash code value for this object.
* The hash code used is the hash code of the name, that is, * The hash code used is the hash code of the name, that is,
* {@code getName().hashCode()}, where {@code getName} is * {@code getName().hashCode()}, where {@code getName} is
* from the Permission superclass. * from the {@code Permission} superclass.
* *
* @return a hash code value for this object. * @return a hash code value for this object.
*/ */
@ -231,7 +232,7 @@ public abstract class BasicPermission extends Permission
/** /**
* Returns the canonical string representation of the actions, * Returns the canonical string representation of the actions,
* which currently is the empty string "", since there are no actions for * which currently is the empty string "", since there are no actions for
* a BasicPermission. * a {@code BasicPermission}.
* *
* @return the empty string "". * @return the empty string "".
*/ */
@ -241,16 +242,16 @@ public abstract class BasicPermission extends Permission
} }
/** /**
* Returns a new PermissionCollection object for storing BasicPermission * Returns a new {@code PermissionCollection} object for storing
* objects. * {@code BasicPermission} objects.
* *
* <p>BasicPermission objects must be stored in a manner that allows them * <p>{@code BasicPermission} objects must be stored in a manner
* to be inserted in any order, but that also enables the * that allows them to be inserted in any order, but that also enables the
* PermissionCollection {@code implies} method * {@link PermissionCollection#implies} method
* to be implemented in an efficient (and consistent) manner. * to be implemented in an efficient (and consistent) manner.
* *
* @return a new PermissionCollection object suitable for * @return a new {@code PermissionCollection} object suitable for
* storing BasicPermissions. * storing {@code BasicPermission} objects.
*/ */
@Override @Override
public PermissionCollection newPermissionCollection() { public PermissionCollection newPermissionCollection() {
@ -258,8 +259,8 @@ public abstract class BasicPermission extends Permission
} }
/** /**
* readObject is called to restore the state of the BasicPermission from * {@code readObject} is called to restore the state of the
* a stream. * (@code BasicPermission} from a stream.
* *
* @param s the {@code ObjectInputStream} from which data is read * @param s the {@code ObjectInputStream} from which data is read
* @throws IOException if an I/O error occurs * @throws IOException if an I/O error occurs
@ -275,12 +276,12 @@ public abstract class BasicPermission extends Permission
} }
/** /**
* Returns the canonical name of this BasicPermission. * Returns the canonical name of this {@code BasicPermission}.
* All internal invocations of getName should invoke this method, so * All internal invocations of getName should invoke this method, so
* that the pre-JDK 1.6 "exitVM" and current "exitVM.*" permission are * that the pre-JDK 1.6 "exitVM" and current "exitVM.*" permission are
* equivalent in equals/hashCode methods. * equivalent in equals/hashCode methods.
* *
* @return the canonical name of this BasicPermission. * @return the canonical name of this {@code BasicPermission}.
*/ */
final String getCanonicalName() { final String getCanonicalName() {
return exitVM ? "exitVM.*" : getName(); return exitVM ? "exitVM.*" : getName();
@ -288,14 +289,14 @@ public abstract class BasicPermission extends Permission
} }
/** /**
* A BasicPermissionCollection stores a collection * A {@code BasicPermissionCollection} stores a collection
* of BasicPermission permissions. BasicPermission objects * of {@code BasicPermission} permissions. {@code BasicPermission} objects
* must be stored in a manner that allows them to be inserted in any * must be stored in a manner that allows them to be inserted in any
* order, but enable the implies function to evaluate the implies * order, but enable the implies function to evaluate the implies
* method in an efficient (and consistent) manner. * method in an efficient (and consistent) manner.
* *
* A BasicPermissionCollection handles comparing a permission like "a.b.c.d.e" * A {@code BasicPermissionCollection} handles comparing a permission
* with a Permission such as "a.b.*", or "*". * like "a.b.c.d.e" with a {@code Permission} such as "a.b.*", or "*".
* *
* @see java.security.Permission * @see java.security.Permission
* @see java.security.Permissions * @see java.security.Permissions
@ -322,15 +323,15 @@ final class BasicPermissionCollection
private transient ConcurrentHashMap<String, Permission> perms; private transient ConcurrentHashMap<String, Permission> perms;
/** /**
* This is set to {@code true} if this BasicPermissionCollection * This is set to {@code true} if this (@code BasicPermissionCollection}
* contains a BasicPermission with '*' as its permission name. * contains a {code BasicPermission} with '*' as its permission name.
* *
* @see #serialPersistentFields * @see #serialPersistentFields
*/ */
private boolean all_allowed; private boolean all_allowed;
/** /**
* The class to which all BasicPermissions in this * The class to which all {@code BasicPermission} objects in this
* BasicPermissionCollection belong. * BasicPermissionCollection belong.
* *
* @see #serialPersistentFields * @see #serialPersistentFields
@ -348,19 +349,19 @@ final class BasicPermissionCollection
} }
/** /**
* Adds a permission to the BasicPermissions. The key for the hash is * Adds a permission to the {@code BasicPermission} object.
* permission.path. * The key for the hash is permission.path.
* *
* @param permission the Permission object to add. * @param permission the {@code Permission} object to add.
* *
* @throws IllegalArgumentException if the permission is not a * @throws IllegalArgumentException if the permission is not a
* BasicPermission, or if * {@code BasicPermission}, or if
* the permission is not of the * the permission is not of the
* same Class as the other * same class as the other
* permissions in this collection. * permissions in this collection.
* *
* @throws SecurityException if this BasicPermissionCollection object * @throws SecurityException if this {@code BasicPermissionCollection}
* has been marked readonly * object has been marked readonly
*/ */
@Override @Override
public void add(Permission permission) { public void add(Permission permission) {
@ -370,7 +371,7 @@ final class BasicPermissionCollection
if (isReadOnly()) if (isReadOnly())
throw new SecurityException("attempt to add a Permission to a readonly PermissionCollection"); throw new SecurityException("attempt to add a Permission to a readonly PermissionCollection");
// make sure we only add new BasicPermissions of the same class // make sure we only add new BasicPermission objects of the same class
// Also check null for compatibility with deserialized form from // Also check null for compatibility with deserialized form from
// previous versions. // previous versions.
if (permClass == null) { if (permClass == null) {
@ -398,8 +399,8 @@ final class BasicPermissionCollection
* *
* @param permission the Permission object to compare * @param permission the Permission object to compare
* *
* @return true if "permission" is a proper subset of a permission in * @return {@code true} if "permission" is a proper subset of a
* the set, false if not. * permission in the set, {@code false} if not.
*/ */
@Override @Override
public boolean implies(Permission permission) { public boolean implies(Permission permission) {
@ -470,16 +471,19 @@ final class BasicPermissionCollection
// private Hashtable permissions; // private Hashtable permissions;
/** /**
* @serialField permissions java.util.Hashtable * @serialField permissions java.util.Hashtable
* The BasicPermissions in this BasicPermissionCollection. * The {@code BasicPermission} objects in this
* All BasicPermissions in the collection must belong to the same class. * {@code BasicPermissionCollection}.
* The Hashtable is indexed by the BasicPermission name; the value * All {@code BasicPermission} objects in the collection must belong
* of the Hashtable entry is the permission. * to the same class.
* The Hashtable is indexed by the {@code BasicPermission} name;
* the value of the Hashtable entry is the permission.
* @serialField all_allowed boolean * @serialField all_allowed boolean
* This is set to {@code true} if this BasicPermissionCollection * This is set to {@code true} if this {@code BasicPermissionCollection}
* contains a BasicPermission with '*' as its permission name. * contains a {@code BasicPermission} object
* with '*' as its permission name.
* @serialField permClass java.lang.Class * @serialField permClass java.lang.Class
* The class to which all BasicPermissions in this * The class to which all {@code BasicPermission} objectss in this
* BasicPermissionCollection belongs. * {@code BasicPermissionCollection} belongs.
*/ */
@java.io.Serial @java.io.Serial
private static final ObjectStreamField[] serialPersistentFields = { private static final ObjectStreamField[] serialPersistentFields = {
@ -520,7 +524,7 @@ final class BasicPermissionCollection
/** /**
* readObject is called to restore the state of the * readObject is called to restore the state of the
* BasicPermissionCollection from a stream. * {@code BasicPermissionCollection} from a stream.
* *
* @param in the {@code ObjectInputStream} from which data is read * @param in the {@code ObjectInputStream} from which data is read
* @throws IOException if an I/O error occurs * @throws IOException if an I/O error occurs

6
src/java.base/share/classes/java/security/Certificate.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -44,13 +44,13 @@ import java.util.Date;
* public key, the principal whose key it is, and the guarantor * public key, the principal whose key it is, and the guarantor
* guaranteeing that the public key is that of the specified * guaranteeing that the public key is that of the specified
* principal. So an implementation of X.509 certificates and an * principal. So an implementation of X.509 certificates and an
* implementation of PGP certificates can both utilize the Certificate * implementation of PGP certificates can both utilize the {@code Certificate}
* interface, even though their formats and additional types and * interface, even though their formats and additional types and
* amounts of information stored are different. * amounts of information stored are different.
* *
* <p><b>Important</b>: This interface is useful for cataloging and * <p><b>Important</b>: This interface is useful for cataloging and
* grouping objects sharing certain common uses. It does not have any * grouping objects sharing certain common uses. It does not have any
* semantics of its own. In particular, a Certificate object does not * semantics of its own. In particular, a {@code Certificate} object does not
* make any statement as to the <i>validity</i> of the binding. It is * make any statement as to the <i>validity</i> of the binding. It is
* the duty of the application implementing this interface to verify * the duty of the application implementing this interface to verify
* the certificate and satisfy itself of its validity. * the certificate and satisfy itself of its validity.

5
src/java.base/share/classes/java/security/CodeSigner.java
View file

@ -61,7 +61,7 @@ public final class CodeSigner implements Serializable {
private transient int myhash = -1; private transient int myhash = -1;
/** /**
* Constructs a CodeSigner object. * Constructs a {@code CodeSigner} object.
* *
* @param signerCertPath The signer's certificate path. * @param signerCertPath The signer's certificate path.
* It must not be {@code null}. * It must not be {@code null}.
@ -123,7 +123,8 @@ public final class CodeSigner implements Serializable {
* *
* @param obj the object to test for equality with this object. * @param obj the object to test for equality with this object.
* *
* @return true if the objects are considered equal, false otherwise. * @return {@code true} if the objects are considered equal,
* {@code false} otherwise.
*/ */
public boolean equals(Object obj) { public boolean equals(Object obj) {
if ((!(obj instanceof CodeSigner that))) { if ((!(obj instanceof CodeSigner that))) {

81
src/java.base/share/classes/java/security/CodeSource.java
View file

@ -79,16 +79,16 @@ public class CodeSource implements java.io.Serializable {
private transient CertificateFactory factory = null; private transient CertificateFactory factory = null;
/** /**
* A String form of the URL for use as a key in HashMaps/Sets. The String * A {@code String} form of the URL for use as a key in HashMaps/Sets.
* form should behave in the same manner as the URL when compared for * The {@code String} form should behave in the same manner as the URL
* equality in a HashMap/Set, except that no nameservice lookup is done * when compared for equality in a HashMap/Set, except that no nameservice
* on the hostname (only string comparison), and the fragment is not * lookup is done on the hostname (only string comparison), and the
* considered. * fragment is not considered.
*/ */
private transient String locationNoFragString; private transient String locationNoFragString;
/** /**
* Constructs a CodeSource and associates it with the specified * Constructs a {@code CodeSource} and associates it with the specified
* location and set of certificates. * location and set of certificates.
* *
* @param url the location (URL). It may be {@code null}. * @param url the location (URL). It may be {@code null}.
@ -108,7 +108,7 @@ public class CodeSource implements java.io.Serializable {
} }
/** /**
* Constructs a CodeSource and associates it with the specified * Constructs a {@code CodeSource} and associates it with the specified
* location and set of code signers. * location and set of code signers.
* *
* @param url the location (URL). It may be {@code null}. * @param url the location (URL). It may be {@code null}.
@ -144,14 +144,15 @@ public class CodeSource implements java.io.Serializable {
/** /**
* Tests for equality between the specified object and this * Tests for equality between the specified object and this
* object. Two CodeSource objects are considered equal if their * object. Two {@code CodeSource} objects are considered equal if their
* locations are of identical value and if their signer certificate * locations are of identical value and if their signer certificate
* chains are of identical value. It is not required that * chains are of identical value. It is not required that
* the certificate chains be in the same order. * the certificate chains be in the same order.
* *
* @param obj the object to test for equality with this object. * @param obj the object to test for equality with this object.
* *
* @return true if the objects are considered equal, false otherwise. * @return {@code true} if the objects are considered equal,
* {@code false} otherwise.
*/ */
@Override @Override
public boolean equals(Object obj) { public boolean equals(Object obj) {
@ -165,7 +166,7 @@ public class CodeSource implements java.io.Serializable {
} }
/** /**
* Returns the location associated with this CodeSource. * Returns the location associated with this {@code CodeSource}.
* *
* @return the location (URL), or {@code null} if no URL was supplied * @return the location (URL), or {@code null} if no URL was supplied
* during construction. * during construction.
@ -177,20 +178,21 @@ public class CodeSource implements java.io.Serializable {
} }
/** /**
* Returns a String form of the URL for use as a key in HashMaps/Sets. * Returns a {@code String} form of the URL for use as a key in
* HashMaps/Sets.
*/ */
String getLocationNoFragString() { String getLocationNoFragString() {
return locationNoFragString; return locationNoFragString;
} }
/** /**
* Returns the certificates associated with this CodeSource. * Returns the certificates associated with this {@code CodeSource}.
* <p> * <p>
* If this CodeSource object was created using the * If this {@code CodeSource} object was created using the
* {@link #CodeSource(URL url, CodeSigner[] signers)} * {@link #CodeSource(URL url, CodeSigner[] signers)}
* constructor then its certificate chains are extracted and used to * constructor then its certificate chains are extracted and used to
* create an array of Certificate objects. Each signer certificate is * create an array of {@code Certificate} objects. Each signer certificate
* followed by its supporting certificate chain (which may be empty). * is followed by its supporting certificate chain (which may be empty).
* Each signer certificate and its supporting certificate chain is ordered * Each signer certificate and its supporting certificate chain is ordered
* bottom-to-top (i.e., with the signer certificate first and the (root) * bottom-to-top (i.e., with the signer certificate first and the (root)
* certificate authority last). * certificate authority last).
@ -220,13 +222,13 @@ public class CodeSource implements java.io.Serializable {
} }
/** /**
* Returns the code signers associated with this CodeSource. * Returns the code signers associated with this {@code CodeSource}.
* <p> * <p>
* If this CodeSource object was created using the * If this {@code CodeSource} object was created using the
* {@link #CodeSource(URL url, java.security.cert.Certificate[] certs)} * {@link #CodeSource(URL url, java.security.cert.Certificate[] certs)}
* constructor then its certificate chains are extracted and used to * constructor then its certificate chains are extracted and used to
* create an array of CodeSigner objects. Note that only X.509 certificates * create an array of {@code CodeSigner} objects. Note that only X.509
* are examined - all other certificate types are ignored. * certificates are examined - all other certificate types are ignored.
* *
* @return a copy of the code signer array, or {@code null} if there * @return a copy of the code signer array, or {@code null} if there
* is none. * is none.
@ -248,10 +250,12 @@ public class CodeSource implements java.io.Serializable {
} }
/** /**
* Returns true if this CodeSource object "implies" the specified CodeSource. * Returns true if this {@code CodeSource} object "implies" the specified
* {@code CodeSource}.
* <p> * <p>
* More specifically, this method makes the following checks. * More specifically, this method makes the following checks.
* If any fail, it returns false. If they all succeed, it returns true. * If any fail, it returns {@code false}. If they all succeed, it returns
* {@code true}.
* <ul> * <ul>
* <li> <i>codesource</i> must not be null. * <li> <i>codesource</i> must not be null.
* <li> If this object's certificates are not null, then all * <li> If this object's certificates are not null, then all
@ -298,9 +302,9 @@ public class CodeSource implements java.io.Serializable {
* </ul> * </ul>
* <p> * <p>
* For example, the codesource objects with the following locations * For example, the codesource objects with the following locations
* and null certificates all imply * and {@code null} certificates all imply the codesource with the location
* the codesource with the location "http://www.example.com/classes/foo.jar" * {@code http://www.example.com/classes/foo.jar}
* and null certificates: * and {@code null} certificates:
* <pre> * <pre>
* http: * http:
* http://*.example.com/classes/* * http://*.example.com/classes/*
@ -308,13 +312,14 @@ public class CodeSource implements java.io.Serializable {
* http://www.example.com/classes/foo.jar * http://www.example.com/classes/foo.jar
* </pre> * </pre>
* *
* Note that if this CodeSource has a null location and a null * Note that if this {@code CodeSource} has a {@code null} location and a
* certificate chain, then it implies every other CodeSource. * {@code null} certificate chain, then it implies every other
* {@code CodeSource}.
* *
* @param codesource CodeSource to compare against. * @param codesource {@code CodeSource} to compare against.
* *
* @return true if the specified codesource is implied by this codesource, * @return {@code true} if the specified codesource is implied by this
* false if not. * codesource, {@code false} if not.
*/ */
public boolean implies(CodeSource codesource) public boolean implies(CodeSource codesource)
{ {
@ -325,11 +330,11 @@ public class CodeSource implements java.io.Serializable {
} }
/** /**
* Returns true if all the certs in this * Returns {@code true} if all the certs in this
* CodeSource are also in <i>that</i>. * {@code CodeSource} are also in <i>that</i>.
* *
* @param that the CodeSource to check against. * @param that the {@code CodeSource} to check against.
* @param strict if true then a strict equality match is performed. * @param strict if {@code true} then a strict equality match is performed.
* Otherwise, a subset match is performed. * Otherwise, a subset match is performed.
*/ */
boolean matchCerts(CodeSource that, boolean strict) boolean matchCerts(CodeSource that, boolean strict)
@ -383,9 +388,9 @@ public class CodeSource implements java.io.Serializable {
/** /**
* Returns true if two CodeSource's have the "same" location. * Returns {@code true} if two CodeSource's have the "same" location.
* *
* @param that CodeSource to compare against * @param that {@code CodeSource} to compare against
*/ */
private boolean matchLocation(CodeSource that) { private boolean matchLocation(CodeSource that) {
if (location == null) if (location == null)
@ -469,10 +474,10 @@ public class CodeSource implements java.io.Serializable {
} }
/** /**
* Returns a string describing this CodeSource, telling its * Returns a string describing this {@code CodeSource}, telling its
* URL and certificates. * URL and certificates.
* *
* @return information about this CodeSource. * @return information about this {@code CodeSource}.
*/ */
@Override @Override
public String toString() { public String toString() {
@ -623,7 +628,7 @@ public class CodeSource implements java.io.Serializable {
* The array of certificates is a concatenation of certificate chains * The array of certificates is a concatenation of certificate chains
* where the initial certificate in each chain is the end-entity cert. * where the initial certificate in each chain is the end-entity cert.
* *
* @return an array of code signers or null if none are generated. * @return an array of code signers or {@code null} if none are generated.
*/ */
private CodeSigner[] convertCertArrayToSignerArray( private CodeSigner[] convertCertArrayToSignerArray(
java.security.cert.Certificate[] certs) { java.security.cert.Certificate[] certs) {

10
src/java.base/share/classes/java/security/DigestException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -37,8 +37,8 @@ public class DigestException extends GeneralSecurityException {
private static final long serialVersionUID = 5821450303093652515L; private static final long serialVersionUID = 5821450303093652515L;
/** /**
* Constructs a DigestException with no detail message. (A * Constructs a {@code DigestException} with no detail message. (A
* detail message is a String that describes this particular * detail message is a {@code String} that describes this particular
* exception.) * exception.)
*/ */
public DigestException() { public DigestException() {
@ -46,8 +46,8 @@ public class DigestException extends GeneralSecurityException {
} }
/** /**
* Constructs a DigestException with the specified detail * Constructs a {@code DigestException} with the specified detail
* message. (A detail message is a String that describes this * message. (A detail message is a {@code String} that describes this
* particular exception.) * particular exception.)
* *
* @param msg the detail message. * @param msg the detail message.

4
src/java.base/share/classes/java/security/DigestInputStream.java
View file

@ -169,8 +169,8 @@ public class DigestInputStream extends FilterInputStream {
* update on the message digest. But when it is off, the message * update on the message digest. But when it is off, the message
* digest is not updated. * digest is not updated.
* *
* @param on true to turn the digest function on, false to turn * @param on {@code true} to turn the digest function on,
* it off. * {@code false} to turn it off.
*/ */
public void on(boolean on) { public void on(boolean on) {
this.on = on; this.on = on;

4
src/java.base/share/classes/java/security/DigestOutputStream.java
View file

@ -152,8 +152,8 @@ public class DigestOutputStream extends FilterOutputStream {
* update on the message digest. But when it is off, the message * update on the message digest. But when it is off, the message
* digest is not updated. * digest is not updated.
* *
* @param on true to turn the digest function on, false to turn it * @param on {@code true} to turn the digest function on,
* off. * {@code false} to turn it off.
*/ */
public void on(boolean on) { public void on(boolean on) {
this.on = on; this.on = on;

18
src/java.base/share/classes/java/security/DomainCombiner.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -35,21 +35,21 @@ package java.security;
* The newly constructed context is then passed to the * The newly constructed context is then passed to the
* {@code AccessController.doPrivileged(..., context)} method * {@code AccessController.doPrivileged(..., context)} method
* to bind the provided context (and associated {@code DomainCombiner}) * to bind the provided context (and associated {@code DomainCombiner})
* with the current execution Thread. Subsequent calls to * with the current execution thread. Subsequent calls to
* {@code AccessController.getContext} or * {@code AccessController.getContext} or
* {@code AccessController.checkPermission} * {@code AccessController.checkPermission}
* cause the {@code DomainCombiner.combine} to get invoked. * cause the {@code DomainCombiner.combine} to get invoked.
* *
* <p> The combine method takes two arguments. The first argument represents * <p> The combine method takes two arguments. The first argument represents
* an array of ProtectionDomains from the current execution Thread, * an array of ProtectionDomains from the current execution thread,
* since the most recent call to {@code AccessController.doPrivileged}. * since the most recent call to {@code AccessController.doPrivileged}.
* If no call to doPrivileged was made, then the first argument will contain * If no call to doPrivileged was made, then the first argument will contain
* all the ProtectionDomains from the current execution Thread. * all the ProtectionDomains from the current execution thread.
* The second argument represents an array of inherited ProtectionDomains, * The second argument represents an array of inherited ProtectionDomains,
* which may be {@code null}. ProtectionDomains may be inherited * which may be {@code null}. ProtectionDomains may be inherited
* from a parent Thread, or from a privileged context. If no call to * from a parent thread, or from a privileged context. If no call to
* doPrivileged was made, then the second argument will contain the * doPrivileged was made, then the second argument will contain the
* ProtectionDomains inherited from the parent Thread. If one or more calls * ProtectionDomains inherited from the parent thread. If one or more calls
* to doPrivileged were made, and the most recent call was to * to doPrivileged were made, and the most recent call was to
* doPrivileged(action, context), then the second argument will contain the * doPrivileged(action, context), then the second argument will contain the
* ProtectionDomains from the privileged context. If the most recent call * ProtectionDomains from the privileged context. If the most recent call
@ -94,16 +94,16 @@ public interface DomainCombiner {
* set of Permissions, for example). * set of Permissions, for example).
* *
* @param currentDomains the ProtectionDomains associated with the * @param currentDomains the ProtectionDomains associated with the
* current execution Thread, up to the most recent * current execution thread, up to the most recent
* privileged {@code ProtectionDomain}. * privileged {@code ProtectionDomain}.
* The ProtectionDomains are listed in order of execution, * The ProtectionDomains are listed in order of execution,
* with the most recently executing {@code ProtectionDomain} * with the most recently executing {@code ProtectionDomain}
* residing at the beginning of the array. This parameter may * residing at the beginning of the array. This parameter may
* be {@code null} if the current execution Thread * be {@code null} if the current execution thread
* has no associated ProtectionDomains. * has no associated ProtectionDomains.
* *
* @param assignedDomains an array of inherited ProtectionDomains. * @param assignedDomains an array of inherited ProtectionDomains.
* ProtectionDomains may be inherited from a parent Thread, * ProtectionDomains may be inherited from a parent thread,
* or from a privileged {@code AccessControlContext}. * or from a privileged {@code AccessControlContext}.
* This parameter may be {@code null} * This parameter may be {@code null}
* if there are no inherited ProtectionDomains. * if there are no inherited ProtectionDomains.

2
src/java.base/share/classes/java/security/DomainLoadStoreParameter.java
View file

@ -109,7 +109,7 @@ public final class DomainLoadStoreParameter implements LoadStoreParameter {
private final Map<String,ProtectionParameter> protectionParams; private final Map<String,ProtectionParameter> protectionParams;
/** /**
* Constructs a DomainLoadStoreParameter for a keystore domain with * Constructs a {@code DomainLoadStoreParameter} for a keystore domain with
* the parameters used to protect keystore data. * the parameters used to protect keystore data.
* *
* @param configuration identifier for the domain configuration data. * @param configuration identifier for the domain configuration data.

8
src/java.base/share/classes/java/security/GeneralSecurityException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -40,16 +40,16 @@ public class GeneralSecurityException extends Exception {
private static final long serialVersionUID = 894798122053539237L; private static final long serialVersionUID = 894798122053539237L;
/** /**
* Constructs a GeneralSecurityException with no detail message. * Constructs a {@code GeneralSecurityException} with no detail message.
*/ */
public GeneralSecurityException() { public GeneralSecurityException() {
super(); super();
} }
/** /**
* Constructs a GeneralSecurityException with the specified detail * Constructs a {@code GeneralSecurityException} with the specified detail
* message. * message.
* A detail message is a String that describes this particular * A detail message is a {@code String} that describes this particular
* exception. * exception.
* *
* @param msg the detail message. * @param msg the detail message.

2
src/java.base/share/classes/java/security/Guard.java
View file

@ -46,7 +46,7 @@ public interface Guard {
/** /**
* Determines whether to allow access to the guarded object * Determines whether to allow access to the guarded object
* {@code object}. Returns silently if access is allowed. * {@code object}. Returns silently if access is allowed.
* Otherwise, throws a SecurityException. * Otherwise, throws a {@code SecurityException}.
* *
* @param object the object being protected by the guard. * @param object the object being protected by the guard.
* *

2
src/java.base/share/classes/java/security/GuardedObject.java
View file

@ -68,7 +68,7 @@ public class GuardedObject implements java.io.Serializable {
/** /**
* Constructs a GuardedObject using the specified object and guard. * Constructs a GuardedObject using the specified object and guard.
* If the Guard object is null, then no restrictions will * If the Guard object is {@code null}, then no restrictions will
* be placed on who can access the object. * be placed on who can access the object.
* *
* @param object the object to be guarded. * @param object the object to be guarded.

105
src/java.base/share/classes/java/security/Identity.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -34,17 +34,17 @@ import java.util.*;
* their public keys. Identities may also be more abstract (or concrete) * their public keys. Identities may also be more abstract (or concrete)
* constructs, such as daemon threads or smart cards. * constructs, such as daemon threads or smart cards.
* *
* <p>All Identity objects have a name and a public key. Names are * <p>All {@code Identity} objects have a name and a public key. Names are
* immutable. Identities may also be scoped. That is, if an Identity is * immutable. Identities may also be scoped. That is, if an {@code Identity} is
* specified to have a particular scope, then the name and public * specified to have a particular scope, then the name and public
* key of the Identity are unique within that scope. * key of the {@code Identity} are unique within that scope.
* *
* <p>An Identity also has a set of certificates (all certifying its own * <p>An {@code Identity} also has a set of certificates (all certifying its own
* public key). The Principal names specified in these certificates need * public key). The Principal names specified in these certificates need
* not be the same, only the key. * not be the same, only the key.
* *
* <p>An Identity can be subclassed, to include postal and email addresses, * <p>An {@code Identity} can be subclassed, to include postal and email
* telephone numbers, images of faces and logos, and so on. * addresses, telephone numbers, images of faces and logos, and so on.
* *
* @see IdentityScope * @see IdentityScope
* @see Signer * @see Signer
@ -66,35 +66,35 @@ public abstract class Identity implements Principal, Serializable {
private static final long serialVersionUID = 3609922007826600659L; private static final long serialVersionUID = 3609922007826600659L;
/** /**
* The name for this identity. * The name for this {@code Identity}.
* *
* @serial * @serial
*/ */
private String name; private String name;
/** /**
* The public key for this identity. * The public key for this {@code Identity}.
* *
* @serial * @serial
*/ */
private PublicKey publicKey; private PublicKey publicKey;
/** /**
* Generic, descriptive information about the identity. * Generic, descriptive information about the {@code Identity}.
* *
* @serial * @serial
*/ */
String info = "No further information available."; String info = "No further information available.";
/** /**
* The scope of the identity. * The scope of the {@code Identity}.
* *
* @serial * @serial
*/ */
IdentityScope scope; IdentityScope scope;
/** /**
* The certificates for this identity. * The certificates for this {@code Identity}.
* *
* @serial * @serial
*/ */
@ -108,12 +108,12 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Constructs an identity with the specified name and scope. * Constructs an {@code Identity} with the specified name and scope.
* *
* @param name the identity name. * @param name the {@code Identity} name.
* @param scope the scope of the identity. * @param scope the scope of the {@code Identity}.
* *
* @throws KeyManagementException if there is already an identity * @throws KeyManagementException if there is already an {@code Identity}
* with the same name in the scope. * with the same name in the scope.
*/ */
public Identity(String name, IdentityScope scope) throws public Identity(String name, IdentityScope scope) throws
@ -126,7 +126,7 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Constructs an identity with the specified name and no scope. * Constructs an {@code Identity} with the specified name and no scope.
* *
* @param name the identity name. * @param name the identity name.
*/ */
@ -137,7 +137,7 @@ public abstract class Identity implements Principal, Serializable {
/** /**
* Returns this identity's name. * Returns this identity's name.
* *
* @return the name of this identity. * @return the name of this {@code Identity}.
*/ */
public final String getName() { public final String getName() {
return name; return name;
@ -146,7 +146,7 @@ public abstract class Identity implements Principal, Serializable {
/** /**
* Returns this identity's scope. * Returns this identity's scope.
* *
* @return the scope of this identity. * @return the scope of this {@code Identity}.
*/ */
public final IdentityScope getScope() { public final IdentityScope getScope() {
return scope; return scope;
@ -155,7 +155,7 @@ public abstract class Identity implements Principal, Serializable {
/** /**
* Returns this identity's public key. * Returns this identity's public key.
* *
* @return the public key for this identity. * @return the public key for this {@code Identity}.
* *
* @see #setPublicKey * @see #setPublicKey
*/ */
@ -171,7 +171,7 @@ public abstract class Identity implements Principal, Serializable {
* method is called with {@code "setIdentityPublicKey"} * method is called with {@code "setIdentityPublicKey"}
* as its argument to see if it's ok to set the public key. * as its argument to see if it's ok to set the public key.
* *
* @param key the public key for this identity. * @param key the public key for this {@code Identity}.
* *
* @throws KeyManagementException if another identity in the * @throws KeyManagementException if another identity in the
* identity's scope has the same public key, or if another exception occurs. * identity's scope has the same public key, or if another exception occurs.
@ -192,7 +192,7 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Specifies a general information string for this identity. * Specifies a general information string for this {@code Identity}.
* *
* <p>First, if there is a security manager, its {@code checkSecurityAccess} * <p>First, if there is a security manager, its {@code checkSecurityAccess}
* method is called with {@code "setIdentityInfo"} * method is called with {@code "setIdentityInfo"}
@ -213,9 +213,9 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Returns general information previously specified for this identity. * Returns general information previously specified for this {@code Identity}.
* *
* @return general information about this identity. * @return general information about this {@code Identity}.
* *
* @see #setInfo * @see #setInfo
*/ */
@ -224,9 +224,9 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Adds a certificate for this identity. If the identity has a public * Adds a certificate for this {@code Identity}. If the {@code Identity} has a public
* key, the public key in the certificate must be the same, and if * key, the public key in the certificate must be the same, and if
* the identity does not have a public key, the identity's * the {@code Identity} does not have a public key, the identity's
* public key is set to be that specified in the certificate. * public key is set to be that specified in the certificate.
* *
* <p>First, if there is a security manager, its {@code checkSecurityAccess} * <p>First, if there is a security manager, its {@code checkSecurityAccess}
@ -278,7 +278,7 @@ public abstract class Identity implements Principal, Serializable {
/** /**
* Removes a certificate from this identity. * Removes a certificate from this {@code Identity}.
* *
* <p>First, if there is a security manager, its {@code checkSecurityAccess} * <p>First, if there is a security manager, its {@code checkSecurityAccess}
* method is called with {@code "removeIdentityCertificate"} * method is called with {@code "removeIdentityCertificate"}
@ -304,9 +304,9 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Returns a copy of all the certificates for this identity. * Returns a copy of all the certificates for this {@code Identity}.
* *
* @return a copy of all the certificates for this identity. * @return a copy of all the certificates for this {@code Identity}.
*/ */
public Certificate[] certificates() { public Certificate[] certificates() {
if (certificates == null) { if (certificates == null) {
@ -319,17 +319,20 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Tests for equality between the specified object and this identity. * Tests for equality between the specified object and this
* {@code Identity}.
* This first tests to see if the entities actually refer to the same * 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 * object, in which case it returns {@code true}. Next, it checks to see if
* the entities have the same name and the same scope. If they do, * the entities have the same name and the same scope. If they do,
* the method returns true. Otherwise, it calls * the method returns {@code true}. Otherwise, it calls
* {@link #identityEquals(Identity) identityEquals}, which subclasses should * {@link #identityEquals(Identity) identityEquals}, which subclasses should
* override. * override.
* *
* @param identity the object to test for equality with this identity. * @param identity the object to test for equality with this
* {@code Identity}.
* *
* @return true if the objects are considered equal, false otherwise. * @return {@code true} if the objects are considered equal,
* {@code false} otherwise.
* *
* @see #identityEquals * @see #identityEquals
*/ */
@ -343,15 +346,17 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Tests for equality between the specified identity and this identity. * Tests for equality between the specified {@code Identity} and this
* {@code Identity}.
* This method should be overridden by subclasses to test for equality. * This method should be overridden by subclasses to test for equality.
* The default behavior is to return true if the names and public keys * The default behavior is to return {@code true} if the names and public
* are equal. * keys are equal.
* *
* @param identity the identity to test for equality with this identity. * @param identity the identity to test for equality with this
* {@code identity}.
* *
* @return true if the identities are considered equal, false * @return {@code true} if the identities are considered equal,
* otherwise. * {@code false} otherwise.
* *
* @see #equals * @see #equals
*/ */
@ -371,7 +376,7 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Returns a parsable name for identity: identityName.scopeName * Returns a parsable name for {@code Identity}: identityName.scopeName
*/ */
String fullName() { String fullName() {
String parsable = name; String parsable = name;
@ -382,19 +387,19 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Returns a short string describing this identity, telling its * Returns a short string describing this {@code Identity}, telling its
* name and its scope (if any). * name and its scope (if any).
* *
* <p>First, if there is a security manager, its {@code checkSecurityAccess} * <p>First, if there is a security manager, its {@code checkSecurityAccess}
* method is called with {@code "printIdentity"} * method is called with {@code "printIdentity"}
* as its argument to see if it's ok to return the string. * as its argument to see if it's ok to return the string.
* *
* @return information about this identity, such as its name and the * @return information about this {@code Identity}, such as its name and the
* name of its scope (if any). * name of its scope (if any).
* *
* @throws SecurityException if a security manager exists and its * @throws SecurityException if a security manager exists and its
* {@code checkSecurityAccess} method doesn't allow * {@code checkSecurityAccess} method doesn't allow
* returning a string describing this identity. * returning a string describing this {@code Identity}.
* *
* @see SecurityManager#checkSecurityAccess * @see SecurityManager#checkSecurityAccess
*/ */
@ -408,7 +413,7 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Returns a string representation of this identity, with * Returns a string representation of this {@code Identity}, with
* optionally more details than that provided by the * optionally more details than that provided by the
* {@code toString} method without any arguments. * {@code toString} method without any arguments.
* *
@ -418,13 +423,13 @@ public abstract class Identity implements Principal, Serializable {
* *
* @param detailed whether or not to provide detailed information. * @param detailed whether or not to provide detailed information.
* *
* @return information about this identity. If {@code detailed} * @return information about this {@code Identity}. If {@code detailed}
* is true, then this method returns more information than that * is {@code true}, then this method returns more information than that
* provided by the {@code toString} method without any arguments. * provided by the {@code toString} method without any arguments.
* *
* @throws SecurityException if a security manager exists and its * @throws SecurityException if a security manager exists and its
* {@code checkSecurityAccess} method doesn't allow * {@code checkSecurityAccess} method doesn't allow
* returning a string describing this identity. * returning a string describing this {@code Identity}.
* *
* @see #toString * @see #toString
* @see SecurityManager#checkSecurityAccess * @see SecurityManager#checkSecurityAccess
@ -473,9 +478,9 @@ public abstract class Identity implements Principal, Serializable {
} }
/** /**
* Returns a hashcode for this identity. * Returns a hashcode for this {@code Identity}.
* *
* @return a hashcode for this identity. * @return a hashcode for this {@code Identity}.
*/ */
public int hashCode() { public int hashCode() {
return name.hashCode(); return name.hashCode();

44
src/java.base/share/classes/java/security/IdentityScope.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -34,10 +34,10 @@ import java.util.Properties;
* itself, and therefore has a name and can have a scope. It can also * itself, and therefore has a name and can have a scope. It can also
* optionally have a public key and associated certificates. * optionally have a public key and associated certificates.
* *
* <p>An IdentityScope can contain Identity objects of all kinds, including * <p>An {@code IdentityScope} can contain {@code Identity} objects of all
* Signers. All types of Identity objects can be retrieved, added, and * kinds, including signers. All types of {@code Identity} objects can be
* removed using the same methods. Note that it is possible, and in fact * retrieved, added, and removed using the same methods. Note that it is
* expected, that different types of identity scopes will * possible, and in fact expected, that different types of identity scopes will
* apply different policies for their various operations on the * apply different policies for their various operations on the
* various types of Identities. * various types of Identities.
* *
@ -121,7 +121,7 @@ class IdentityScope extends Identity {
* @param name the scope name. * @param name the scope name.
* @param scope the scope for the new identity scope. * @param scope the scope for the new identity scope.
* *
* @throws KeyManagementException if there is already an identity * @throws KeyManagementException if there is already an {@code Identity}
* with the same name in the scope. * with the same name in the scope.
*/ */
public IdentityScope(String name, IdentityScope scope) public IdentityScope(String name, IdentityScope scope)
@ -175,24 +175,26 @@ class IdentityScope extends Identity {
public abstract int size(); public abstract int size();
/** /**
* Returns the identity in this scope with the specified name (if any). * Returns the {@code Identity} in this scope with the specified
* name (if any).
* *
* @param name the name of the identity to be retrieved. * @param name the name of the {@code Identity} to be retrieved.
* *
* @return the identity named {@code name}, or null if there are * @return the {@code Identity} named {@code name}, or {@code null}
* no identities named {@code name} in this scope. * if there are no identities named {@code name} in this scope.
*/ */
public abstract Identity getIdentity(String name); public abstract Identity getIdentity(String name);
/** /**
* Retrieves the identity whose name is the same as that of the * Retrieves the {@code Identity} whose name is the same as that of the
* specified principal. (Note: Identity implements Principal.) * specified principal. (Note: {@code Identity} implements
* {@code Principal}.)
* *
* @param principal the principal corresponding to the identity * @param principal the principal corresponding to the {@code Identity}
* to be retrieved. * to be retrieved.
* *
* @return the identity whose name is the same as that of the * @return the {@code Identity} whose name is the same as that of the
* principal, or null if there are no identities of the same name * principal, or {@code null} if there are no identities of the same name
* in this scope. * in this scope.
*/ */
public Identity getIdentity(Principal principal) { public Identity getIdentity(Principal principal) {
@ -200,19 +202,19 @@ class IdentityScope extends Identity {
} }
/** /**
* Retrieves the identity with the specified public key. * Retrieves the {@code identity} with the specified public key.
* *
* @param key the public key for the identity to be returned. * @param key the public key for the identity to be returned.
* *
* @return the identity with the given key, or null if there are * @return the identity with the given key, or {@code null} if there are
* no identities in this scope with that key. * no identities in this scope with that key.
*/ */
public abstract Identity getIdentity(PublicKey key); public abstract Identity getIdentity(PublicKey key);
/** /**
* Adds an identity to this identity scope. * Adds an {@code Identity} to this identity scope.
* *
* @param identity the identity to be added. * @param identity the {@code Identity} to be added.
* *
* @throws KeyManagementException if the identity is not * @throws KeyManagementException if the identity is not
* valid, a name conflict occurs, another identity has the same * valid, a name conflict occurs, another identity has the same
@ -222,9 +224,9 @@ class IdentityScope extends Identity {
throws KeyManagementException; throws KeyManagementException;
/** /**
* Removes an identity from this identity scope. * Removes an {@code Identity} from this identity scope.
* *
* @param identity the identity to be removed. * @param identity the {@code Identity} to be removed.
* *
* @throws KeyManagementException if the identity is missing, * @throws KeyManagementException if the identity is missing,
* or another exception occurs. * or another exception occurs.

12
src/java.base/share/classes/java/security/InvalidAlgorithmParameterException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1922, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -44,9 +44,9 @@ extends GeneralSecurityException {
private static final long serialVersionUID = 2864672297499471472L; private static final long serialVersionUID = 2864672297499471472L;
/** /**
* Constructs an InvalidAlgorithmParameterException with no detail * Constructs an {@code InvalidAlgorithmParameterException} with no detail
* message. * message.
* A detail message is a String that describes this particular * A detail message is a {@code String} that describes this particular
* exception. * exception.
*/ */
public InvalidAlgorithmParameterException() { public InvalidAlgorithmParameterException() {
@ -54,9 +54,9 @@ extends GeneralSecurityException {
} }
/** /**
* Constructs an InvalidAlgorithmParameterException with the specified * Constructs an {@code InvalidAlgorithmParameterException} with the
* detail message. * specified detail message.
* A detail message is a String that describes this * A detail message is a {@code String} that describes this
* particular exception. * particular exception.
* *
* @param msg the detail message. * @param msg the detail message.

8
src/java.base/share/classes/java/security/InvalidKeyException.java
View file

@ -40,8 +40,8 @@ public class InvalidKeyException extends KeyException {
private static final long serialVersionUID = 5698479920593359816L; private static final long serialVersionUID = 5698479920593359816L;
/** /**
* Constructs an InvalidKeyException with no detail message. A * Constructs an {@code InvalidKeyException} with no detail message. A
* detail message is a String that describes this particular * detail message is a {@code String} that describes this particular
* exception. * exception.
*/ */
public InvalidKeyException() { public InvalidKeyException() {
@ -49,8 +49,8 @@ public class InvalidKeyException extends KeyException {
} }
/** /**
* Constructs an InvalidKeyException with the specified detail * Constructs an {@code InvalidKeyException} with the specified detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
* *
* @param msg the detail message. * @param msg the detail message.

10
src/java.base/share/classes/java/security/InvalidParameterException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -40,8 +40,8 @@ public class InvalidParameterException extends IllegalArgumentException {
private static final long serialVersionUID = -857968536935667808L; private static final long serialVersionUID = -857968536935667808L;
/** /**
* Constructs an InvalidParameterException with no detail message. * Constructs an {@code InvalidParameterException} with no detail message.
* A detail message is a String that describes this particular * A detail message is a {@code String} that describes this particular
* exception. * exception.
*/ */
public InvalidParameterException() { public InvalidParameterException() {
@ -49,8 +49,8 @@ public class InvalidParameterException extends IllegalArgumentException {
} }
/** /**
* Constructs an InvalidParameterException with the specified * Constructs an {@code InvalidParameterException} with the specified
* detail message. A detail message is a String that describes * detail message. A detail message is a {@code String} that describes
* this particular exception. * this particular exception.
* *
* @param msg the detail message. * @param msg the detail message.

10
src/java.base/share/classes/java/security/Key.java
View file

@ -26,8 +26,8 @@
package java.security; package java.security;
/** /**
* The Key interface is the top-level interface for all keys. It * The {@code Key} interface is the top-level interface for all keys. It
* defines the functionality shared by all key objects. All keys * defines the functionality shared by all {@code Key} objects. All keys
* have three characteristics: * have three characteristics:
* *
* <UL> * <UL>
@ -130,7 +130,7 @@ public interface Key extends java.io.Serializable {
/** /**
* Returns the name of the primary encoding format of this key, * Returns the name of the primary encoding format of this key,
* or null if this key does not support encoding. * or {@code null} if this key does not support encoding.
* The primary encoding format is * The primary encoding format is
* named in terms of the appropriate ASN.1 data format, if an * named in terms of the appropriate ASN.1 data format, if an
* ASN.1 specification for this key exists. * ASN.1 specification for this key exists.
@ -148,10 +148,10 @@ public interface Key extends java.io.Serializable {
String getFormat(); String getFormat();
/** /**
* Returns the key in its primary encoding format, or null * Returns the key in its primary encoding format, or {@code null}
* if this key does not support encoding. * if this key does not support encoding.
* *
* @return the encoded key, or null if the key does not support * @return the encoded key, or {@code null} if the key does not support
* encoding. * encoding.
*/ */
byte[] getEncoded(); byte[] getEncoded();

10
src/java.base/share/classes/java/security/KeyException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -42,16 +42,16 @@ public class KeyException extends GeneralSecurityException {
private static final long serialVersionUID = -7483676942812432108L; private static final long serialVersionUID = -7483676942812432108L;
/** /**
* Constructs a KeyException with no detail message. A detail * Constructs a {@code KeyException} with no detail message. A detail
* message is a String that describes this particular exception. * message is a {@code String} that describes this particular exception.
*/ */
public KeyException() { public KeyException() {
super(); super();
} }
/** /**
* Constructs a KeyException with the specified detail message. * Constructs a {@code KeyException} with the specified detail message.
* A detail message is a String that describes this particular * A detail message is a {@code String} that describes this particular
* exception. * exception.
* *
* @param msg the detail message. * @param msg the detail message.

34
src/java.base/share/classes/java/security/KeyFactory.java
View file

@ -115,7 +115,7 @@ public class KeyFactory {
private Iterator<Service> serviceIterator; private Iterator<Service> serviceIterator;
/** /**
* Creates a KeyFactory object. * Creates a {@code KeyFactory} object.
* *
* @param keyFacSpi the delegate * @param keyFacSpi the delegate
* @param provider the provider * @param provider the provider
@ -141,14 +141,14 @@ public class KeyFactory {
} }
/** /**
* Returns a KeyFactory object that converts * Returns a {@code KeyFactory} object that converts
* public/private keys of the specified algorithm. * public/private keys of the specified algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new KeyFactory object encapsulating the * A new {@code KeyFactory} object encapsulating the
* KeyFactorySpi implementation from the first * {@code KeyFactorySpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -184,11 +184,11 @@ public class KeyFactory {
} }
/** /**
* Returns a KeyFactory object that converts * Returns a {@code KeyFactory} object that converts
* public/private keys of the specified algorithm. * public/private keys of the specified algorithm.
* *
* <p> A new KeyFactory object encapsulating the * <p> A new {@code KeyFactory} object encapsulating the
* KeyFactorySpi implementation from the specified provider * {@code KeyFactorySpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -229,13 +229,13 @@ public class KeyFactory {
} }
/** /**
* Returns a KeyFactory object that converts * Returns a {@code KeyFactory} object that converts
* public/private keys of the specified algorithm. * public/private keys of the specified algorithm.
* *
* <p> A new KeyFactory object encapsulating the * <p> A new {@code KeyFactory} object encapsulating the
* KeyFactorySpi implementation from the specified Provider * {@code KeyFactorySpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * is returned. Note that the specified provider does not
* does not have to be registered in the provider list. * have to be registered in the provider list.
* *
* @param algorithm the name of the requested key algorithm. * @param algorithm the name of the requested key algorithm.
* See the KeyFactory section in the <a href= * See the KeyFactory section in the <a href=
@ -294,10 +294,10 @@ public class KeyFactory {
} }
/** /**
* Update the active KeyFactorySpi of this class and return the next * Update the active {@code KeyFactorySpi} of this class and return the next
* implementation for failover. If no more implementations are * implementation for failover. If no more implementations are
* available, this method returns null. However, the active spi of * available, this method returns null. However, the active spi of
* this class is never set to null. * this class is never set to {@code null}.
*/ */
private KeyFactorySpi nextSpi(KeyFactorySpi oldSpi) { private KeyFactorySpi nextSpi(KeyFactorySpi oldSpi) {
synchronized (lock) { synchronized (lock) {

12
src/java.base/share/classes/java/security/KeyManagementException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -28,7 +28,7 @@ package java.security;
/** /**
* This is the general key management exception for all operations * This is the general key management exception for all operations
* dealing with key management. Examples of subclasses of * dealing with key management. Examples of subclasses of
* KeyManagementException that developers might create for * {@code KeyManagementException} that developers might create for
* giving more detailed information could include: * giving more detailed information could include:
* *
* <ul> * <ul>
@ -50,8 +50,8 @@ public class KeyManagementException extends KeyException {
private static final long serialVersionUID = 947674216157062695L; private static final long serialVersionUID = 947674216157062695L;
/** /**
* Constructs a KeyManagementException with no detail message. A * Constructs a {@code KeyManagementException} with no detail message. A
* detail message is a String that describes this particular * detail message is a {@code String} that describes this particular
* exception. * exception.
*/ */
public KeyManagementException() { public KeyManagementException() {
@ -59,8 +59,8 @@ public class KeyManagementException extends KeyException {
} }
/** /**
* Constructs a KeyManagementException with the specified detail * Constructs a {@code KeyManagementException} with the specified detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
* *
* @param msg the detail message. * @param msg the detail message.

57
src/java.base/share/classes/java/security/KeyPairGenerator.java
View file

@ -36,7 +36,7 @@ import sun.security.jca.GetInstance.Instance;
import sun.security.util.Debug; import sun.security.util.Debug;
/** /**
* The KeyPairGenerator class is used to generate pairs of * The {@code KeyPairGenerator} class is used to generate pairs of
* public and private keys. Key pair generators are constructed using the * public and private keys. Key pair generators are constructed using the
* {@code getInstance} factory methods (static methods that * {@code getInstance} factory methods (static methods that
* return instances of a given class). * return instances of a given class).
@ -57,7 +57,7 @@ import sun.security.util.Debug;
* corresponds to the length of the modulus). * corresponds to the length of the modulus).
* There is an * There is an
* {@link #initialize(int, java.security.SecureRandom) initialize} * {@link #initialize(int, java.security.SecureRandom) initialize}
* method in this KeyPairGenerator class that takes these two universally * method in this {@code KeyPairGenerator} class that takes these two universally
* shared types of arguments. There is also one that takes just a * shared types of arguments. There is also one that takes just a
* {@code keysize} argument, and uses the {@code SecureRandom} * {@code keysize} argument, and uses the {@code SecureRandom}
* implementation of the highest-priority installed provider as the source * implementation of the highest-priority installed provider as the source
@ -92,17 +92,18 @@ import sun.security.util.Debug;
* used.) * used.)
* </ul> * </ul>
* *
* <p>In case the client does not explicitly initialize the KeyPairGenerator * <p>In case the client does not explicitly initialize the
* {@code KeyPairGenerator}
* (via a call to an {@code initialize} method), each provider must * (via a call to an {@code initialize} method), each provider must
* supply (and document) a default initialization. * supply (and document) a default initialization.
* See the Keysize Restriction sections of the * See the Keysize Restriction sections of the
* {@extLink security_guide_jdk_providers JDK Providers} * {@extLink security_guide_jdk_providers JDK Providers}
* document for information on the KeyPairGenerator defaults used by * document for information on the {@code KeyPairGenerator} defaults used by
* JDK providers. * JDK providers.
* However, note that defaults may vary across different providers. * However, note that defaults may vary across different providers.
* Additionally, the default value for a provider may change in a future * Additionally, the default value for a provider may change in a future
* version. Therefore, it is recommended to explicitly initialize the * version. Therefore, it is recommended to explicitly initialize the
* KeyPairGenerator instead of relying on provider-specific defaults. * {@code KeyPairGenerator} instead of relying on provider-specific defaults.
* *
* <p>Note that this class is abstract and extends from * <p>Note that this class is abstract and extends from
* {@code KeyPairGeneratorSpi} for historical reasons. * {@code KeyPairGeneratorSpi} for historical reasons.
@ -145,7 +146,7 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
Provider provider; Provider provider;
/** /**
* Creates a KeyPairGenerator object for the specified algorithm. * Creates a {@code KeyPairGenerator} object for the specified algorithm.
* *
* @param algorithm the standard string name of the algorithm. * @param algorithm the standard string name of the algorithm.
* See the KeyPairGenerator section in the <a href= * See the KeyPairGenerator section in the <a href=
@ -190,14 +191,14 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
} }
/** /**
* Returns a KeyPairGenerator object that generates public/private * Returns a {@code KeyPairGenerator} object that generates public/private
* key pairs for the specified algorithm. * key pairs for the specified algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security Providers,
* starting with the most preferred Provider. * starting with the most preferred Provider.
* A new KeyPairGenerator object encapsulating the * A new {@code KeyPairGenerator} object encapsulating the
* KeyPairGeneratorSpi implementation from the first * {@code KeyPairGeneratorSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -258,11 +259,11 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
} }
/** /**
* Returns a KeyPairGenerator object that generates public/private * Returns a {@code KeyPairGenerator} object that generates public/private
* key pairs for the specified algorithm. * key pairs for the specified algorithm.
* *
* <p> A new KeyPairGenerator object encapsulating the * <p> A new {@code KeyPairGenerator} object encapsulating the
* KeyPairGeneratorSpi implementation from the specified provider * {@code KeyPairGeneratorSpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -303,13 +304,13 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
} }
/** /**
* Returns a KeyPairGenerator object that generates public/private * Returns a {@code KeyPairGenerator} object that generates public/private
* key pairs for the specified algorithm. * key pairs for the specified algorithm.
* *
* <p> A new KeyPairGenerator object encapsulating the * <p> A new {@code KeyPairGenerator} object encapsulating the
* KeyPairGeneratorSpi implementation from the specified Provider * {@code KeyPairGeneratorSpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * is returned. Note that the specified provider does not
* does not have to be registered in the provider list. * have to be registered in the provider list.
* *
* @param algorithm the standard string name of the algorithm. * @param algorithm the standard string name of the algorithm.
* See the KeyPairGenerator section in the <a href= * See the KeyPairGenerator section in the <a href=
@ -370,7 +371,7 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
* number of bits. * number of bits.
* *
* @throws InvalidParameterException if the {@code keysize} is not * @throws InvalidParameterException if the {@code keysize} is not
* supported by this KeyPairGenerator object. * supported by this {@code KeyPairGenerator} object.
*/ */
public void initialize(int keysize) { public void initialize(int keysize) {
initialize(keysize, JCAUtil.getDefSecureRandom()); initialize(keysize, JCAUtil.getDefSecureRandom());
@ -386,7 +387,7 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
* @param random the source of randomness. * @param random the source of randomness.
* *
* @throws InvalidParameterException if the {@code keysize} is not * @throws InvalidParameterException if the {@code keysize} is not
* supported by this KeyPairGenerator object. * supported by this {@code KeyPairGenerator} object.
* *
* @since 1.2 * @since 1.2
*/ */
@ -422,8 +423,8 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
* from the highest-priority installed provider or system-provided if none * from the highest-priority installed provider or system-provided if none
* of the installed providers supply one). * of the installed providers supply one).
* That {@code initialize} method always throws an * That {@code initialize} method always throws an
* UnsupportedOperationException if it is not overridden by the provider. * {@code UnsupportedOperationException} if it is not overridden
* * by the provider.
* @param params the parameter set used to generate the keys. * @param params the parameter set used to generate the keys.
* *
* @throws InvalidAlgorithmParameterException if the given parameters * @throws InvalidAlgorithmParameterException if the given parameters
@ -448,8 +449,8 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
* java.security.SecureRandom) initialize} method, * java.security.SecureRandom) initialize} method,
* passing it {@code params} and {@code random}. * passing it {@code params} and {@code random}.
* That {@code initialize} * That {@code initialize}
* method always throws an * method always throws an {@code UnsupportedOperationException}
* UnsupportedOperationException if it is not overridden by the provider. * if it is not overridden by the provider.
* *
* @param params the parameter set used to generate the keys. * @param params the parameter set used to generate the keys.
* @param random the source of randomness. * @param random the source of randomness.
@ -478,7 +479,7 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
/** /**
* Generates a key pair. * Generates a key pair.
* *
* <p>If this KeyPairGenerator has not been initialized explicitly, * <p>If this {@code KeyPairGenerator} has not been initialized explicitly,
* provider-specific defaults will be used for the size and other * provider-specific defaults will be used for the size and other
* (algorithm-specific) values of the generated keys. * (algorithm-specific) values of the generated keys.
* *
@ -498,7 +499,7 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
/** /**
* Generates a key pair. * Generates a key pair.
* *
* <p>If this KeyPairGenerator has not been initialized explicitly, * <p>If this {@code KeyPairGenerator} has not been initialized explicitly,
* provider-specific defaults will be used for the size and other * provider-specific defaults will be used for the size and other
* (algorithm-specific) values of the generated keys. * (algorithm-specific) values of the generated keys.
* *
@ -604,8 +605,8 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
/** /**
* Update the active spi of this class and return the next * Update the active spi of this class and return the next
* implementation for failover. If no more implementations are * implementation for failover. If no more implementations are
* available, this method returns null. However, the active spi of * available, this method returns {@code null}. However, the
* this class is never set to null. * active spi of this class is never set to {@code null}.
*/ */
private KeyPairGeneratorSpi nextSpi(KeyPairGeneratorSpi oldSpi, private KeyPairGeneratorSpi nextSpi(KeyPairGeneratorSpi oldSpi,
boolean reinit) { boolean reinit) {

16
src/java.base/share/classes/java/security/KeyPairGeneratorSpi.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -36,9 +36,9 @@ import java.security.spec.AlgorithmParameterSpec;
* cryptographic service provider who wishes to supply the implementation * cryptographic service provider who wishes to supply the implementation
* of a key pair generator for a particular algorithm. * of a key pair generator for a particular algorithm.
* *
* <p> In case the client does not explicitly initialize the KeyPairGenerator * <p> In case the client does not explicitly initialize the
* (via a call to an {@code initialize} method), each provider must * {@code KeyPairGenerator} (via a call to an {@code initialize} method),
* supply (and document) a default initialization. * each provider must supply (and document) a default initialization.
* See the Keysize Restriction sections of the * See the Keysize Restriction sections of the
* {@extLink security_guide_jdk_providers JDK Providers} * {@extLink security_guide_jdk_providers JDK Providers}
* document for information on the KeyPairGenerator defaults used by * document for information on the KeyPairGenerator defaults used by
@ -46,7 +46,7 @@ import java.security.spec.AlgorithmParameterSpec;
* However, note that defaults may vary across different providers. * However, note that defaults may vary across different providers.
* Additionally, the default value for a provider may change in a future * Additionally, the default value for a provider may change in a future
* version. Therefore, it is recommended to explicitly initialize the * version. Therefore, it is recommended to explicitly initialize the
* KeyPairGenerator instead of relying on provider-specific defaults. * {@code KeyPairGenerator} instead of relying on provider-specific defaults.
* *
* @author Benjamin Renaud * @author Benjamin Renaud
* @since 1.2 * @since 1.2
@ -74,7 +74,7 @@ public abstract class KeyPairGeneratorSpi {
* @param random the source of randomness for this generator. * @param random the source of randomness for this generator.
* *
* @throws InvalidParameterException if the {@code keysize} is not * @throws InvalidParameterException if the {@code keysize} is not
* supported by this KeyPairGeneratorSpi object. * supported by this {@code KeyPairGeneratorSpi} object.
*/ */
public abstract void initialize(int keysize, SecureRandom random); public abstract void initialize(int keysize, SecureRandom random);
@ -86,10 +86,10 @@ public abstract class KeyPairGeneratorSpi {
* abstract class. (For backwards compatibility, it cannot be abstract.) * abstract class. (For backwards compatibility, it cannot be abstract.)
* It may be overridden by a provider to initialize the key pair * It may be overridden by a provider to initialize the key pair
* generator. Such an override * generator. Such an override
* is expected to throw an InvalidAlgorithmParameterException if * is expected to throw an {@code InvalidAlgorithmParameterException} if
* a parameter is inappropriate for this key pair generator. * a parameter is inappropriate for this key pair generator.
* If this method is not overridden, it always throws an * If this method is not overridden, it always throws an
* UnsupportedOperationException. * {@code UnsupportedOperationException}.
* *
* @param params the parameter set used to generate the keys. * @param params the parameter set used to generate the keys.
* *

213
src/java.base/share/classes/java/security/KeyStore.java
View file

@ -90,7 +90,7 @@ import sun.security.util.Debug;
* (SafeKeyper) are one option, and simpler mechanisms such as files may also * (SafeKeyper) are one option, and simpler mechanisms such as files may also
* be used (in a variety of formats). * be used (in a variety of formats).
* *
* <p> Typical ways to request a KeyStore object include * <p> Typical ways to request a {@code KeyStore} object include
* specifying an existing keystore file, * specifying an existing keystore file,
* relying on the default type and providing a specific keystore type. * relying on the default type and providing a specific keystore type.
* *
@ -235,7 +235,7 @@ public class KeyStore {
/** /**
* Gets the parameter used to protect keystore data. * Gets the parameter used to protect keystore data.
* *
* @return the parameter used to protect keystore data, or null * @return the parameter used to protect keystore data, or {@code null}
*/ */
ProtectionParameter getProtectionParameter(); ProtectionParameter getProtectionParameter();
} }
@ -373,7 +373,8 @@ public class KeyStore {
/** /**
* Determines if password has been cleared. * Determines if password has been cleared.
* *
* @return true if the password has been cleared, false otherwise * @return {@code true} if the password has been cleared,
* {@code false} otherwise
*/ */
public synchronized boolean isDestroyed() { public synchronized boolean isDestroyed() {
return destroyed; return destroyed;
@ -381,7 +382,7 @@ public class KeyStore {
} }
/** /**
* A ProtectionParameter encapsulating a CallbackHandler. * A {@code ProtectionParameter} encapsulating a CallbackHandler.
* *
* @since 1.5 * @since 1.5
*/ */
@ -395,7 +396,7 @@ public class KeyStore {
* CallbackHandler. * CallbackHandler.
* *
* @param handler the CallbackHandler * @param handler the CallbackHandler
* @throws NullPointerException if handler is null * @throws NullPointerException if handler is {@code null}
*/ */
public CallbackHandlerProtection(CallbackHandler handler) { public CallbackHandlerProtection(CallbackHandler handler) {
if (handler == null) { if (handler == null) {
@ -802,8 +803,8 @@ public class KeyStore {
} }
/** /**
* Creates a KeyStore object of the given type, and encapsulates the given * Creates a {@code KeyStore} object of the given type, and encapsulates
* provider implementation (SPI object) in it. * the given provider implementation (SPI object) in it.
* *
* @param keyStoreSpi the provider implementation. * @param keyStoreSpi the provider implementation.
* @param provider the provider. * @param provider the provider.
@ -826,13 +827,13 @@ public class KeyStore {
} }
/** /**
* Returns a keystore object of the specified type. * Returns a {@code KeyStore} object of the specified type.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new KeyStore object encapsulating the * A new {@code KeyStore} object encapsulating the
* KeyStoreSpi implementation from the first * {@code KeyStoreSpi} implementation from the first
* Provider that supports the specified type is returned. * provider that supports the specified type is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -853,7 +854,7 @@ public class KeyStore {
* *
* @return a keystore object of the specified type * @return a keystore object of the specified type
* *
* @throws KeyStoreException if no {@code Provider} supports a * @throws KeyStoreException if no provider supports a
* {@code KeyStoreSpi} implementation for the * {@code KeyStoreSpi} implementation for the
* specified type * specified type
* *
@ -874,10 +875,10 @@ public class KeyStore {
} }
/** /**
* Returns a keystore object of the specified type. * Returns a {@code KeyStore} object of the specified type.
* *
* <p> A new KeyStore object encapsulating the * <p> A new {@code KeyStore} object encapsulating the
* KeyStoreSpi implementation from the specified provider * {@code KeyStoreSpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -923,11 +924,11 @@ public class KeyStore {
} }
/** /**
* Returns a keystore object of the specified type. * Returns a {@code KeyStore} object of the specified type.
* *
* <p> A new KeyStore object encapsulating the * <p> A new {@code KeyStore} object encapsulating the
* KeyStoreSpi implementation from the specified Provider * {@code KeyStoreSpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * object is returned. Note that the specified provider object
* does not have to be registered in the provider list. * does not have to be registered in the provider list.
* *
* @param type the type of keystore. * @param type the type of keystore.
@ -1054,8 +1055,8 @@ public class KeyStore {
* @param alias the alias name * @param alias the alias name
* @param password the password for recovering the key * @param password the password for recovering the key
* *
* @return the requested key, or null if the given alias does not exist * @return the requested key, or {@code null} if the given alias does
* or does not identify a key-related entry. * not exist or does not identify a key-related entry.
* *
* @throws KeyStoreException if the keystore has not been initialized * @throws KeyStoreException if the keystore has not been initialized
* (loaded). * (loaded).
@ -1084,8 +1085,8 @@ public class KeyStore {
* @param alias the alias name * @param alias the alias name
* *
* @return the certificate chain (ordered with the user's certificate first * @return the certificate chain (ordered with the user's certificate first
* followed by zero or more certificate authorities), or null if the given alias * followed by zero or more certificate authorities), or {@code null}
* does not exist or does not contain a certificate chain * if the given alias does not exist or does not contain a certificate chain
* *
* @throws KeyStoreException if the keystore has not been initialized * @throws KeyStoreException if the keystore has not been initialized
* (loaded). * (loaded).
@ -1117,8 +1118,8 @@ public class KeyStore {
* *
* @param alias the alias name * @param alias the alias name
* *
* @return the certificate, or null if the given alias does not exist or * @return the certificate, or {@code null} if the given alias does not
* does not contain a certificate. * exist or does not contain a certificate.
* *
* @throws KeyStoreException if the keystore has not been initialized * @throws KeyStoreException if the keystore has not been initialized
* (loaded). * (loaded).
@ -1137,8 +1138,8 @@ public class KeyStore {
* *
* @param alias the alias name * @param alias the alias name
* *
* @return the creation date of this entry, or null if the given alias does * @return the creation date of this entry, or {@code null} if the given
* not exist * alias does not exist
* *
* @throws KeyStoreException if the keystore has not been initialized * @throws KeyStoreException if the keystore has not been initialized
* (loaded). * (loaded).
@ -1291,7 +1292,7 @@ public class KeyStore {
* *
* @param alias the alias name * @param alias the alias name
* *
* @return true if the alias exists, false otherwise * @return {@code true} if the alias exists, {@code false} otherwise
* *
* @throws KeyStoreException if the keystore has not been initialized * @throws KeyStoreException if the keystore has not been initialized
* (loaded). * (loaded).
@ -1323,15 +1324,15 @@ public class KeyStore {
} }
/** /**
* Returns true if the entry identified by the given alias * Returns {@code true} if the entry identified by the given alias
* was created by a call to {@code setKeyEntry}, * was created by a call to {@code setKeyEntry},
* or created by a call to {@code setEntry} with a * or created by a call to {@code setEntry} with a
* {@code PrivateKeyEntry} or a {@code SecretKeyEntry}. * {@code PrivateKeyEntry} or a {@code SecretKeyEntry}.
* *
* @param alias the alias for the keystore entry to be checked * @param alias the alias for the keystore entry to be checked
* *
* @return true if the entry identified by the given alias is a * @return {@code true} if the entry identified by the given alias is a
* key-related entry, false otherwise. * key-related entry, {@code false} otherwise.
* *
* @throws KeyStoreException if the keystore has not been initialized * @throws KeyStoreException if the keystore has not been initialized
* (loaded). * (loaded).
@ -1346,15 +1347,15 @@ public class KeyStore {
} }
/** /**
* Returns true if the entry identified by the given alias * Returns {@code true} if the entry identified by the given alias
* was created by a call to {@code setCertificateEntry}, * was created by a call to {@code setCertificateEntry},
* or created by a call to {@code setEntry} with a * or created by a call to {@code setEntry} with a
* {@code TrustedCertificateEntry}. * {@code TrustedCertificateEntry}.
* *
* @param alias the alias for the keystore entry to be checked * @param alias the alias for the keystore entry to be checked
* *
* @return true if the entry identified by the given alias contains a * @return {@code true} if the entry identified by the given alias
* trusted certificate, false otherwise. * contains a trusted certificate, {@code false} otherwise.
* *
* @throws KeyStoreException if the keystore has not been initialized * @throws KeyStoreException if the keystore has not been initialized
* (loaded). * (loaded).
@ -1389,7 +1390,7 @@ public class KeyStore {
* @param cert the certificate to match with. * @param cert the certificate to match with.
* *
* @return the alias name of the first entry with a matching certificate, * @return the alias name of the first entry with a matching certificate,
* or null if no such entry exists in this keystore. * or {@code null} if no such entry exists in this keystore.
* *
* @throws KeyStoreException if the keystore has not been initialized * @throws KeyStoreException if the keystore has not been initialized
* (loaded). * (loaded).
@ -1461,7 +1462,7 @@ public class KeyStore {
} }
/** /**
* Loads this KeyStore from the given input stream. * Loads this keystore from the given input stream.
* *
* <p>A password may be given to unlock the keystore * <p>A password may be given to unlock the keystore
* (e.g. the keystore resides on a hardware token device), * (e.g. the keystore resides on a hardware token device),
@ -1503,7 +1504,7 @@ public class KeyStore {
/** /**
* Loads this keystore using the given {@code LoadStoreParameter}. * Loads this keystore using the given {@code LoadStoreParameter}.
* *
* <p> Note that if this KeyStore has already been loaded, it is * <p> Note that if this {@code KeyStore} has already been loaded, it is
* reinitialized and loaded again from the given parameter. * reinitialized and loaded again from the given parameter.
* *
* @param param the {@code LoadStoreParameter} * @param param the {@code LoadStoreParameter}
@ -1619,9 +1620,9 @@ public class KeyStore {
* @param alias the alias name * @param alias the alias name
* @param entryClass the entry class * @param entryClass the entry class
* *
* @return true if the keystore {@code Entry} for the specified * @return {@code true} if the keystore {@code Entry} for the specified
* {@code alias} is an instance or subclass of the * {@code alias} is an instance or subclass of the
* specified {@code entryClass}, false otherwise * specified {@code entryClass}, {@code false} otherwise
* *
* @throws NullPointerException if * @throws NullPointerException if
* {@code alias} or {@code entryClass} * {@code alias} or {@code entryClass}
@ -1662,13 +1663,14 @@ public class KeyStore {
* <p> * <p>
* This method traverses the list of registered security * This method traverses the list of registered security
* {@linkplain Provider providers}, starting with the most * {@linkplain Provider providers}, starting with the most
* preferred Provider. * preferred provider.
* For each {@link KeyStoreSpi} implementation supported by a * For each {@link KeyStoreSpi} implementation supported by a
* Provider, it invokes the {@link * provider, it invokes the {@link
* KeyStoreSpi#engineProbe(InputStream) engineProbe} method to * KeyStoreSpi#engineProbe(InputStream) engineProbe} method to
* determine if it supports the specified keystore. * determine if it supports the specified keystore.
* A new KeyStore object is returned that encapsulates the KeyStoreSpi * A new {@code KeyStore} object is returned that encapsulates the
* implementation from the first Provider that supports the specified file. * {@code KeyStoreSpi}
* implementation from the first provider that supports the specified file.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -1678,7 +1680,7 @@ public class KeyStore {
* *
* @return a keystore object loaded with keystore data * @return a keystore object loaded with keystore data
* *
* @throws KeyStoreException if no Provider supports a KeyStoreSpi * @throws KeyStoreException if no provider supports a {@code KeyStoreSpi}
* implementation for the specified keystore file. * implementation for the specified keystore file.
* @throws IOException if there is an I/O or format problem with the * @throws IOException if there is an I/O or format problem with the
* keystore data, if a password is required but not given, * keystore data, if a password is required but not given,
@ -1717,13 +1719,14 @@ public class KeyStore {
* *
* <p> * <p>
* This method traverses the list of registered security {@linkplain * This method traverses the list of registered security {@linkplain
* Provider providers}, starting with the most preferred Provider. * Provider providers}, starting with the most preferred provider.
* For each {@link KeyStoreSpi} implementation supported by a * For each {@link KeyStoreSpi} implementation supported by a
* Provider, it invokes the {@link * provider, it invokes the {@link
* KeyStoreSpi#engineProbe(InputStream) engineProbe} method to * KeyStoreSpi#engineProbe(InputStream) engineProbe} method to
* determine if it supports the specified keystore. * determine if it supports the specified keystore.
* A new KeyStore object is returned that encapsulates the KeyStoreSpi * A new {@code KeyStore} object is returned that encapsulates the
* implementation from the first Provider that supports the specified file. * {@code KeyStoreSpi}
* implementation from the first provider that supports the specified file.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -1734,7 +1737,7 @@ public class KeyStore {
* *
* @return a keystore object loaded with keystore data * @return a keystore object loaded with keystore data
* *
* @throws KeyStoreException if no Provider supports a KeyStoreSpi * @throws KeyStoreException if no provider supports a {@code KeyStoreSpi}
* implementation for the specified keystore file. * implementation for the specified keystore file.
* @throws IOException if there is an I/O or format problem with the * @throws IOException if there is an I/O or format problem with the
* keystore data. If the error is due to an incorrect * keystore data. If the error is due to an incorrect
@ -1836,13 +1839,13 @@ public class KeyStore {
} }
/** /**
* A description of a to-be-instantiated KeyStore object. * A description of a to-be-instantiated {@code KeyStore} object.
* *
* <p>An instance of this class encapsulates the information needed to * <p>An instance of this class encapsulates the information needed to
* instantiate and initialize a KeyStore object. That process is * instantiate and initialize a {@code KeyStore} object. That process is
* triggered when the {@linkplain #getKeyStore} method is called. * triggered when the {@linkplain #getKeyStore} method is called.
* *
* <p>This makes it possible to decouple configuration from KeyStore * <p>This makes it possible to decouple configuration from {@code KeyStore}
* object creation and e.g. delay a password prompt until it is * object creation and e.g. delay a password prompt until it is
* needed. * needed.
* *
@ -1856,57 +1859,58 @@ public class KeyStore {
static final int MAX_CALLBACK_TRIES = 3; static final int MAX_CALLBACK_TRIES = 3;
/** /**
* Construct a new Builder. * Construct a new {@code Builder}.
*/ */
protected Builder() { protected Builder() {
// empty // empty
} }
/** /**
* Returns the KeyStore described by this object. * Returns the {@code KeyStore} described by this object.
* *
* @return the {@code KeyStore} described by this object * @return the {@code KeyStore} described by this object
* @throws KeyStoreException if an error occurred during the * @throws KeyStoreException if an error occurred during the
* operation, for example if the KeyStore could not be * operation, for example if the {@code KeyStore} could not be
* instantiated or loaded * instantiated or loaded
*/ */
public abstract KeyStore getKeyStore() throws KeyStoreException; public abstract KeyStore getKeyStore() throws KeyStoreException;
/** /**
* Returns the ProtectionParameters that should be used to obtain * Returns the {@code ProtectionParameter} that should be used to obtain
* the {@link KeyStore.Entry Entry} with the given alias. * the {@link KeyStore.Entry Entry} with the given alias.
* The {@code getKeyStore} method must be invoked before this * The {@code getKeyStore} method must be invoked before this
* method may be called. * method may be called.
* *
* @return the ProtectionParameters that should be used to obtain * @return the {@code ProtectionParameter} that should be used to obtain
* the {@link KeyStore.Entry Entry} with the given alias. * the {@link KeyStore.Entry Entry} with the given alias.
* @param alias the alias of the KeyStore entry * @param alias the alias of the {@code KeyStore} entry
* @throws NullPointerException if alias is null * @throws NullPointerException if alias is {@code null}
* @throws KeyStoreException if an error occurred during the * @throws KeyStoreException if an error occurred during the
* operation * operation
* @throws IllegalStateException if the getKeyStore method has * @throws IllegalStateException if the {@code getKeyStore} method has
* not been invoked prior to calling this method * not been invoked prior to calling this method
*/ */
public abstract ProtectionParameter getProtectionParameter(String alias) public abstract ProtectionParameter getProtectionParameter(String alias)
throws KeyStoreException; throws KeyStoreException;
/** /**
* Returns a new Builder that encapsulates the given KeyStore. * Returns a new {@code Builder} that encapsulates the given
* {@code KeyStore}.
* The {@linkplain #getKeyStore} method of the returned object * The {@linkplain #getKeyStore} method of the returned object
* will return {@code keyStore}, the {@linkplain * will return {@code keyStore}, the {@linkplain
* #getProtectionParameter getProtectionParameter()} method will * #getProtectionParameter getProtectionParameter()} method will
* return {@code protectionParameters}. * return {@code protectionParameters}.
* *
* <p> This is useful if an existing KeyStore object needs to be * <p> This is useful if an existing {@code KeyStore} object needs to be
* used with Builder-based APIs. * used with builder-based APIs.
* *
* @return a new Builder object * @return a new {@code Builder} object
* @param keyStore the KeyStore to be encapsulated * @param keyStore the {@code KeyStore} to be encapsulated
* @param protectionParameter the ProtectionParameter used to * @param protectionParameter the {@code ProtectionParameter} used to
* protect the KeyStore entries * protect the {@code KeyStore} entries
* @throws NullPointerException if keyStore or * @throws NullPointerException if {@code keyStore} or
* protectionParameters is null * {@code protectionParameter} is {@code null}
* @throws IllegalArgumentException if the keyStore has not been * @throws IllegalArgumentException if the {@code keyStore} has not been
* initialized * initialized
*/ */
public static Builder newInstance(final KeyStore keyStore, public static Builder newInstance(final KeyStore keyStore,
@ -1940,10 +1944,10 @@ public class KeyStore {
} }
/** /**
* Returns a new Builder object. * Returns a new {@code Builder} object.
* *
* <p>The first call to the {@link #getKeyStore} method on the returned * <p>The first call to the {@link #getKeyStore} method on the returned
* builder will create a KeyStore of type {@code type} and call * builder will create a {@code KeyStore} of type {@code type} and call
* its {@link KeyStore#load load()} method. * its {@link KeyStore#load load()} method.
* The {@code inputStream} argument is constructed from * The {@code inputStream} argument is constructed from
* {@code file}. * {@code file}.
@ -1956,10 +1960,10 @@ public class KeyStore {
* *
* <p>Subsequent calls to {@link #getKeyStore} return the same object * <p>Subsequent calls to {@link #getKeyStore} return the same object
* as the initial call. If the initial call failed with a * as the initial call. If the initial call failed with a
* KeyStoreException, subsequent calls also throw a * {@code KeyStoreException}, subsequent calls also throw a
* KeyStoreException. * {@code KeyStoreException}.
* *
* <p>The KeyStore is instantiated from {@code provider} if * <p>The {@code KeyStore} is instantiated from {@code provider} if
* non-null. Otherwise, all installed providers are searched. * non-null. Otherwise, all installed providers are searched.
* *
* <p>Calls to {@link #getProtectionParameter getProtectionParameter()} * <p>Calls to {@link #getProtectionParameter getProtectionParameter()}
@ -1971,13 +1975,15 @@ public class KeyStore {
* within the {@link AccessControlContext} of the code invoking this * within the {@link AccessControlContext} of the code invoking this
* method. * method.
* *
* @return a new Builder object * @return a new {@code Builder} object
* @param type the type of KeyStore to be constructed * @param type the type of {@code KeyStore} to be constructed
* @param provider the provider from which the KeyStore is to * @param provider the provider from which the {@code KeyStore} is to
* be instantiated (or null) * be instantiated (or {@code null})
* @param file the File that contains the KeyStore data * @param file the File that contains the {@code KeyStore} data
* @param protection the ProtectionParameter securing the KeyStore data * @param protection the {@code ProtectionParameter} securing the
* @throws NullPointerException if type, file or protection is null * {@code KeyStore} data
* @throws NullPointerException if type, file or protection is
* {@code null}
* @throws IllegalArgumentException if protection is not an instance * @throws IllegalArgumentException if protection is not an instance
* of either PasswordProtection or CallbackHandlerProtection; or * of either PasswordProtection or CallbackHandlerProtection; or
* if file does not exist or does not refer to a normal file * if file does not exist or does not refer to a normal file
@ -2004,11 +2010,12 @@ public class KeyStore {
} }
/** /**
* Returns a new Builder object. * Returns a new {@code Builder} object.
* *
* <p>The first call to the {@link #getKeyStore} method on the returned * <p>The first call to the {@link #getKeyStore} method on the returned
* builder will create a KeyStore using {@code file} to detect the * builder will create a {@code KeyStore} using {@code file} to detect
* keystore type and then call its {@link KeyStore#load load()} method. * the keystore type and then call its {@link KeyStore#load load()}
* method.
* It uses the same algorithm to determine the keystore type as * It uses the same algorithm to determine the keystore type as
* described in {@link KeyStore#getInstance(File, LoadStoreParameter)}. * described in {@link KeyStore#getInstance(File, LoadStoreParameter)}.
* The {@code inputStream} argument is constructed from {@code file}. * The {@code inputStream} argument is constructed from {@code file}.
@ -2020,7 +2027,8 @@ public class KeyStore {
* *
* <p>Subsequent calls to {@link #getKeyStore} return the same object * <p>Subsequent calls to {@link #getKeyStore} return the same object
* as the initial call. If the initial call failed with a * as the initial call. If the initial call failed with a
* KeyStoreException, subsequent calls also throw a KeyStoreException. * {@code KeyStoreException}, subsequent calls also throw a
* {@code KeyStoreException}.
* *
* <p>Calls to {@link #getProtectionParameter getProtectionParameter()} * <p>Calls to {@link #getProtectionParameter getProtectionParameter()}
* will return a {@link KeyStore.PasswordProtection PasswordProtection} * will return a {@link KeyStore.PasswordProtection PasswordProtection}
@ -2031,10 +2039,11 @@ public class KeyStore {
* within the {@link AccessControlContext} of the code invoking this * within the {@link AccessControlContext} of the code invoking this
* method. * method.
* *
* @return a new Builder object * @return a new {@code Builder} object
* @param file the File that contains the KeyStore data * @param file the File that contains the {@code KeyStore} data
* @param protection the ProtectionParameter securing the KeyStore data * @param protection the {@code ProtectionParameter} securing the
* @throws NullPointerException if file or protection is null * {@code KeyStore} data
* @throws NullPointerException if file or protection is {@code null}
* @throws IllegalArgumentException if protection is not an instance * @throws IllegalArgumentException if protection is not an instance
* of either PasswordProtection or CallbackHandlerProtection; or * of either PasswordProtection or CallbackHandlerProtection; or
* if file does not exist or does not refer to a normal file * if file does not exist or does not refer to a normal file
@ -2172,16 +2181,17 @@ public class KeyStore {
} }
/** /**
* Returns a new Builder object. * Returns a new {@code Builder} object.
* *
* <p>Each call to the {@link #getKeyStore} method on the returned * <p>Each call to the {@link #getKeyStore} method on the returned
* builder will return a new KeyStore object of type {@code type}. * builder will return a new {@code KeyStore} object of type
* {@code type}.
* Its {@link KeyStore#load(KeyStore.LoadStoreParameter) load()} * Its {@link KeyStore#load(KeyStore.LoadStoreParameter) load()}
* method is invoked using a * method is invoked using a
* {@code LoadStoreParameter} that encapsulates * {@code LoadStoreParameter} that encapsulates
* {@code protection}. * {@code protection}.
* *
* <p>The KeyStore is instantiated from {@code provider} if * <p>The {@code KeyStore} is instantiated from {@code provider} if
* non-null. Otherwise, all installed providers are searched. * non-null. Otherwise, all installed providers are searched.
* *
* <p>Calls to {@link #getProtectionParameter getProtectionParameter()} * <p>Calls to {@link #getProtectionParameter getProtectionParameter()}
@ -2191,12 +2201,13 @@ public class KeyStore {
* within the {@link AccessControlContext} of the code invoking this * within the {@link AccessControlContext} of the code invoking this
* method. * method.
* *
* @return a new Builder object * @return a new {@code Builder} object
* @param type the type of KeyStore to be constructed * @param type the type of {@code KeyStore} to be constructed
* @param provider the provider from which the KeyStore is to * @param provider the provider from which the {@code KeyStore} is to
* be instantiated (or null) * be instantiated (or {@code null})
* @param protection the ProtectionParameter securing the Keystore * @param protection the {@code ProtectionParameter} securing the
* @throws NullPointerException if type or protection is null * {@code Keystore}
* @throws NullPointerException if type or protection is {@code null}
*/ */
public static Builder newInstance(final String type, public static Builder newInstance(final String type,
final Provider provider, final ProtectionParameter protection) { final Provider provider, final ProtectionParameter protection) {

10
src/java.base/share/classes/java/security/KeyStoreException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -40,8 +40,8 @@ public class KeyStoreException extends GeneralSecurityException {
private static final long serialVersionUID = -1119353179322377262L; private static final long serialVersionUID = -1119353179322377262L;
/** /**
* Constructs a KeyStoreException with no detail message. (A * Constructs a {@code KeyStoreException} with no detail message. (A
* detail message is a String that describes this particular * detail message is a {@code String} that describes this particular
* exception.) * exception.)
*/ */
public KeyStoreException() { public KeyStoreException() {
@ -49,8 +49,8 @@ public class KeyStoreException extends GeneralSecurityException {
} }
/** /**
* Constructs a KeyStoreException with the specified detail * Constructs a {@code KeyStoreException} with the specified detail
* message. (A detail message is a String that describes this * message. (A detail message is a {@code String} that describes this
* particular exception.) * particular exception.)
* *
* @param msg the detail message. * @param msg the detail message.

43
src/java.base/share/classes/java/security/KeyStoreSpi.java
View file

@ -68,8 +68,8 @@ public abstract class KeyStoreSpi {
* @param alias the alias name * @param alias the alias name
* @param password the password for recovering the key * @param password the password for recovering the key
* *
* @return the requested key, or null if the given alias does not exist * @return the requested key, or {@code null} if the given alias
* or does not identify a key-related entry. * does not exist or does not identify a key-related entry.
* *
* @throws NoSuchAlgorithmException if the algorithm for recovering the * @throws NoSuchAlgorithmException if the algorithm for recovering the
* key cannot be found * key cannot be found
@ -89,8 +89,8 @@ public abstract class KeyStoreSpi {
* @param alias the alias name * @param alias the alias name
* *
* @return the certificate chain (ordered with the user's certificate first * @return the certificate chain (ordered with the user's certificate first
* and the root certificate authority last), or null if the given alias * and the root certificate authority last), or {@code null} if the
* does not exist or does not contain a certificate chain * given alias * does not exist or does not contain a certificate chain
*/ */
public abstract Certificate[] engineGetCertificateChain(String alias); public abstract Certificate[] engineGetCertificateChain(String alias);
@ -112,8 +112,8 @@ public abstract class KeyStoreSpi {
* *
* @param alias the alias name * @param alias the alias name
* *
* @return the certificate, or null if the given alias does not exist or * @return the certificate, or {@code null} if the given alias does not
* does not contain a certificate. * exist or does not contain a certificate.
*/ */
public abstract Certificate engineGetCertificate(String alias); public abstract Certificate engineGetCertificate(String alias);
@ -122,8 +122,8 @@ public abstract class KeyStoreSpi {
* *
* @param alias the alias name * @param alias the alias name
* *
* @return the creation date of this entry, or null if the given alias does * @return the creation date of this entry, or {@code null}
* not exist * if the given alias does not exist
*/ */
public abstract Date engineGetCreationDate(String alias); public abstract Date engineGetCreationDate(String alias);
@ -222,7 +222,7 @@ public abstract class KeyStoreSpi {
* *
* @param alias the alias name * @param alias the alias name
* *
* @return true if the alias exists, false otherwise * @return {@code true} if the alias exists, {@code false} otherwise
*/ */
public abstract boolean engineContainsAlias(String alias); public abstract boolean engineContainsAlias(String alias);
@ -234,28 +234,28 @@ public abstract class KeyStoreSpi {
public abstract int engineSize(); public abstract int engineSize();
/** /**
* Returns true if the entry identified by the given alias * Returns {@code true} if the entry identified by the given alias
* was created by a call to {@code setKeyEntry}, * was created by a call to {@code setKeyEntry},
* or created by a call to {@code setEntry} with a * or created by a call to {@code setEntry} with a
* {@code PrivateKeyEntry} or a {@code SecretKeyEntry}. * {@code PrivateKeyEntry} or a {@code SecretKeyEntry}.
* *
* @param alias the alias for the keystore entry to be checked * @param alias the alias for the keystore entry to be checked
* *
* @return true if the entry identified by the given alias is a * @return {@code true} if the entry identified by the given alias is a
* key-related, false otherwise. * key-related, {@code false} otherwise.
*/ */
public abstract boolean engineIsKeyEntry(String alias); public abstract boolean engineIsKeyEntry(String alias);
/** /**
* Returns true if the entry identified by the given alias * Returns {@code true} if the entry identified by the given alias
* was created by a call to {@code setCertificateEntry}, * was created by a call to {@code setCertificateEntry},
* or created by a call to {@code setEntry} with a * or created by a call to {@code setEntry} with a
* {@code TrustedCertificateEntry}. * {@code TrustedCertificateEntry}.
* *
* @param alias the alias for the keystore entry to be checked * @param alias the alias for the keystore entry to be checked
* *
* @return true if the entry identified by the given alias contains a * @return {@code true} if the entry identified by the given alias
* trusted certificate, false otherwise. * contains a trusted certificate, {@code false} otherwise.
*/ */
public abstract boolean engineIsCertificateEntry(String alias); public abstract boolean engineIsCertificateEntry(String alias);
@ -280,7 +280,7 @@ public abstract class KeyStoreSpi {
* @param cert the certificate to match with. * @param cert the certificate to match with.
* *
* @return the alias name of the first entry with matching certificate, * @return the alias name of the first entry with matching certificate,
* or null if no such entry exists in this keystore. * or {@code null} if no such entry exists in this keystore.
*/ */
public abstract String engineGetCertificateAlias(Certificate cert); public abstract String engineGetCertificateAlias(Certificate cert);
@ -626,7 +626,7 @@ public abstract class KeyStoreSpi {
* @param alias the alias name * @param alias the alias name
* @param entryClass the entry class * @param entryClass the entry class
* *
* @return true if the keystore {@code Entry} for the specified * @return {@code true} if the keystore {@code Entry} for the specified
* {@code alias} is an instance or subclass of the * {@code alias} is an instance or subclass of the
* specified {@code entryClass}, false otherwise * specified {@code entryClass}, false otherwise
* *
@ -655,13 +655,14 @@ public abstract class KeyStoreSpi {
* keystore that is supported by this implementation, or not. * keystore that is supported by this implementation, or not.
* *
* @implSpec * @implSpec
* This method returns false by default. Keystore implementations should * This method returns {@code false} by default. Keystore implementations
* override this method to peek at the data stream directly or to use other * should override this method to peek at the data stream directly or
* content detection mechanisms. * to use other content detection mechanisms.
* *
* @param stream the keystore data to be probed * @param stream the keystore data to be probed
* *
* @return true if the keystore data is supported, otherwise false * @return {@code true} if the keystore data is supported,
* otherwise {@code false}
* *
* @throws IOException if there is an I/O problem with the keystore data. * @throws IOException if there is an I/O problem with the keystore data.
* @throws NullPointerException if stream is {@code null}. * @throws NullPointerException if stream is {@code null}.

59
src/java.base/share/classes/java/security/MessageDigest.java
View file

@ -37,12 +37,12 @@ import sun.security.util.MessageDigestSpi2;
import javax.crypto.SecretKey; import javax.crypto.SecretKey;
/** /**
* This MessageDigest class provides applications the functionality of a * This {@code MessageDigest} class provides applications the functionality of a
* message digest algorithm, such as SHA-1 or SHA-256. * message digest algorithm, such as SHA-1 or SHA-256.
* Message digests are secure one-way hash functions that take arbitrary-sized * Message digests are secure one-way hash functions that take arbitrary-sized
* data and output a fixed-length hash value. * data and output a fixed-length hash value.
* *
* <p>A MessageDigest object starts out initialized. The data is * <p>A {@code MessageDigest} object starts out initialized. The data is
* processed through it using the {@link #update(byte) update} * processed through it using the {@link #update(byte) update}
* methods. At any point {@link #reset() reset} can be called * methods. At any point {@link #reset() reset} can be called
* to reset the digest. Once all the data to be updated has been * to reset the digest. Once all the data to be updated has been
@ -50,12 +50,12 @@ import javax.crypto.SecretKey;
* be called to complete the hash computation. * be called to complete the hash computation.
* *
* <p>The {@code digest} method can be called once for a given number * <p>The {@code digest} method can be called once for a given number
* of updates. After {@code digest} has been called, the MessageDigest * of updates. After {@code digest} has been called, the {@code MessageDigest}
* object is reset to its initialized state. * object is reset to its initialized state.
* *
* <p>Implementations are free to implement the Cloneable interface. * <p>Implementations are free to implement the Cloneable interface.
* Client applications can test cloneability by attempting cloning * Client applications can test cloneability by attempting cloning
* and catching the CloneNotSupportedException: * and catching the {@code CloneNotSupportedException}:
* *
* <pre>{@code * <pre>{@code
* MessageDigest md = MessageDigest.getInstance("SHA-256"); * MessageDigest md = MessageDigest.getInstance("SHA-256");
@ -139,14 +139,14 @@ public abstract class MessageDigest extends MessageDigestSpi {
} }
/** /**
* Returns a MessageDigest object that implements the specified digest * Returns a {@code MessageDigest} object that implements the specified
* algorithm. * digest algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security Providers,
* starting with the most preferred Provider. * starting with the most preferred Provider.
* A new MessageDigest object encapsulating the * A new {@code MessageDigest} object encapsulating the
* MessageDigestSpi implementation from the first * {@code MessageDigestSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -201,11 +201,11 @@ public abstract class MessageDigest extends MessageDigestSpi {
} }
/** /**
* Returns a MessageDigest object that implements the specified digest * Returns a {@code MessageDigest} object that implements the specified
* algorithm. * digest algorithm.
* *
* <p> A new MessageDigest object encapsulating the * <p> A new {@code MessageDigest} object encapsulating the
* MessageDigestSpi implementation from the specified provider * {@code MessageDigestSpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -258,13 +258,13 @@ public abstract class MessageDigest extends MessageDigestSpi {
} }
/** /**
* Returns a MessageDigest object that implements the specified digest * Returns a {@code MessageDigest} object that implements the specified
* algorithm. * digest algorithm.
* *
* <p> A new MessageDigest object encapsulating the * <p> A new {@code MessageDigest} object encapsulating the
* MessageDigestSpi implementation from the specified Provider * {@code MessageDigestSpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * is returned. Note that the specified provider does not
* does not have to be registered in the provider list. * have to be registered in the provider list.
* *
* @param algorithm the name of the algorithm requested. * @param algorithm the name of the algorithm requested.
* See the MessageDigest section in the <a href= * See the MessageDigest section in the <a href=
@ -466,7 +466,7 @@ public abstract class MessageDigest extends MessageDigestSpi {
* *
* @param digestb the other digest to compare. * @param digestb the other digest to compare.
* *
* @return true if the digests are equal, false otherwise. * @return {@code true} if the digests are equal, {@code false} otherwise.
*/ */
public static boolean isEqual(byte[] digesta, byte[] digestb) { public static boolean isEqual(byte[] digesta, byte[] digestb) {
if (digesta == digestb) return true; if (digesta == digestb) return true;
@ -557,17 +557,18 @@ public abstract class MessageDigest extends MessageDigestSpi {
/* /*
* The following class allows providers to extend from MessageDigestSpi * The following class allows providers to extend from
* rather than from MessageDigest. It represents a MessageDigest with an * {@code MessageDigestSpi} rather than from {@code MessageDigest}.
* It represents a message digest with an
* encapsulated, provider-supplied SPI object (of type MessageDigestSpi). * encapsulated, provider-supplied SPI object (of type MessageDigestSpi).
* If the provider implementation is an instance of MessageDigestSpi, * If the provider implementation is an instance of
* the getInstance() methods above return an instance of this class, with * {@code MessageDigestSpi}, the {@code getInstance()} methods
* the SPI object encapsulated. * above return an instance of this class, with the SPI object encapsulated.
* *
* Note: All SPI methods from the original MessageDigest class have been * Note: All SPI methods from the original {@code MessageDigest} class
* moved up the hierarchy into a new class (MessageDigestSpi), which has * have been moved up the hierarchy into a new class
* been interposed in the hierarchy between the API (MessageDigest) * ({@code MessageDigestSpi}), which has been interposed in the hierarchy
* and its original parent (Object). * between the API ({@code MessageDigest}) and its original parent (Object).
*/ */
private static class Delegate extends MessageDigest private static class Delegate extends MessageDigest

5
src/java.base/share/classes/java/security/MessageDigestSpi.java
View file

@ -162,11 +162,12 @@ public abstract class MessageDigestSpi {
* *
* @param offset offset to start from in the output buffer * @param offset offset to start from in the output buffer
* *
* @param len number of bytes within buf allotted for the digest. * @param len number of bytes within {@code buf} allotted for the digest.
* Both this default implementation and the SUN provider do not * Both this default implementation and the SUN provider do not
* return partial digests. The presence of this parameter is solely * return partial digests. The presence of this parameter is solely
* for consistency in our API's. If the value of this parameter is less * for consistency in our API's. If the value of this parameter is less
* than the actual digest length, the method will throw a DigestException. * than the actual digest length, the method will throw a
* {@code DigestException}.
* This parameter is ignored if its value is greater than or equal to * This parameter is ignored if its value is greater than or equal to
* the actual digest length. * the actual digest length.
* *

10
src/java.base/share/classes/java/security/NoSuchAlgorithmException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -39,8 +39,8 @@ public class NoSuchAlgorithmException extends GeneralSecurityException {
private static final long serialVersionUID = -7443947487218346562L; private static final long serialVersionUID = -7443947487218346562L;
/** /**
* Constructs a NoSuchAlgorithmException with no detail * Constructs a {@code NoSuchAlgorithmException} with no detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
*/ */
public NoSuchAlgorithmException() { public NoSuchAlgorithmException() {
@ -48,8 +48,8 @@ public class NoSuchAlgorithmException extends GeneralSecurityException {
} }
/** /**
* Constructs a NoSuchAlgorithmException with the specified * Constructs a {@code NoSuchAlgorithmException} with the specified
* detail message. A detail message is a String that describes * detail message. A detail message is a {@code String} that describes
* this particular exception, which may, for example, specify which * this particular exception, which may, for example, specify which
* algorithm is not available. * algorithm is not available.
* *

10
src/java.base/share/classes/java/security/NoSuchProviderException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -39,8 +39,8 @@ public class NoSuchProviderException extends GeneralSecurityException {
private static final long serialVersionUID = 8488111756688534474L; private static final long serialVersionUID = 8488111756688534474L;
/** /**
* Constructs a NoSuchProviderException with no detail message. A * Constructs a {@code NoSuchProviderException} with no detail message. A
* detail message is a String that describes this particular * detail message is a {@code String} that describes this particular
* exception. * exception.
*/ */
public NoSuchProviderException() { public NoSuchProviderException() {
@ -48,8 +48,8 @@ public class NoSuchProviderException extends GeneralSecurityException {
} }
/** /**
* Constructs a NoSuchProviderException with the specified detail * Constructs a {@code NoSuchProviderException} with the specified detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
* *
* @param msg the detail message. * @param msg the detail message.

76
src/java.base/share/classes/java/security/Permission.java
View file

@ -31,13 +31,13 @@ package java.security;
* as well as abstract functions for defining the semantics of the * as well as abstract functions for defining the semantics of the
* particular Permission subclass. * particular Permission subclass.
* *
* <p>Most Permission objects also include an "actions" list that tells the actions * <p>Most {@code Permission} objects also include an "actions" list that
* that are permitted for the object. For example, * tells the actions that are permitted for the object. For example,
* for a {@code java.io.FilePermission} object, the permission name is * for a {@code java.io.FilePermission} object, the permission name is
* the pathname of a file (or directory), and the actions list * the pathname of a file (or directory), and the actions list
* (such as "read, write") specifies which actions are granted for the * (such as "read, write") specifies which actions are granted for the
* specified file (or for files in the specified directory). * specified file (or for files in the specified directory).
* The actions list is optional for Permission objects, such as * The actions list is optional for {@code Permission} objects, such as
* {@code java.lang.RuntimePermission}, * {@code java.lang.RuntimePermission},
* that don't need such a list; you either have the named permission (such * that don't need such a list; you either have the named permission (such
* as "system.exit") or you don't. * as "system.exit") or you don't.
@ -49,8 +49,8 @@ package java.security;
* Thus, this is not an equality test, but rather more of a * Thus, this is not an equality test, but rather more of a
* subset test. * subset test.
* *
* <P> Permission objects are similar to String objects in that they * <P> {@code Permission} objects are similar to {@code String} objects
* are immutable once they have been created. Subclasses should not * in that they are immutable once they have been created. Subclasses should not
* provide methods that can change the state of a permission * provide methods that can change the state of a permission
* once it has been created. * once it has been created.
* *
@ -76,7 +76,7 @@ public abstract class Permission implements Guard, java.io.Serializable {
/** /**
* Constructs a permission with the specified name. * Constructs a permission with the specified name.
* *
* @param name name of the Permission object being created. * @param name name of the {@code Permission} object being created.
* *
*/ */
@ -89,7 +89,7 @@ public abstract class Permission implements Guard, java.io.Serializable {
* {@code SecurityManager.checkPermission} method is called, * {@code SecurityManager.checkPermission} method is called,
* passing this permission object as the permission to check. * passing this permission object as the permission to check.
* Returns silently if access is granted. Otherwise, throws * Returns silently if access is granted. Otherwise, throws
* a SecurityException. * a {@code SecurityException}.
* *
* @param object the object being guarded (currently ignored). * @param object the object being guarded (currently ignored).
* *
@ -112,8 +112,9 @@ public abstract class Permission implements Guard, java.io.Serializable {
* Checks if the specified permission's actions are "implied by" * Checks if the specified permission's actions are "implied by"
* this object's actions. * this object's actions.
* <P> * <P>
* This must be implemented by subclasses of Permission, as they are the * This must be implemented by subclasses of {@code Permission}, as they
* only ones that can impose semantics on a Permission object. * are the only ones that can impose semantics on a {@code Permission}
* object.
* *
* <p>The {@code implies} method is used by the AccessController to determine * <p>The {@code implies} method is used by the AccessController to determine
* whether a requested permission is implied by another permission that * whether a requested permission is implied by another permission that
@ -121,41 +122,41 @@ public abstract class Permission implements Guard, java.io.Serializable {
* *
* @param permission the permission to check against. * @param permission the permission to check against.
* *
* @return true if the specified permission is implied by this object, * @return {@code true} if the specified permission is implied by this
* false if not. * object, {@code false} if not.
*/ */
public abstract boolean implies(Permission permission); public abstract boolean implies(Permission permission);
/** /**
* Checks two Permission objects for equality. * Checks two {@code Permission} objects for equality.
* <P> * <P>
* Do not use the {@code equals} method for making access control * Do not use the {@code equals} method for making access control
* decisions; use the {@code implies} method. * decisions; use the {@code implies} method.
* *
* @param obj the object we are testing for equality with this object. * @param obj the object we are testing for equality with this object.
* *
* @return true if both Permission objects are equivalent. * @return {@code true} if both {@code Permission} objects are equivalent.
*/ */
public abstract boolean equals(Object obj); public abstract boolean equals(Object obj);
/** /**
* Returns the hash code value for this Permission object. * Returns the hash code value for this {@code Permission} object.
* <P> * <P>
* The required {@code hashCode} behavior for Permission Objects is * The required {@code hashCode} behavior for {@code Permission} Objects is
* the following: * the following:
* <ul> * <ul>
* <li>Whenever it is invoked on the same Permission object more than * <li>Whenever it is invoked on the same {@code Permission} object more
* once during an execution of a Java application, the * than once during an execution of a Java application, the
* {@code hashCode} method * {@code hashCode} method
* must consistently return the same integer. This integer need not * must consistently return the same integer. This integer need not
* remain consistent from one execution of an application to another * remain consistent from one execution of an application to another
* execution of the same application. * execution of the same application.
* <li>If two Permission objects are equal according to the * <li>If two {@code Permission} objects are equal according to the
* {@code equals} * {@code equals}
* method, then calling the {@code hashCode} method on each of the * method, then calling the {@code hashCode} method on each of the
* two Permission objects must produce the same integer result. * two {@code Permission} objects must produce the same integer result.
* </ul> * </ul>
* *
* @return a hash code value for this object. * @return a hash code value for this object.
@ -164,11 +165,11 @@ public abstract class Permission implements Guard, java.io.Serializable {
public abstract int hashCode(); public abstract int hashCode();
/** /**
* Returns the name of this Permission. * Returns the name of this {@code Permission}.
* For example, in the case of a {@code java.io.FilePermission}, * For example, in the case of a {@code java.io.FilePermission},
* the name will be a pathname. * the name will be a pathname.
* *
* @return the name of this Permission. * @return the name of this {@code Permission}.
* *
*/ */
@ -177,8 +178,8 @@ public abstract class Permission implements Guard, java.io.Serializable {
} }
/** /**
* Returns the actions as a String. This is abstract * Returns the actions as a {@code String}. This is abstract
* so subclasses can defer creating a String representation until * so subclasses can defer creating a {@code String} representation until
* one is needed. Subclasses should always return actions in what they * one is needed. Subclasses should always return actions in what they
* consider to be their * consider to be their
* canonical form. For example, two FilePermission objects created via * canonical form. For example, two FilePermission objects created via
@ -192,25 +193,26 @@ public abstract class Permission implements Guard, java.io.Serializable {
* both return * both return
* "read,write" when the {@code getActions} method is invoked. * "read,write" when the {@code getActions} method is invoked.
* *
* @return the actions of this Permission. * @return the actions of this {@code Permission}.
* *
*/ */
public abstract String getActions(); public abstract String getActions();
/** /**
* Returns an empty PermissionCollection for a given Permission object, or null if * Returns an empty {@code PermissionCollection} for a given
* one is not defined. Subclasses of class Permission should * {@code Permission} object, or {@code null} if
* one is not defined. Subclasses of class {@code Permission} should
* override this if they need to store their permissions in a particular * override this if they need to store their permissions in a particular
* PermissionCollection object in order to provide the correct semantics * {@code PermissionCollection} object in order to provide the correct
* when the {@code PermissionCollection.implies} method is called. * semantics when the {@code PermissionCollection.implies} method is called.
* If null is returned, * If {@code null} is returned,
* then the caller of this method is free to store permissions of this * then the caller of this method is free to store permissions of this
* type in any PermissionCollection they choose (one that uses a Hashtable, * type in any {@code PermissionCollection} they choose (one that uses
* one that uses a Vector, etc.). * a Hashtable, one that uses a Vector, etc.).
* *
* @return a new PermissionCollection object for this type of Permission, or * @return a new {@code PermissionCollection} object for this type of
* null if one is not defined. * {@code Permission}, or {@code null} if one is not defined.
*/ */
public PermissionCollection newPermissionCollection() { public PermissionCollection newPermissionCollection() {
@ -218,12 +220,12 @@ public abstract class Permission implements Guard, java.io.Serializable {
} }
/** /**
* Returns a string describing this Permission. The convention is to * Returns a string describing this {@code Permission}. The convention
* specify the class name, the permission name, and the actions in * is to specify the class name, the permission name, and the actions in
* the following format: '("ClassName" "name" "actions")', or * the following format: '("ClassName" "name" "actions")', or
* '("ClassName" "name")' if actions list is null or empty. * '("ClassName" "name")' if actions list is {@code null} or empty.
* *
* @return information about this Permission. * @return information about this {@code Permission}.
*/ */
public String toString() { public String toString() {
String actions = getActions(); String actions = getActions();

118
src/java.base/share/classes/java/security/PermissionCollection.java
View file

@ -32,7 +32,7 @@ import java.util.stream.StreamSupport;
/** /**
* Abstract class representing a collection of Permission objects. * Abstract class representing a collection of Permission objects.
* *
* <p>With a PermissionCollection, you can: * <p>With a {@code PermissionCollection}, you can:
* <UL> * <UL>
* <LI> add a permission to the collection using the {@code add} method. * <LI> add a permission to the collection using the {@code add} method.
* <LI> check to see if a particular permission is implied in the * <LI> check to see if a particular permission is implied in the
@ -40,46 +40,49 @@ import java.util.stream.StreamSupport;
* <LI> enumerate all the permissions, using the {@code elements} method. * <LI> enumerate all the permissions, using the {@code elements} method.
* </UL> * </UL>
* *
* <p>When it is desirable to group together a number of Permission objects * <p>When it is desirable to group together a number of {@code Permission}
* of the same type, the {@code newPermissionCollection} method on that * objects of the same type, the {@code newPermissionCollection} method on that
* particular type of Permission object should first be called. The default * particular type of {@code Permission} object should first be called. The
* behavior (from the Permission class) is to simply return null. * default behavior (from the {@code Permission} class) is to simply return
* Subclasses of class Permission override the method if they need to store * {@code null}. Subclasses of class {@code Permission} override the method if
* their permissions in a particular PermissionCollection object in order * they need to store their permissions in a particular
* to provide the correct semantics when the * {@code PermissionCollection} object in order to provide the correct
* {@code PermissionCollection.implies} method is called. * semantics when the {@code PermissionCollection.implies} method is called.
* If a non-null value is returned, that PermissionCollection must be used. * If a non-null value is returned, that {@code PermissionCollection} must be
* If null is returned, then the caller of {@code newPermissionCollection} * used. If {@code null} is returned, then the caller of
* is free to store permissions of the * {@code newPermissionCollection} is free to store permissions of the
* given type in any PermissionCollection they choose * given type in any {@code PermissionCollection} they choose
* (one that uses a Hashtable, one that uses a Vector, etc.). * (one that uses a {@code Hashtable}, one that uses a {@code Vector}, etc.).
* *
* <p>The PermissionCollection returned by the * <p>The collection returned by the {@code Permission.newPermissionCollection}
* {@code Permission.newPermissionCollection} * method is a homogeneous collection, which stores only {@code Permission}
* method is a homogeneous collection, which stores only Permission objects * objects for a given permission type. A {@code PermissionCollection} may
* for a given Permission type. A PermissionCollection may also be * also be heterogeneous. For example, {@code Permissions} is a
* heterogeneous. For example, Permissions is a PermissionCollection * {@code PermissionCollection} subclass that represents a collection of
* subclass that represents a collection of PermissionCollections. * {@code PermissionCollection} objects.
* That is, its members are each a homogeneous PermissionCollection. * That is, its members are each a homogeneous {@code PermissionCollection}.
* For example, a Permissions object might have a FilePermissionCollection * For example, a {@code Permission} object might have a
* for all the FilePermission objects, a SocketPermissionCollection for all the * {@code FilePermissionCollection} for all the {@code FilePermission} objects,
* SocketPermission objects, and so on. Its {@code add} method adds a * a {@code SocketPermissionCollection} for all the {@code SocketPermission}
* objects, and so on. Its {@code add} method adds a
* permission to the appropriate collection. * permission to the appropriate collection.
* *
* <p>Whenever a permission is added to a heterogeneous PermissionCollection * <p>Whenever a permission is added to a heterogeneous
* such as Permissions, and the PermissionCollection doesn't yet contain a * {@code PermissionCollection} such as {@code Permissions}, and the
* PermissionCollection of the specified permission's type, the * {@code PermissionCollection} doesn't yet contain a
* PermissionCollection should call * {@code PermissionCollection} of the specified permission's type, the
* {@code PermissionCollection} should call
* the {@code newPermissionCollection} method on the permission's class * the {@code newPermissionCollection} method on the permission's class
* to see if it requires a special PermissionCollection. If * to see if it requires a special {@code PermissionCollection}. If
* {@code newPermissionCollection} * {@code newPermissionCollection}
* returns null, the PermissionCollection * returns {@code null}, the {@code PermissionCollection}
* is free to store the permission in any type of PermissionCollection it * is free to store the permission in any type of {@code PermissionCollection}
* desires (one using a Hashtable, one using a Vector, etc.). For example, * it desires (one using a {@code Hashtable}, one using a {@code Vector}, etc.).
* the Permissions object uses a default PermissionCollection implementation * For example, the {@code Permissions} object uses a default
* that stores the permission objects in a Hashtable. * {@code PermissionCollection} implementation that stores the permission
* objects in a {@code Hashtable}.
* *
* <p> Subclass implementations of PermissionCollection should assume * <p> Subclass implementations of {@code PermissionCollection} should assume
* that they may be called simultaneously from multiple threads, * that they may be called simultaneously from multiple threads,
* and therefore should be synchronized properly. Furthermore, * and therefore should be synchronized properly. Furthermore,
* Enumerations returned via the {@code elements} method are * Enumerations returned via the {@code elements} method are
@ -116,9 +119,10 @@ public abstract class PermissionCollection implements java.io.Serializable {
* *
* @param permission the Permission object to add. * @param permission the Permission object to add.
* *
* @throws SecurityException if this PermissionCollection object * @throws SecurityException if this {@code PermissionCollection}
* has been marked readonly * object has been marked readonly
* @throws IllegalArgumentException if this PermissionCollection * @throws IllegalArgumentException if this
* {@code PermissionCollection}
* object is a homogeneous collection and the permission * object is a homogeneous collection and the permission
* is not of the correct type. * is not of the correct type.
*/ */
@ -126,12 +130,13 @@ public abstract class PermissionCollection implements java.io.Serializable {
/** /**
* Checks to see if the specified permission is implied by * Checks to see if the specified permission is implied by
* the collection of Permission objects held in this PermissionCollection. * the collection of {@code Permission} objects held in this
* {@code PermissionCollection}.
* *
* @param permission the Permission object to compare. * @param permission the {@code Permission} object to compare.
* *
* @return true if "permission" is implied by the permissions in * @return {@code true} if "permission" is implied by the permissions in
* the collection, false if not. * the collection, {@code false} if not.
*/ */
public abstract boolean implies(Permission permission); public abstract boolean implies(Permission permission);
@ -168,32 +173,32 @@ public abstract class PermissionCollection implements java.io.Serializable {
} }
/** /**
* Marks this PermissionCollection object as "readonly". After * Marks this {@code PermissionCollection} object as "readonly". After
* a PermissionCollection object * a {@code PermissionCollection} object
* is marked as readonly, no new Permission objects can be added to it * is marked as readonly, no new {@code Permission} objects
* using {@code add}. * can be added to it using {@code add}.
*/ */
public void setReadOnly() { public void setReadOnly() {
readOnly = true; readOnly = true;
} }
/** /**
* Returns true if this PermissionCollection object is marked as readonly. * Returns {@code true} if this {@code PermissionCollection} object is
* If it is readonly, no new Permission objects can be added to it * marked as readonly. If it is readonly, no new {@code Permission}
* using {@code add}. * objects can be added to it using {@code add}.
* *
* <p>By default, the object is <i>not</i> readonly. It can be set to * <p>By default, the object is <i>not</i> readonly. It can be set to
* readonly by a call to {@code setReadOnly}. * readonly by a call to {@code setReadOnly}.
* *
* @return true if this PermissionCollection object is marked as readonly, * @return {@code true} if this {@code PermissionCollection} object is
* false otherwise. * marked as readonly, {@code false} otherwise.
*/ */
public boolean isReadOnly() { public boolean isReadOnly() {
return readOnly; return readOnly;
} }
/** /**
* Returns a string describing this PermissionCollection object, * Returns a string describing this {@code PermissionCollection} object,
* providing information about all the permissions it contains. * providing information about all the permissions it contains.
* The format is: * The format is:
* <pre> * <pre>
@ -205,12 +210,13 @@ public abstract class PermissionCollection implements java.io.Serializable {
* *
* {@code super.toString} is a call to the {@code toString} * {@code super.toString} is a call to the {@code toString}
* method of this * method of this
* object's superclass, which is Object. The result is * object's superclass, which is {@code Object}. The result is
* this PermissionCollection's type name followed by this object's * this collection's type name followed by this object's
* hashcode, thus enabling clients to differentiate different * hashcode, thus enabling clients to differentiate different
* PermissionCollections object, even if they contain the same permissions. * {@code PermissionCollection} objects, even if they contain the
* same permissions.
* *
* @return information about this PermissionCollection object, * @return information about this {@code PermissionCollection} object,
* as described above. * as described above.
* *
*/ */

180
src/java.base/share/classes/java/security/Permissions.java
View file

@ -40,27 +40,28 @@ import java.util.NoSuchElementException;
import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentHashMap;
/** /**
* This class represents a heterogeneous collection of Permissions. That is, * This class represents a heterogeneous collection of permissions.
* it contains different types of Permission objects, organized into * That is, it contains different types of {@code Permission} objects,
* PermissionCollections. For example, if any * organized into {@code PermissionCollection} objects. For example, if any
* {@code java.io.FilePermission} objects are added to an instance of * {@code java.io.FilePermission} objects are added to an instance of
* this class, they are all stored in a single * this class, they are all stored in a single {@code PermissionCollection}.
* PermissionCollection. It is the PermissionCollection returned by a call to * It is the {@code PermissionCollection} returned by a call to
* the {@code newPermissionCollection} method in the FilePermission class. * the {@code newPermissionCollection} method in the {@code FilePermission}
* Similarly, any {@code java.lang.RuntimePermission} objects are * class. Similarly, any {@code java.lang.RuntimePermission} objects are
* stored in the PermissionCollection returned by a call to the * stored in the {@code PermissionCollection} returned by a call to the
* {@code newPermissionCollection} method in the * {@code newPermissionCollection} method in the {@code RuntimePermission}
* RuntimePermission class. Thus, this class represents a collection of * class. Thus, this class represents a collection of
* PermissionCollections. * {@code PermissionCollection} objects.
* *
* <p>When the {@code add} method is called to add a Permission, the * <p>When the {@code add} method is called to add a {@code Permission}, the
* Permission is stored in the appropriate PermissionCollection. If no such * {@code Permission} is stored in the appropriate {@code PermissionCollection}.
* collection exists yet, the Permission object's class is determined and the * If no such collection exists yet, the {@code Permission} object's class is
* {@code newPermissionCollection} method is called on that class to create * determined and the {@code newPermissionCollection} method is called on that
* the PermissionCollection and add it to the Permissions object. If * class to create the {@code PermissionCollection} and add it to the
* {@code newPermissionCollection} returns null, then a default * {@code Permissions} object. If {@code newPermissionCollection} returns
* PermissionCollection that uses a hashtable will be created and used. Each * {@code null}, then a default {@code PermissionCollection} that uses a
* hashtable entry stores a Permission object as both the key and the value. * hashtable will be created and used. Each hashtable entry stores a
* {@code Permission} object as both the key and the value.
* *
* <p> Enumerations returned via the {@code elements} method are * <p> Enumerations returned via the {@code elements} method are
* not <em>fail-fast</em>. Modifications to a collection should not be * not <em>fail-fast</em>. Modifications to a collection should not be
@ -82,8 +83,8 @@ public final class Permissions extends PermissionCollection
implements Serializable implements Serializable
{ {
/** /**
* Key is permissions Class, value is PermissionCollection for that class. * Key is permissions Class, value is {@code PermissionCollection} for
* Not serialized; see serialization section at end of class. * that class. Not serialized; see serialization section at end of class.
*/ */
private transient ConcurrentHashMap<Class<?>, PermissionCollection> permsMap; private transient ConcurrentHashMap<Class<?>, PermissionCollection> permsMap;
@ -96,7 +97,8 @@ implements Serializable
PermissionCollection allPermission; PermissionCollection allPermission;
/** /**
* Creates a new Permissions object containing no PermissionCollections. * Creates a new {@code Permissions} object containing no
* {@code PermissionCollection} objects.
*/ */
public Permissions() { public Permissions() {
permsMap = new ConcurrentHashMap<>(11); permsMap = new ConcurrentHashMap<>(11);
@ -104,18 +106,19 @@ implements Serializable
} }
/** /**
* Adds a permission object to the PermissionCollection for the class the * Adds a {@code Permission} object to the {@code PermissionCollection}
* permission belongs to. For example, if <i>permission</i> is a * for the class the permission belongs to. For example,
* FilePermission, it is added to the FilePermissionCollection stored * if <i>permission</i> is a {@code FilePermission}, it is added to
* in this Permissions object. * the {@code FilePermissionCollection} stored in this
* {@code Permissions} object.
* *
* This method creates * This method creates a new {@code PermissionCollection} object
* a new PermissionCollection object (and adds the permission to it) * (and adds the permission to it) if an appropriate collection does
* if an appropriate collection does not yet exist. * not yet exist.
* *
* @param permission the Permission object to add. * @param permission the {@code Permission} object to add.
* *
* @throws SecurityException if this Permissions object is * @throws SecurityException if this {@code Permissions} object is
* marked as readonly. * marked as readonly.
* *
* @see PermissionCollection#isReadOnly() * @see PermissionCollection#isReadOnly()
@ -139,31 +142,30 @@ implements Serializable
} }
/** /**
* Checks to see if this object's PermissionCollection for permissions of * Checks to see if this object's {@code PermissionCollection} for
* the specified permission's class implies the permissions * permissions of the specified permission's class implies the permissions
* expressed in the <i>permission</i> object. Returns true if the * expressed in the <i>permission</i> object. Returns {@code true} if the
* combination of permissions in the appropriate PermissionCollection * combination of permissions in the appropriate
* (e.g., a FilePermissionCollection for a FilePermission) together * {@code PermissionCollection} (e.g., a {@code FilePermissionCollection}
* imply the specified permission. * for a {@code FilePermission}) together imply the specified permission.
* *
* <p>For example, suppose there is a FilePermissionCollection in this * <p>For example, suppose there is a {@code FilePermissionCollection}
* Permissions object, and it contains one FilePermission that specifies * in this {@code Permissions} object, and it contains one
* "read" access for all files in all subdirectories of the "/tmp" * {@code FilePermission} that specifies "read" access for all files
* directory, and another FilePermission that specifies "write" access * in all subdirectories of the "/tmp" directory, and another
* for all files in the "/tmp/scratch/foo" directory. * {@code FilePermission} that specifies "write" access for all files
* Then if the {@code implies} method * in the "/tmp/scratch/foo" directory. Then if the {@code implies} method
* is called with a permission specifying both "read" and "write" access * is called with a permission specifying both "read" and "write" access
* to files in the "/tmp/scratch/foo" directory, {@code true} is * to files in the "/tmp/scratch/foo" directory, {@code true} is
* returned. * returned.
* *
* <p>Additionally, if this PermissionCollection contains the * <p>Additionally, if this {@code PermissionCollection} contains the
* AllPermission, this method will always return true. * {@code AllPermission}, this method will always return {@code true}.
* *
* @param permission the Permission object to check. * @param permission the {@code Permission} object to check.
* *
* @return true if "permission" is implied by the permissions in the * @return {@code true} if "permission" is implied by the permissions in the
* PermissionCollection it * {@code PermissionCollection} it belongs to, {@code false} if not.
* belongs to, false if not.
*/ */
@Override @Override
public boolean implies(Permission permission) { public boolean implies(Permission permission) {
@ -183,10 +185,10 @@ implements Serializable
} }
/** /**
* Returns an enumeration of all the Permission objects in all the * Returns an enumeration of all the {@code Permission} objects in all the
* PermissionCollections in this Permissions object. * {@code PermissionCollection} objects in this {@code Permissions} object.
* *
* @return an enumeration of all the Permissions. * @return an enumeration of all the {@code Permission} objects.
*/ */
@Override @Override
public Enumeration<Permission> elements() { public Enumeration<Permission> elements() {
@ -197,35 +199,36 @@ implements Serializable
} }
/** /**
* Gets the PermissionCollection in this Permissions object for * Gets the {@code PermissionCollection} in this {@code Permissions}
* permissions whose type is the same as that of <i>p</i>. * object for permissions whose type is the same as that of <i>p</i>.
* For example, if <i>p</i> is a FilePermission, * For example, if <i>p</i> is a {@code FilePermission},
* the FilePermissionCollection * the {@code FilePermissionCollection} stored in this {@code Permissions}
* stored in this Permissions object will be returned. * object will be returned.
* *
* If createEmpty is true, * If {@code createEmpty} is {@code true},
* this method creates a new PermissionCollection object for the specified * this method creates a new {@code PermissionCollection} object for the
* type of permission objects if one does not yet exist. * specified type of permission objects if one does not yet exist.
* To do so, it first calls the {@code newPermissionCollection} method * To do so, it first calls the {@code newPermissionCollection} method
* on <i>p</i>. Subclasses of class Permission * on <i>p</i>. Subclasses of class {@code Permission}
* override that method if they need to store their permissions in a * override that method if they need to store their permissions in a
* particular PermissionCollection object in order to provide the * particular {@code PermissionCollection} object in order to provide the
* correct semantics when the {@code PermissionCollection.implies} * correct semantics when the {@code PermissionCollection.implies}
* method is called. * method is called.
* If the call returns a PermissionCollection, that collection is stored * If the call returns a {@code PermissionCollection}, that collection is
* in this Permissions object. If the call returns null and createEmpty * stored in this {@code Permissions} object. If the call returns
* is true, then * {@code null} and {@code createEmpty} is {@code true}, then this method
* this method instantiates and stores a default PermissionCollection * instantiates and stores a default {@code PermissionCollection}
* that uses a hashtable to store its permission objects. * that uses a hashtable to store its permission objects.
* *
* createEmpty is ignored when creating empty PermissionCollection * {@code createEmpty} is ignored when creating empty
* for unresolved permissions because of the overhead of determining the * {@code PermissionCollection} for unresolved permissions because of the
* PermissionCollection to use. * overhead of determining the {@code PermissionCollection} to use.
* *
* createEmpty should be set to false when this method is invoked from * {@code createEmpty} should be set to {@code false} when this method is
* implies() because it incurs the additional overhead of creating and * invoked from implies() because it incurs the additional overhead of
* adding an empty PermissionCollection that will just return false. * creating and adding an empty {@code PermissionCollection} that will
* It should be set to true when invoked from add(). * just return {@code false}.
* It should be set to {@code true} when invoked from add().
*/ */
private PermissionCollection getPermissionCollection(Permission p, private PermissionCollection getPermissionCollection(Permission p,
boolean createEmpty) { boolean createEmpty) {
@ -281,7 +284,7 @@ implements Serializable
* @param p the type of unresolved permission to resolve * @param p the type of unresolved permission to resolve
* *
* @return PermissionCollection containing the unresolved permissions, * @return PermissionCollection containing the unresolved permissions,
* or null if there were no unresolved permissions of type p. * or {@code null} if there were no unresolved permissions of type p.
* *
*/ */
private PermissionCollection getUnresolvedPermissions(Permission p) private PermissionCollection getUnresolvedPermissions(Permission p)
@ -348,7 +351,8 @@ implements Serializable
/** /**
* @serialField perms java.util.Hashtable * @serialField perms java.util.Hashtable
* A table of the Permission classes and PermissionCollections. * A table of the {@code Permission} classes and
* {@code PermissionCollection} objects.
* @serialField allPermission java.security.PermissionCollection * @serialField allPermission java.security.PermissionCollection
*/ */
@java.io.Serial @java.io.Serial
@ -488,7 +492,8 @@ final class PermissionsEnumerator implements Enumeration<Permission> {
} }
/** /**
* A PermissionsHash stores a homogeneous set of permissions in a hashtable. * A {@code PermissionsHash} stores a homogeneous set of permissions in a
* hashtable.
* *
* @see Permission * @see Permission
* @see Permissions * @see Permissions
@ -509,16 +514,16 @@ implements Serializable
private transient ConcurrentHashMap<Permission, Permission> permsMap; private transient ConcurrentHashMap<Permission, Permission> permsMap;
/** /**
* Create an empty PermissionsHash object. * Create an empty {@code PermissionsHash} object.
*/ */
PermissionsHash() { PermissionsHash() {
permsMap = new ConcurrentHashMap<>(11); permsMap = new ConcurrentHashMap<>(11);
} }
/** /**
* Adds a permission to the PermissionsHash. * Adds a permission to the {@code PermissionsHash}.
* *
* @param permission the Permission object to add. * @param permission the {@code Permission} object to add.
*/ */
@Override @Override
public void add(Permission permission) { public void add(Permission permission) {
@ -529,10 +534,10 @@ implements Serializable
* Check and see if this set of permissions implies the permissions * Check and see if this set of permissions implies the permissions
* expressed in "permission". * expressed in "permission".
* *
* @param permission the Permission object to compare * @param permission the {@code Permission} object to compare
* *
* @return true if "permission" is a proper subset of a permission in * @return {@code true} if "permission" is a proper subset of a permission
* the set, false if not. * in the set, {@code false} if not.
*/ */
@Override @Override
public boolean implies(Permission permission) { public boolean implies(Permission permission) {
@ -553,9 +558,10 @@ implements Serializable
} }
/** /**
* Returns an enumeration of all the Permission objects in the container. * Returns an enumeration of all the {@code Permission} objects in the
* container.
* *
* @return an enumeration of all the Permissions. * @return an enumeration of all the {@code Permission} objects.
*/ */
@Override @Override
public Enumeration<Permission> elements() { public Enumeration<Permission> elements() {
@ -569,7 +575,7 @@ implements Serializable
// private Hashtable perms; // private Hashtable perms;
/** /**
* @serialField perms java.util.Hashtable * @serialField perms java.util.Hashtable
* A table of the Permissions (both key and value are same). * A table of the permissions (both key and value are same).
*/ */
@java.io.Serial @java.io.Serial
private static final ObjectStreamField[] serialPersistentFields = { private static final ObjectStreamField[] serialPersistentFields = {
@ -599,8 +605,8 @@ implements Serializable
} }
/** /**
* Reads in a Hashtable of Permission/Permission and saves them in the * Reads in a {@code Hashtable} of Permission/Permission and saves them
* permsMap field. * in the permsMap field.
* *
* @param in the {@code ObjectInputStream} from which data is read * @param in the {@code ObjectInputStream} from which data is read
* @throws IOException if an I/O error occurs * @throws IOException if an I/O error occurs

125
src/java.base/share/classes/java/security/Policy.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -35,36 +35,36 @@ import sun.security.util.SecurityConstants;
/** /**
* A Policy object is responsible for determining whether code executing * A {@code Policy} object is responsible for determining whether code executing
* in the Java runtime environment has permission to perform a * in the Java runtime environment has permission to perform a
* security-sensitive operation. * security-sensitive operation.
* *
* <p> There is only one Policy object installed in the runtime at any * <p> There is only one {@code Policy} object installed in the runtime at any
* given time. A Policy object can be installed by calling the * given time. A {@code Policy} object can be installed by calling the
* {@code setPolicy} method. The installed Policy object can be * {@code setPolicy} method. The installed {@code Policy} object can be
* obtained by calling the {@code getPolicy} method. * obtained by calling the {@code getPolicy} method.
* *
* <p> If no Policy object has been installed in the runtime, a call to * <p> If no {@code Policy} object has been installed in the runtime, a call to
* {@code getPolicy} installs an instance of the default Policy * {@code getPolicy} installs an instance of the default {@code Policy}
* implementation (a default subclass implementation of this abstract class). * implementation (a default subclass implementation of this abstract class).
* The default Policy implementation can be changed by setting the value * The default {@code Policy} implementation can be changed by setting the value
* of the {@code policy.provider} security property to the fully qualified * of the {@code policy.provider} security property to the fully qualified
* name of the desired Policy subclass implementation. The system class loader * name of the desired {@code Policy} subclass implementation. The system
* is used to load this class. * class loader is used to load this class.
* *
* <p> Application code can directly subclass Policy to provide a custom * <p> Application code can directly subclass {@code Policy} to provide a custom
* implementation. In addition, an instance of a Policy object can be * implementation. In addition, an instance of a {@code Policy} object can be
* constructed by invoking one of the {@code getInstance} factory methods * constructed by invoking one of the {@code getInstance} factory methods
* with a standard type. The default policy type is "JavaPolicy". * with a standard type. The default policy type is "JavaPolicy".
* *
* <p> Once a Policy instance has been installed (either by default, or by * <p> Once a {@code Policy} instance has been installed (either by default,
* calling {@code setPolicy}), the Java runtime invokes its * or by calling {@code setPolicy}), the Java runtime invokes its
* {@code implies} method when it needs to * {@code implies} method when it needs to
* determine whether executing code (encapsulated in a ProtectionDomain) * determine whether executing code (encapsulated in a ProtectionDomain)
* can perform SecurityManager-protected operations. How a Policy object * can perform SecurityManager-protected operations. How a {@code Policy}
* retrieves its policy data is up to the Policy implementation itself. * object retrieves its policy data is up to the {@code Policy} implementation
* The policy data may be stored, for example, in a flat ASCII file, * itself. The policy data may be stored, for example, in a flat ASCII file,
* in a serialized binary file of the Policy class, or in a database. * in a serialized binary file of the {@code Policy} class, or in a database.
* *
* <p> The {@code refresh} method causes the policy object to * <p> The {@code refresh} method causes the policy object to
* refresh/reload its data. This operation is implementation-dependent. * refresh/reload its data. This operation is implementation-dependent.
@ -72,7 +72,7 @@ import sun.security.util.SecurityConstants;
* calling {@code refresh} will cause it to re-read the configuration * calling {@code refresh} will cause it to re-read the configuration
* policy files. If a refresh operation is not supported, this method does * policy files. If a refresh operation is not supported, this method does
* nothing. Note that refreshed policy may not have an effect on classes * nothing. Note that refreshed policy may not have an effect on classes
* in a particular ProtectionDomain. This is dependent on the Policy * in a particular ProtectionDomain. This is dependent on the policy
* provider's implementation of the {@code implies} * provider's implementation of the {@code implies}
* method and its PermissionCollection caching strategy. * method and its PermissionCollection caching strategy.
* *
@ -147,19 +147,19 @@ public abstract class Policy {
} }
/** /**
* Returns the installed Policy object. This value should not be cached, * Returns the installed {@code Policy} object. This value should not be
* as it may be changed by a call to {@code setPolicy}. * cached, as it may be changed by a call to {@code setPolicy}.
* This method first calls * This method first calls
* {@code SecurityManager.checkPermission} with a * {@code SecurityManager.checkPermission} with a
* {@code SecurityPermission("getPolicy")} permission * {@code SecurityPermission("getPolicy")} permission
* to ensure it's ok to get the Policy object. * to ensure it's ok to get the {@code Policy} object.
* *
* @return the installed Policy. * @return the installed Policy.
* *
* @throws SecurityException * @throws SecurityException
* if a security manager exists and its * if a security manager exists and its
* {@code checkPermission} method doesn't allow * {@code checkPermission} method doesn't allow
* getting the Policy object. * getting the {@code Policy} object.
* *
* @see SecurityManager#checkPermission(Permission) * @see SecurityManager#checkPermission(Permission)
* @see #setPolicy(java.security.Policy) * @see #setPolicy(java.security.Policy)
@ -174,10 +174,10 @@ public abstract class Policy {
} }
/** /**
* Returns the installed Policy object, skipping the security check. * Returns the installed {@code Policy} object, skipping the security check.
* Used by ProtectionDomain and getPolicy. * Used by ProtectionDomain and getPolicy.
* *
* @return the installed Policy. * @return the installed {@code Policy}.
*/ */
static Policy getPolicyNoCheck() static Policy getPolicyNoCheck()
{ {
@ -263,12 +263,12 @@ public abstract class Policy {
} }
/** /**
* Sets the system-wide Policy object. This method first calls * Sets the system-wide {@code Policy} object. This method first calls
* {@code SecurityManager.checkPermission} with a * {@code SecurityManager.checkPermission} with a
* {@code SecurityPermission("setPolicy")} * {@code SecurityPermission("setPolicy")}
* permission to ensure it's ok to set the Policy. * permission to ensure it's ok to set the Policy.
* *
* @param p the new system Policy object. * @param p the new system {@code Policy} object.
* *
* @throws SecurityException * @throws SecurityException
* if a security manager exists and its * if a security manager exists and its
@ -365,10 +365,10 @@ public abstract class Policy {
* Returns a Policy object of the specified type. * Returns a Policy object of the specified type.
* *
* <p> This method traverses the list of registered security providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new Policy object encapsulating the * A new {@code Policy} object encapsulating the
* PolicySpi implementation from the first * {@code PolicySpi} implementation from the first
* Provider that supports the specified type is returned. * provider that supports the specified type is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -387,7 +387,8 @@ public abstract class Policy {
* Java Security Standard Algorithm Names Specification</a> * Java Security Standard Algorithm Names Specification</a>
* for a list of standard Policy types. * for a list of standard Policy types.
* *
* @param params parameters for the Policy, which may be null. * @param params parameters for the {@code Policy}, which may be
* {@code null}.
* *
* @return the new {@code Policy} object * @return the new {@code Policy} object
* *
@ -426,10 +427,10 @@ public abstract class Policy {
} }
/** /**
* Returns a Policy object of the specified type. * Returns a {@code Policy} object of the specified type.
* *
* <p> A new Policy object encapsulating the * <p> A new {@code Policy} object encapsulating the
* PolicySpi implementation from the specified provider * {@code PolicySpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the provider list. * in the provider list.
* *
@ -442,7 +443,8 @@ public abstract class Policy {
* Java Security Standard Algorithm Names Specification</a> * Java Security Standard Algorithm Names Specification</a>
* for a list of standard Policy types. * for a list of standard Policy types.
* *
* @param params parameters for the Policy, which may be null. * @param params parameters for the {@code Policy}, which may be
* {@code null}.
* *
* @param provider the provider. * @param provider the provider.
* *
@ -496,12 +498,12 @@ public abstract class Policy {
} }
/** /**
* Returns a Policy object of the specified type. * Returns a {@code Policy} object of the specified type.
* *
* <p> A new Policy object encapsulating the * <p> A new {@code Policy} object encapsulating the
* PolicySpi implementation from the specified Provider * {@code PolicySpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * is returned. Note that the specified provider does not
* does not have to be registered in the provider list. * have to be registered in the provider list.
* *
* @param type the specified Policy type. See the Policy section in the * @param type the specified Policy type. See the Policy section in the
* <a href= * <a href=
@ -509,9 +511,10 @@ public abstract class Policy {
* Java Security Standard Algorithm Names Specification</a> * Java Security Standard Algorithm Names Specification</a>
* for a list of standard Policy types. * for a list of standard Policy types.
* *
* @param params parameters for the Policy, which may be null. * @param params parameters for the {@code Policy}, which may be
* {@code null}.
* *
* @param provider the Provider. * @param provider the {@code Provider}.
* *
* @return the new {@code Policy} object * @return the new {@code Policy} object
* *
@ -569,13 +572,13 @@ public abstract class Policy {
} }
/** /**
* Return the Provider of this Policy. * Return the {@code Provider} of this policy.
* *
* <p> This Policy instance will only have a Provider if it * <p> This {@code Policy} instance will only have a provider if it
* was obtained via a call to {@code Policy.getInstance}. * was obtained via a call to {@code Policy.getInstance}.
* Otherwise this method returns null. * Otherwise this method returns {@code null}.
* *
* @return the Provider of this Policy, or null. * @return the {@code Provider} of this policy, or {@code null}.
* *
* @since 1.6 * @since 1.6
*/ */
@ -584,13 +587,13 @@ public abstract class Policy {
} }
/** /**
* Return the type of this Policy. * Return the type of this {@code Policy}.
* *
* <p> This Policy instance will only have a type if it * <p> This {@code Policy} instance will only have a type if it
* was obtained via a call to {@code Policy.getInstance}. * was obtained via a call to {@code Policy.getInstance}.
* Otherwise this method returns null. * Otherwise this method returns {@code null}.
* *
* @return the type of this Policy, or null. * @return the type of this {@code Policy}, or {@code null}.
* *
* @since 1.6 * @since 1.6
*/ */
@ -599,13 +602,13 @@ public abstract class Policy {
} }
/** /**
* Return Policy parameters. * Return {@code Policy} parameters.
* *
* <p> This Policy instance will only have parameters if it * <p> This {@code Policy} instance will only have parameters if it
* was obtained via a call to {@code Policy.getInstance}. * was obtained via a call to {@code Policy.getInstance}.
* Otherwise this method returns null. * Otherwise this method returns {@code null}.
* *
* @return Policy parameters, or null. * @return {@code Policy} parameters, or {@code null}.
* *
* @since 1.6 * @since 1.6
*/ */
@ -733,7 +736,7 @@ public abstract class Policy {
* @param domain the ProtectionDomain to test * @param domain the ProtectionDomain to test
* @param permission the Permission object to be tested for implication. * @param permission the Permission object to be tested for implication.
* *
* @return true if "permission" is a proper subset of a permission * @return {@code true} if "permission" is a proper subset of a permission
* granted to this ProtectionDomain. * granted to this ProtectionDomain.
* *
* @see java.security.ProtectionDomain * @see java.security.ProtectionDomain
@ -779,8 +782,8 @@ public abstract class Policy {
public void refresh() { } public void refresh() { }
/** /**
* This subclass is returned by the getInstance calls. All Policy calls * This subclass is returned by the getInstance calls. All {@code Policy}
* are delegated to the underlying PolicySpi. * calls are delegated to the underlying {@code PolicySpi}.
*/ */
private static class PolicyDelegate extends Policy { private static class PolicyDelegate extends Policy {
@ -839,7 +842,7 @@ public abstract class Policy {
* This class represents a read-only empty PermissionCollection object that * This class represents a read-only empty PermissionCollection object that
* is returned from the {@code getPermissions(CodeSource)} and * is returned from the {@code getPermissions(CodeSource)} and
* {@code getPermissions(ProtectionDomain)} * {@code getPermissions(ProtectionDomain)}
* methods in the Policy class when those operations are not * methods in the {@code Policy} class when those operations are not
* supported by the Policy implementation. * supported by the Policy implementation.
*/ */
private static class UnsupportedEmptyCollection private static class UnsupportedEmptyCollection
@ -877,8 +880,8 @@ public abstract class Policy {
* *
* @param permission the Permission object to compare. * @param permission the Permission object to compare.
* *
* @return true if "permission" is implied by the permissions in * @return {@code true} if "permission" is implied by the permissions in
* the collection, false if not. * the collection, {@code false} if not.
*/ */
@Override public boolean implies(Permission permission) { @Override public boolean implies(Permission permission) {
return perms.implies(permission); return perms.implies(permission);

8
src/java.base/share/classes/java/security/PolicySpi.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2005, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -30,12 +30,12 @@ package java.security;
* This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
* for the {@code Policy} class. * for the {@code Policy} class.
* All the abstract methods in this class must be implemented by each * All the abstract methods in this class must be implemented by each
* service provider who wishes to supply a Policy implementation. * service provider who wishes to supply a {@code Policy} implementation.
* *
* <p> Subclass implementations of this abstract class must provide * <p> Subclass implementations of this abstract class must provide
* a public constructor that takes a {@code Policy.Parameters} * a public constructor that takes a {@code Policy.Parameters}
* object as an input parameter. This constructor also must throw * object as an input parameter. This constructor also must throw
* an IllegalArgumentException if it does not understand the * an {@code IllegalArgumentException} if it does not understand the
* {@code Policy.Parameters} input. * {@code Policy.Parameters} input.
* *
* *
@ -63,7 +63,7 @@ public abstract class PolicySpi {
* @param permission check whether this permission is granted to the * @param permission check whether this permission is granted to the
* specified domain. * specified domain.
* *
* @return boolean true if the permission is granted to the domain. * @return boolean {@code true} if the permission is granted to the domain.
*/ */
protected abstract boolean engineImplies protected abstract boolean engineImplies
(ProtectionDomain domain, Permission permission); (ProtectionDomain domain, Permission permission);

38
src/java.base/share/classes/java/security/Principal.java
View file

@ -28,7 +28,7 @@ package java.security;
import javax.security.auth.Subject; import javax.security.auth.Subject;
/** /**
* This interface represents the abstract notion of a principal, which * This interface represents the abstract notion of a {@code Principal}, which
* can be used to represent any entity, such as an individual, a * can be used to represent any entity, such as an individual, a
* corporation, and a login id. * corporation, and a login id.
* *
@ -40,52 +40,54 @@ import javax.security.auth.Subject;
public interface Principal { public interface Principal {
/** /**
* Compares this principal to the specified object. Returns true * Compares this {@code Principal} to the specified object.
* if the object passed in matches the principal represented by * Returns {@code true}
* if the object passed in matches the {@code Principal} represented by
* the implementation of this interface. * the implementation of this interface.
* *
* @param another principal to compare with. * @param another {@code Principal} to compare with.
* *
* @return true if the principal passed in is the same as that * @return {@code true} if the {@code Principal} passed in is the same as
* encapsulated by this principal, and false otherwise. * that encapsulated by this {@code Principal}, and {@code false} otherwise.
*/ */
boolean equals(Object another); boolean equals(Object another);
/** /**
* Returns a string representation of this principal. * Returns a string representation of this {@code Principal}.
* *
* @return a string representation of this principal. * @return a string representation of this {@code Principal}.
*/ */
String toString(); String toString();
/** /**
* Returns a hashcode for this principal. * Returns a hashcode for this {@code Principal}.
* *
* @return a hashcode for this principal. * @return a hashcode for this {@code Principal}.
*/ */
int hashCode(); int hashCode();
/** /**
* Returns the name of this principal. * Returns the name of this {@code Principal}.
* *
* @return the name of this principal. * @return the name of this {@code Principal}.
*/ */
String getName(); String getName();
/** /**
* Returns true if the specified subject is implied by this principal. * Returns {@code true} if the specified subject is implied by this
* {@code Principal}.
* *
* @implSpec * @implSpec
* The default implementation of this method returns true if * The default implementation of this method returns {@code true} if
* {@code subject} is non-null and contains at least one principal that * {@code subject} is non-null and contains at least one
* is equal to this principal. * {@code Principal} that is equal to this {@code Principal}.
* *
* <p>Subclasses may override this with a different implementation, if * <p>Subclasses may override this with a different implementation, if
* necessary. * necessary.
* *
* @param subject the {@code Subject} * @param subject the {@code Subject}
* @return true if {@code subject} is non-null and is * @return {@code true} if {@code subject} is non-null and is
* implied by this principal, or false otherwise. * implied by this {@code Principal}, or false otherwise.
* @since 1.8 * @since 1.8
*/ */
default boolean implies(Subject subject) { default boolean implies(Subject subject) {

12
src/java.base/share/classes/java/security/PrivilegedActionException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -53,7 +53,7 @@ public class PrivilegedActionException extends Exception {
private static final long serialVersionUID = 4724086851538908602L; private static final long serialVersionUID = 4724086851538908602L;
/** /**
* Constructs a new PrivilegedActionException &quot;wrapping&quot; * Constructs a new {@code PrivilegedActionException} &quot;wrapping&quot;
* the specific Exception. * the specific Exception.
* *
* @param exception The exception thrown * @param exception The exception thrown
@ -101,13 +101,13 @@ public class PrivilegedActionException extends Exception {
}; };
/** /**
* Reconstitutes the PrivilegedActionException instance from a stream * Reconstitutes the {@code PrivilegedActionException} instance from a
* and initialize the cause properly when deserializing from an older * stream and initialize the cause properly when deserializing from an older
* version. * version.
* *
* <p>The getException and getCause method returns the private "exception" * <p>The getException and getCause method returns the private "exception"
* field in the older implementation and PrivilegedActionException::cause * field in the older implementation and
* was set to null. * {@code PrivilegedActionException::cause} was set to {@code null}.
* *
* @param s the {@code ObjectInputStream} from which data is read * @param s the {@code ObjectInputStream} from which data is read
* @throws IOException if an I/O error occurs * @throws IOException if an I/O error occurs

111
src/java.base/share/classes/java/security/ProtectionDomain.java
View file

@ -41,16 +41,16 @@ import sun.security.util.FilePermCompat;
import sun.security.util.SecurityConstants; import sun.security.util.SecurityConstants;
/** /**
* The ProtectionDomain class encapsulates the characteristics of a domain, * The {@code ProtectionDomain} class encapsulates the characteristics of a
* which encloses a set of classes whose instances are granted a set * 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. * of permissions when being executed on behalf of a given set of Principals.
* <p> * <p>
* A static set of permissions can be bound to a ProtectionDomain when it is * A static set of permissions can be bound to a {@code ProtectionDomain}
* constructed; such permissions are granted to the domain regardless of the * when it is constructed; such permissions are granted to the domain
* Policy in force. However, to support dynamic security policies, a * regardless of the policy in force. However, to support dynamic security
* ProtectionDomain can also be constructed such that it is dynamically * policies, a {@code ProtectionDomain} can also be constructed such that it
* mapped to a set of permissions by the current Policy whenever a permission * is dynamically mapped to a set of permissions by the current policy whenever
* is checked. * a permission is checked.
* *
* @author Li Gong * @author Li Gong
* @author Roland Schemers * @author Roland Schemers
@ -61,8 +61,9 @@ import sun.security.util.SecurityConstants;
public class ProtectionDomain { public class ProtectionDomain {
/** /**
* If true, {@link #impliesWithAltFilePerm} will try to be compatible on * If {@code true}, {@link #impliesWithAltFilePerm} will try to be
* FilePermission checking even if a 3rd-party Policy implementation is set. * compatible on FilePermission checking even if a 3rd-party Policy
* implementation is set.
*/ */
private static final boolean filePermCompatInPD = private static final boolean filePermCompatInPD =
"true".equals(GetPropertyAction.privilegedGetProperty( "true".equals(GetPropertyAction.privilegedGetProperty(
@ -158,15 +159,16 @@ public class ProtectionDomain {
final Key key = new Key(); final Key key = new Key();
/** /**
* Creates a new ProtectionDomain with the given CodeSource and * Creates a new {@code ProtectionDomain} with the given {@code CodeSource}
* Permissions. If the permissions object is not null, then * and permissions. If permissions is not {@code null}, then
* {@code setReadOnly()} will be called on the passed in * {@code setReadOnly()} will be called on the passed in
* Permissions object. * permissions.
* <p> * <p>
* The permissions granted to this domain are static, i.e. * The permissions granted to this domain are static, i.e.
* invoking the {@link #staticPermissionsOnly()} method returns true. * invoking the {@link #staticPermissionsOnly()} method returns
* {@code true}.
* They contain only the ones passed to this constructor and * They contain only the ones passed to this constructor and
* the current Policy will not be consulted. * the current policy will not be consulted.
* *
* @param codesource the codesource associated with this domain * @param codesource the codesource associated with this domain
* @param permissions the permissions granted to this domain * @param permissions the permissions granted to this domain
@ -188,30 +190,31 @@ public class ProtectionDomain {
} }
/** /**
* Creates a new ProtectionDomain qualified by the given CodeSource, * Creates a new {@code ProtectionDomain} qualified by the given
* Permissions, ClassLoader and array of Principals. If the * {@code CodeSource}, permissions, {@code ClassLoader} and array
* permissions object is not null, then {@code setReadOnly()} * of principals. If permissions is not {@code null}, then
* will be called on the passed in Permissions object. * {@code setReadOnly()} will be called on the passed in permissions.
* <p> * <p>
* The permissions granted to this domain are dynamic, i.e. * The permissions granted to this domain are dynamic, i.e.
* invoking the {@link #staticPermissionsOnly()} method returns false. * invoking the {@link #staticPermissionsOnly()} method returns
* {@code false}.
* They include both the static permissions passed to this constructor, * They include both the static permissions passed to this constructor,
* and any permissions granted to this domain by the current Policy at the * and any permissions granted to this domain by the current policy at the
* time a permission is checked. * time a permission is checked.
* <p> * <p>
* This constructor is typically used by * This constructor is typically used by
* {@link SecureClassLoader ClassLoaders} * {@link SecureClassLoader ClassLoaders}
* and {@link DomainCombiner DomainCombiners} which delegate to * and {@link DomainCombiner DomainCombiners} which delegate to the
* {@code Policy} to actively associate the permissions granted to * {@code Policy} object to actively associate the permissions granted to
* this domain. This constructor affords the * this domain. This constructor affords the
* Policy provider the opportunity to augment the supplied * policy provider the opportunity to augment the supplied
* PermissionCollection to reflect policy changes. * {@code PermissionCollection} to reflect policy changes.
* *
* @param codesource the CodeSource associated with this domain * @param codesource the {@code CodeSource} associated with this domain
* @param permissions the permissions granted to this domain * @param permissions the permissions granted to this domain
* @param classloader the ClassLoader associated with this domain * @param classloader the {@code ClassLoader} associated with this domain
* @param principals the array of Principals associated with this * @param principals the array of {@code Principal} objects associated
* domain. The contents of the array are copied to protect against * with this domain. The contents of the array are copied to protect against
* subsequent modification. * subsequent modification.
* @see Policy#refresh * @see Policy#refresh
* @see Policy#getPermissions(ProtectionDomain) * @see Policy#getPermissions(ProtectionDomain)
@ -237,8 +240,8 @@ public class ProtectionDomain {
} }
/** /**
* Returns the CodeSource of this domain. * Returns the {@code CodeSource} of this domain.
* @return the CodeSource of this domain which may be null. * @return the {@code CodeSource} of this domain which may be {@code null}.
* @since 1.2 * @since 1.2
*/ */
public final CodeSource getCodeSource() { public final CodeSource getCodeSource() {
@ -247,8 +250,8 @@ public class ProtectionDomain {
/** /**
* Returns the ClassLoader of this domain. * Returns the {@code ClassLoader} of this domain.
* @return the ClassLoader of this domain which may be null. * @return the {@code ClassLoader} of this domain which may be {@code null}.
* *
* @since 1.4 * @since 1.4
*/ */
@ -271,7 +274,8 @@ public class ProtectionDomain {
/** /**
* Returns the static permissions granted to this domain. * Returns the static permissions granted to this domain.
* *
* @return the static set of permissions for this domain which may be null. * @return the static set of permissions for this domain which may be
* {@code null}.
* @see Policy#refresh * @see Policy#refresh
* @see Policy#getPermissions(ProtectionDomain) * @see Policy#getPermissions(ProtectionDomain)
*/ */
@ -280,11 +284,11 @@ public class ProtectionDomain {
} }
/** /**
* Returns true if this domain contains only static permissions * Returns {@code true} if this domain contains only static permissions
* and does not check the current {@code Policy} at the time of * and does not check the current {@code Policy} at the time of
* permission checking. * permission checking.
* *
* @return true if this domain contains only static permissions. * @return {@code true} if this domain contains only static permissions.
* *
* @since 9 * @since 9
*/ */
@ -293,24 +297,25 @@ public class ProtectionDomain {
} }
/** /**
* Check and see if this ProtectionDomain implies the permissions * Check and see if this {@code ProtectionDomain} implies the permissions
* expressed in the Permission object. * expressed in the {@code Permission} object.
* <p> * <p>
* The set of permissions evaluated is a function of whether the * The set of permissions evaluated is a function of whether the
* ProtectionDomain was constructed with a static set of permissions * {@code ProtectionDomain} was constructed with a static set of permissions
* or it was bound to a dynamically mapped set of permissions. * or it was bound to a dynamically mapped set of permissions.
* <p> * <p>
* If the {@link #staticPermissionsOnly()} method returns * If the {@link #staticPermissionsOnly()} method returns
* true, then the permission will only be checked against the * {@code true}, then the permission will only be checked against the
* PermissionCollection supplied at construction. * {@code PermissionCollection} supplied at construction.
* <p> * <p>
* Otherwise, the permission will be checked against the combination * Otherwise, the permission will be checked against the combination
* of the PermissionCollection supplied at construction and * of the {@code PermissionCollection} supplied at construction and
* the current Policy binding. * the current policy binding.
* *
* @param perm the Permission object to check. * @param perm the {code Permission} object to check.
* *
* @return true if {@code perm} is implied by this ProtectionDomain. * @return {@code true} if {@code perm} is implied by this
* {@code ProtectionDomain}.
*/ */
@SuppressWarnings("removal") @SuppressWarnings("removal")
public boolean implies(Permission perm) { public boolean implies(Permission perm) {
@ -400,7 +405,7 @@ public class ProtectionDomain {
} }
/** /**
* Convert a ProtectionDomain to a String. * Convert a {@code ProtectionDomain} to a {@code String}.
*/ */
@Override public String toString() { @Override public String toString() {
String pals = "<no principals>"; String pals = "<no principals>";
@ -441,18 +446,18 @@ public class ProtectionDomain {
} }
/** /**
* Return true (merge policy permissions) in the following cases: * Return {@code true} (merge policy permissions) in the following cases:
* *
* . SecurityManager is null * . SecurityManager is {@code null}
* *
* . SecurityManager is not null, * . SecurityManager is not {@code null},
* debug is not null, * debug is not {@code null},
* SecurityManager implementation is in bootclasspath, * SecurityManager implementation is in bootclasspath,
* Policy implementation is in bootclasspath * Policy implementation is in bootclasspath
* (the bootclasspath restrictions avoid recursion) * (the bootclasspath restrictions avoid recursion)
* *
* . SecurityManager is not null, * . SecurityManager is not {@code null},
* debug is null, * debug is {@code null},
* caller has Policy.getPolicy permission * caller has Policy.getPolicy permission
*/ */
@SuppressWarnings("removal") @SuppressWarnings("removal")

126
src/java.base/share/classes/java/security/Provider.java
View file

@ -171,7 +171,7 @@ public abstract class Provider extends Properties {
} }
/** /**
* Constructs a provider with the specified name, version number, * Constructs a {@code Provider} with the specified name, version number,
* and information. Calling this constructor is equivalent to call the * and information. Calling this constructor is equivalent to call the
* {@link #Provider(String, String, String)} with {@code name} * {@link #Provider(String, String, String)} with {@code name}
* name, {@code Double.toString(version)}, and {@code info}. * name, {@code Double.toString(version)}, and {@code info}.
@ -198,7 +198,7 @@ public abstract class Provider extends Properties {
} }
/** /**
* Constructs a provider with the specified name, version string, * Constructs a {@code Provider} with the specified name, version string,
* and information. * and information.
* *
* <p>The version string contains a version number optionally followed * <p>The version string contains a version number optionally followed
@ -238,10 +238,11 @@ public abstract class Provider extends Properties {
} }
/** /**
* Apply the supplied configuration argument to this provider instance * Apply the supplied configuration argument to this {@code Provider}
* and return the configured provider. Note that if this provider cannot * instance and return the configured {@code Provider}. Note that if
* be configured in-place, a new provider will be created and returned. * this {@code Provider} cannot be configured in-place, a new
* Therefore, callers should always use the returned provider. * {@code Provider} will be created and returned. Therefore,
* callers should always use the returned {@code Provider}.
* *
* @implSpec * @implSpec
* The default implementation throws {@code UnsupportedOperationException}. * The default implementation throws {@code UnsupportedOperationException}.
@ -254,10 +255,11 @@ public abstract class Provider extends Properties {
* @throws UnsupportedOperationException if a configuration argument is * @throws UnsupportedOperationException if a configuration argument is
* not supported. * not supported.
* @throws NullPointerException if the supplied configuration argument is * @throws NullPointerException if the supplied configuration argument is
* null. * {@code null}.
* @throws InvalidParameterException if the supplied configuration argument * @throws InvalidParameterException if the supplied configuration argument
* is invalid. * is invalid.
* @return a provider configured with the supplied configuration argument. * @return a {@code Provider} configured with the supplied configuration
* argument.
* *
* @since 9 * @since 9
*/ */
@ -266,14 +268,15 @@ public abstract class Provider extends Properties {
} }
/** /**
* Check if this provider instance has been configured. * Check if this {@code Provider} instance has been configured.
* *
* @implSpec * @implSpec
* The default implementation returns true. * The default implementation returns {@code true}.
* Subclasses should override this method if the provider instance requires * Subclasses should override this method if the {@code Provider} requires
* an explicit {@code configure} call after being constructed. * an explicit {@code configure} call after being constructed.
* *
* @return true if no further configuration is needed, false otherwise. * @return {@code true} if no further configuration is needed,
* {@code false} otherwise.
* *
* @since 9 * @since 9
*/ */
@ -283,18 +286,18 @@ public abstract class Provider extends Properties {
/** /**
* Returns the name of this provider. * Returns the name of this {@code Provider}.
* *
* @return the name of this provider. * @return the name of this {@code Provider}.
*/ */
public String getName() { public String getName() {
return name; return name;
} }
/** /**
* Returns the version number for this provider. * Returns the version number for this {@code Provider}.
* *
* @return the version number for this provider. * @return the version number for this {@code Provider}.
* *
* @deprecated use {@link #getVersionStr} instead. * @deprecated use {@link #getVersionStr} instead.
*/ */
@ -304,9 +307,9 @@ public abstract class Provider extends Properties {
} }
/** /**
* Returns the version string for this provider. * Returns the version string for this {@code Provider}.
* *
* @return the version string for this provider. * @return the version string for this {@code Provider}.
* *
* @since 9 * @since 9
*/ */
@ -315,10 +318,10 @@ public abstract class Provider extends Properties {
} }
/** /**
* Returns a human-readable description of the provider and its * Returns a human-readable description of the {@code Provider} and its
* services. This may return an HTML page, with relevant links. * services. This may return an HTML page, with relevant links.
* *
* @return a description of the provider and its services. * @return a description of the {@code Provider} and its services.
*/ */
public String getInfo() { public String getInfo() {
return info; return info;
@ -326,10 +329,10 @@ public abstract class Provider extends Properties {
/** /**
* Returns a string with the name and the version string * Returns a string with the name and the version string
* of this provider. * of this {@code Provider}.
* *
* @return the string with the name and the version string * @return the string with the name and the version string
* for this provider. * for this {@code Provider}.
*/ */
public String toString() { public String toString() {
return name + " version " + versionStr; return name + " version " + versionStr;
@ -342,8 +345,8 @@ public abstract class Provider extends Properties {
*/ */
/** /**
* Clears this provider so that it no longer contains the properties * Clears this {@code Provider} so that it no longer contains the properties
* used to look up facilities implemented by the provider. * used to look up facilities implemented by the {@code Provider}.
* *
* <p>If a security manager is enabled, its {@code checkSecurityAccess} * <p>If a security manager is enabled, its {@code checkSecurityAccess}
* method is called with the string {@code "clearProviderProperties."+name} * method is called with the string {@code "clearProviderProperties."+name}
@ -386,8 +389,8 @@ public abstract class Provider extends Properties {
} }
/** /**
* Copies all the mappings from the specified Map to this provider. * Copies all the mappings from the specified Map to this {@code Provider}.
* These mappings will replace any properties that this provider had * These mappings will replace any properties that this {@code Provider} had
* for any of the keys currently in the specified Map. * for any of the keys currently in the specified Map.
* *
* @since 1.2 * @since 1.2
@ -403,7 +406,7 @@ public abstract class Provider extends Properties {
/** /**
* Returns an unmodifiable Set view of the property entries contained * Returns an unmodifiable Set view of the property entries contained
* in this Provider. * in this {@code Provider}.
* *
* @see java.util.Map.Entry * @see java.util.Map.Entry
* @since 1.2 * @since 1.2
@ -431,7 +434,7 @@ public abstract class Provider extends Properties {
/** /**
* Returns an unmodifiable Set view of the property keys contained in * Returns an unmodifiable Set view of the property keys contained in
* this provider. * this {@code Provider}.
* *
* @since 1.2 * @since 1.2
*/ */
@ -443,7 +446,7 @@ public abstract class Provider extends Properties {
/** /**
* Returns an unmodifiable Collection view of the property values * Returns an unmodifiable Collection view of the property values
* contained in this provider. * contained in this {@code Provider}.
* *
* @since 1.2 * @since 1.2
*/ */
@ -727,10 +730,10 @@ public abstract class Provider extends Properties {
/** /**
* If the specified key is not already associated with a value or is * If the specified key is not already associated with a value or is
* associated with null, associates it with the given value. Otherwise, * associated with {@code null}, associates it with the given value.
* replaces the value with the results of the given remapping function, * Otherwise, replaces the value with the results of the given remapping
* or removes if the result is null. This method may be of use when * function, or removes if the result is {@code null}. This method may be
* combining multiple mapped values for a key. * of use when combining multiple mapped values for a key.
* *
* <p>If a security manager is enabled, its {@code checkSecurityAccess} * <p>If a security manager is enabled, its {@code checkSecurityAccess}
* method is called with the strings {@code "putProviderProperty."+name} * method is called with the strings {@code "putProviderProperty."+name}
@ -856,9 +859,10 @@ public abstract class Provider extends Properties {
/** /**
* Reads the {@code ObjectInputStream} for the default serializable fields. * Reads the {@code ObjectInputStream} for the default serializable fields.
* If the serialized field {@code versionStr} is found in the STREAM FIELDS, * If the serialized field {@code versionStr} is found in the STREAM FIELDS,
* its String value will be used to populate both the version string and * its {@code String} value will be used to populate both the version string
* version number. If {@code versionStr} is not found, but {@code version} * and version number. If {@code versionStr} is not found, but
* is, then its double value will be used to populate both fields. * {@code version} is, then its double value will be used to populate
* both fields.
* *
* @param in the {@code ObjectInputStream} to read * @param in the {@code ObjectInputStream} to read
* @throws IOException if an I/O error occurs * @throws IOException if an I/O error occurs
@ -1250,7 +1254,7 @@ public abstract class Provider extends Properties {
/** /**
* Get the service describing this Provider's implementation of the * Get the service describing this Provider's implementation of the
* specified type of this algorithm or alias. If no such * specified type of this algorithm or alias. If no such
* implementation exists, this method returns null. If there are two * implementation exists, this method returns {@code null}. If there are two
* matching services, one added to this provider using * matching services, one added to this provider using
* {@link #putService putService()} and one added via {@link #put put()}, * {@link #putService putService()} and one added via {@link #put put()},
* the service added via {@link #putService putService()} is returned. * the service added via {@link #putService putService()} is returned.
@ -1261,9 +1265,9 @@ public abstract class Provider extends Properties {
* alias) of the service requested (for example, {@code SHA-1}) * alias) of the service requested (for example, {@code SHA-1})
* *
* @return the service describing this Provider's matching service * @return the service describing this Provider's matching service
* or null if no such service exists * or {@code null} if no such service exists
* *
* @throws NullPointerException if type or algorithm is null * @throws NullPointerException if type or algorithm is {@code null}
* *
* @since 1.5 * @since 1.5
*/ */
@ -1302,10 +1306,10 @@ public abstract class Provider extends Properties {
/** /**
* Get an unmodifiable Set of all services supported by * Get an unmodifiable Set of all services supported by
* this Provider. * this {@code Provider}.
* *
* @return an unmodifiable Set of all services supported by * @return an unmodifiable Set of all services supported by
* this Provider * this {@code Provider}
* *
* @since 1.5 * @since 1.5
*/ */
@ -1351,7 +1355,7 @@ public abstract class Provider extends Properties {
* if a security manager exists and its {@link * if a security manager exists and its {@link
* java.lang.SecurityManager#checkSecurityAccess} method denies * java.lang.SecurityManager#checkSecurityAccess} method denies
* access to set property values. * access to set property values.
* @throws NullPointerException if s is null * @throws NullPointerException if s is {@code null}
* *
* @since 1.5 * @since 1.5
*/ */
@ -1452,7 +1456,7 @@ public abstract class Provider extends Properties {
/** /**
* Remove a service previously added using * Remove a service previously added using
* {@link #putService putService()}. The specified service is removed from * {@link #putService putService()}. The specified service is removed from
* this provider. It will no longer be returned by * this {@code Provider}. It will no longer be returned by
* {@link #getService getService()} and its information will be removed * {@link #getService getService()} and its information will be removed
* from this provider's Hashtable. * from this provider's Hashtable.
* *
@ -1473,7 +1477,7 @@ public abstract class Provider extends Properties {
* if a security manager exists and its {@link * if a security manager exists and its {@link
* java.lang.SecurityManager#checkSecurityAccess} method denies * java.lang.SecurityManager#checkSecurityAccess} method denies
* access to remove this provider's properties. * access to remove this provider's properties.
* @throws NullPointerException if s is null * @throws NullPointerException if s is {@code null}
* *
* @since 1.5 * @since 1.5
*/ */
@ -1627,7 +1631,7 @@ public abstract class Provider extends Properties {
* an algorithm name, and the name of the class that implements the * an algorithm name, and the name of the class that implements the
* service. Optionally, it also includes a list of alternate algorithm * service. Optionally, it also includes a list of alternate algorithm
* names for this service (aliases) and attributes, which are a map of * names for this service (aliases) and attributes, which are a map of
* (name, value) String pairs. * (name, value) {@code String} pairs.
* *
* <p>This class defines the methods {@link #supportsParameter * <p>This class defines the methods {@link #supportsParameter
* supportsParameter()} and {@link #newInstance newInstance()} * supportsParameter()} and {@link #newInstance newInstance()}
@ -1737,12 +1741,13 @@ public abstract class Provider extends Properties {
* @param type the type of this service * @param type the type of this service
* @param algorithm the algorithm name * @param algorithm the algorithm name
* @param className the name of the class implementing this service * @param className the name of the class implementing this service
* @param aliases List of aliases or null if algorithm has no aliases * @param aliases List of aliases or {@code null} if algorithm has no
* @param attributes Map of attributes or null if this implementation * aliases
* has no attributes * @param attributes Map of attributes or {@code null} if this
* implementation has no attributes
* *
* @throws NullPointerException if provider, type, algorithm, or * @throws NullPointerException if provider, type, algorithm, or
* className is null * className is {@code null}
*/ */
public Service(Provider provider, String type, String algorithm, public Service(Provider provider, String type, String algorithm,
String className, List<String> aliases, String className, List<String> aliases,
@ -1814,15 +1819,15 @@ public abstract class Provider extends Properties {
} }
/** /**
* Return the value of the specified attribute or null if this * Return the value of the specified attribute or {@code null} if this
* attribute is not set for this Service. * attribute is not set for this Service.
* *
* @param name the name of the requested attribute * @param name the name of the requested attribute
* *
* @return the value of the specified attribute or null if the * @return the value of the specified attribute or {@code null} if the
* attribute is not present * attribute is not present
* *
* @throws NullPointerException if name is null * @throws NullPointerException if name is {@code null}
*/ */
public final String getAttribute(String name) { public final String getAttribute(String name) {
if (name == null) { if (name == null) {
@ -1847,7 +1852,8 @@ public abstract class Provider extends Properties {
* Java Cryptography Architecture (JCA) Reference Guide}. * Java Cryptography Architecture (JCA) Reference Guide}.
* *
* @param constructorParameter the value to pass to the constructor, * @param constructorParameter the value to pass to the constructor,
* or null if this type of service does not use a constructorParameter. * or {@code null} if this type of service does not use a
* constructorParameter.
* *
* @return a new implementation of this service * @return a new implementation of this service
* *
@ -2008,9 +2014,9 @@ public abstract class Provider extends Properties {
/** /**
* Test whether this Service can use the specified parameter. * Test whether this Service can use the specified parameter.
* Returns false if this service cannot use the parameter. Returns * Returns {@code false} if this service cannot use the parameter.
* true if this service can use the parameter, if a fast test is * Returns {@code true} if this service can use the parameter,
* infeasible, or if the status is unknown. * if a fast test is infeasible, or if the status is unknown.
* *
* <p>The security provider framework uses this method with * <p>The security provider framework uses this method with
* some types of services to quickly exclude non-matching * some types of services to quickly exclude non-matching
@ -2025,8 +2031,8 @@ public abstract class Provider extends Properties {
* *
* @param parameter the parameter to test * @param parameter the parameter to test
* *
* @return false if this service cannot use the specified * @return {@code false} if this service cannot use the specified
* parameter; true if it can possibly use the parameter * parameter; {@code true} if it can possibly use the parameter
* *
* @throws InvalidParameterException if the value of parameter is * @throws InvalidParameterException if the value of parameter is
* invalid for this type of service or if this method cannot be * invalid for this type of service or if this method cannot be
@ -2145,9 +2151,9 @@ public abstract class Provider extends Properties {
} }
/** /**
* Return a String representation of this service. * Return a {@code String} representation of this service.
* *
* @return a String representation of this service. * @return a {@code String} representation of this service.
*/ */
public String toString() { public String toString() {
String aString = aliases.isEmpty() String aString = aliases.isEmpty()

12
src/java.base/share/classes/java/security/ProviderException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -26,7 +26,7 @@
package java.security; package java.security;
/** /**
* A runtime exception for Provider exceptions (such as * A runtime exception for {@code Provider} exceptions (such as
* misconfiguration errors or unrecoverable internal errors), * misconfiguration errors or unrecoverable internal errors),
* which may be subclassed by Providers to * which may be subclassed by Providers to
* throw specialized, provider-specific runtime errors. * throw specialized, provider-specific runtime errors.
@ -40,8 +40,8 @@ public class ProviderException extends RuntimeException {
private static final long serialVersionUID = 5256023526693665674L; private static final long serialVersionUID = 5256023526693665674L;
/** /**
* Constructs a ProviderException with no detail message. A * Constructs a {@code ProviderException} with no detail message. A
* detail message is a String that describes this particular * detail message is a {@code String} that describes this particular
* exception. * exception.
*/ */
public ProviderException() { public ProviderException() {
@ -49,8 +49,8 @@ public class ProviderException extends RuntimeException {
} }
/** /**
* Constructs a ProviderException with the specified detail * Constructs a {@code ProviderException} with the specified detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
* *
* @param s the detail message. * @param s the detail message.

10
src/java.base/share/classes/java/security/SecureClassLoader.java
View file

@ -32,7 +32,7 @@ import java.util.Objects;
import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentHashMap;
/** /**
* This class extends ClassLoader with additional support for defining * This class extends {@code ClassLoader} with additional support for defining
* classes with an associated code source and permissions which are * classes with an associated code source and permissions which are
* retrieved by the system policy by default. * retrieved by the system policy by default.
* *
@ -44,7 +44,7 @@ public class SecureClassLoader extends ClassLoader {
/* /*
* Map that maps the CodeSource to a ProtectionDomain. The key is a * Map that maps the CodeSource to a ProtectionDomain. The key is a
* CodeSourceKey class that uses a String instead of a URL to avoid * CodeSourceKey class that uses a {@code String} instead of a URL to avoid
* potential expensive name service lookups. This does mean that URLs that * potential expensive name service lookups. This does mean that URLs that
* are equivalent after nameservice lookup will be placed in separate * are equivalent after nameservice lookup will be placed in separate
* ProtectionDomains; however during policy enforcement these URLs will be * ProtectionDomains; however during policy enforcement these URLs will be
@ -59,7 +59,7 @@ public class SecureClassLoader extends ClassLoader {
} }
/** /**
* Creates a new SecureClassLoader using the specified parent * Creates a new {@code SecureClassLoader} using the specified parent
* class loader for delegation. * class loader for delegation.
* *
* <p>If there is a security manager, this method first * <p>If there is a security manager, this method first
@ -77,7 +77,7 @@ public class SecureClassLoader extends ClassLoader {
} }
/** /**
* Creates a new SecureClassLoader using the default parent class * Creates a new {@code SecureClassLoader} using the default parent class
* loader for delegation. * loader for delegation.
* *
* <p>If there is a security manager, this method first * <p>If there is a security manager, this method first
@ -113,7 +113,7 @@ public class SecureClassLoader extends ClassLoader {
} }
/** /**
* Converts an array of bytes into an instance of class Class, * Converts an array of bytes into an instance of class {@code Class},
* with an optional CodeSource. Before the * with an optional CodeSource. Before the
* class can be used it must be resolved. * class can be used it must be resolved.
* <p> * <p>

31
src/java.base/share/classes/java/security/SecureRandom.java
View file

@ -202,9 +202,9 @@ public class SecureRandom extends java.util.Random {
* <p> This constructor traverses the list of registered security Providers, * <p> This constructor traverses the list of registered security Providers,
* starting with the most preferred Provider. * starting with the most preferred Provider.
* A new {@code SecureRandom} object encapsulating the * A new {@code SecureRandom} object encapsulating the
* {@code SecureRandomSpi} implementation from the first * {@code SecureRandomSpi} implementation from the first provider
* Provider that supports a {@code SecureRandom} (RNG) algorithm is returned. * that supports a {@code SecureRandom} (RNG) algorithm is returned.
* If none of the Providers support an RNG algorithm, * If none of the providers support an RNG algorithm,
* then an implementation-specific default is returned. * then an implementation-specific default is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
@ -243,9 +243,9 @@ public class SecureRandom extends java.util.Random {
* <p> This constructor traverses the list of registered security Providers, * <p> This constructor traverses the list of registered security Providers,
* starting with the most preferred Provider. * starting with the most preferred Provider.
* A new {@code SecureRandom} object encapsulating the * A new {@code SecureRandom} object encapsulating the
* {@code SecureRandomSpi} implementation from the first * {@code SecureRandomSpi} implementation from the first provider
* Provider that supports a {@code SecureRandom} (RNG) algorithm is returned. * that supports a {@code SecureRandom} (RNG) algorithm is returned.
* If none of the Providers support an RNG algorithm, * If none of the providers support an RNG algorithm,
* then an implementation-specific default is returned. * then an implementation-specific default is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
@ -350,7 +350,7 @@ public class SecureRandom extends java.util.Random {
* starting with the most preferred Provider. * starting with the most preferred Provider.
* A new {@code SecureRandom} object encapsulating the * A new {@code SecureRandom} object encapsulating the
* {@code SecureRandomSpi} implementation from the first * {@code SecureRandomSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -442,9 +442,9 @@ public class SecureRandom extends java.util.Random {
* Random Number Generator (RNG) algorithm. * Random Number Generator (RNG) algorithm.
* *
* <p> A new {@code SecureRandom} object encapsulating the * <p> A new {@code SecureRandom} object encapsulating the
* {@code SecureRandomSpi} implementation from the specified {@code Provider} * {@code SecureRandomSpi} implementation from the specified provider
* object is returned. Note that the specified {@code Provider} object * is returned. Note that the specified provider does not
* does not have to be registered in the provider list. * have to be registered in the provider list.
* *
* @param algorithm the name of the RNG algorithm. * @param algorithm the name of the RNG algorithm.
* See the {@code SecureRandom} section in the <a href= * See the {@code SecureRandom} section in the <a href=
@ -483,11 +483,11 @@ public class SecureRandom extends java.util.Random {
* Random Number Generator (RNG) algorithm and supports the specified * Random Number Generator (RNG) algorithm and supports the specified
* {@code SecureRandomParameters} request. * {@code SecureRandomParameters} request.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new {@code SecureRandom} object encapsulating the * A new {@code SecureRandom} object encapsulating the
* {@code SecureRandomSpi} implementation from the first * {@code SecureRandomSpi} implementation from the first
* Provider that supports the specified algorithm and the specified * provider that supports the specified algorithm and the specified
* {@code SecureRandomParameters} is returned. * {@code SecureRandomParameters} is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
@ -599,9 +599,8 @@ public class SecureRandom extends java.util.Random {
* *
* <p> A new {@code SecureRandom} object encapsulating the * <p> A new {@code SecureRandom} object encapsulating the
* {@code SecureRandomSpi} implementation from the specified * {@code SecureRandomSpi} implementation from the specified
* {@code Provider} object is returned. Note that the specified * provider is returned. Note that the specified provider
* {@code Provider} object does not have to be registered in the * does not have to be registered in the provider list.
* provider list.
* *
* @param algorithm the name of the RNG algorithm. * @param algorithm the name of the RNG algorithm.
* See the {@code SecureRandom} section in the <a href= * See the {@code SecureRandom} section in the <a href=

66
src/java.base/share/classes/java/security/Security.java
View file

@ -345,7 +345,7 @@ public final class Security {
* added, or -1 if the provider was not added because it is * added, or -1 if the provider was not added because it is
* already installed. * already installed.
* *
* @throws NullPointerException if provider is null * @throws NullPointerException if provider is {@code null}
* @throws SecurityException * @throws SecurityException
* if a security manager exists and its {@link * if a security manager exists and its {@link
* java.lang.SecurityManager#checkSecurityAccess} method * java.lang.SecurityManager#checkSecurityAccess} method
@ -385,7 +385,7 @@ public final class Security {
* added, or -1 if the provider was not added because it is * added, or -1 if the provider was not added because it is
* already installed. * already installed.
* *
* @throws NullPointerException if provider is null * @throws NullPointerException if provider is {@code null}
* @throws SecurityException * @throws SecurityException
* if a security manager exists and its {@link * if a security manager exists and its {@link
* java.lang.SecurityManager#checkSecurityAccess} method * java.lang.SecurityManager#checkSecurityAccess} method
@ -414,7 +414,7 @@ public final class Security {
* providers). * providers).
* *
* <p>This method returns silently if the provider is not installed or * <p>This method returns silently if the provider is not installed or
* if name is null. * if name is {@code null}.
* *
* <p>First, if there is a security manager, its * <p>First, if there is a security manager, its
* {@code checkSecurityAccess} * {@code checkSecurityAccess}
@ -456,8 +456,8 @@ public final class Security {
/** /**
* Returns the provider installed with the specified name, if * Returns the provider installed with the specified name, if
* any. Returns null if no provider with the specified name is * any. Returns {@code null} if no provider with the specified name is
* installed or if name is null. * installed or if name is {@code null}.
* *
* @param name the name of the provider to get. * @param name the name of the provider to get.
* *
@ -472,8 +472,8 @@ public final class Security {
/** /**
* Returns an array containing all installed providers that satisfy the * Returns an array containing all installed providers that satisfy the
* specified selection criterion, or null if no such providers have been * specified selection criterion, or {@code null} if no such providers
* installed. The returned providers are ordered * have been installed. The returned providers are ordered
* according to their * according to their
* {@linkplain #insertProviderAt(java.security.Provider, int) preference order}. * {@linkplain #insertProviderAt(java.security.Provider, int) preference order}.
* *
@ -521,11 +521,11 @@ public final class Security {
* providers. The filter is case-insensitive. * providers. The filter is case-insensitive.
* *
* @return all the installed providers that satisfy the selection * @return all the installed providers that satisfy the selection
* criterion, or null if no such providers have been installed. * criterion, or {@code null} if no such providers have been installed.
* *
* @throws InvalidParameterException * @throws InvalidParameterException
* if the filter is not in the required format * if the filter is not in the required format
* @throws NullPointerException if filter is null * @throws NullPointerException if filter is {@code null}
* *
* @see #getProviders(java.util.Map) * @see #getProviders(java.util.Map)
* @since 1.3 * @since 1.3
@ -551,8 +551,8 @@ public final class Security {
/** /**
* Returns an array containing all installed providers that satisfy the * Returns an array containing all installed providers that satisfy the
* specified selection criteria, or null if no such providers have been * specified selection criteria, or {@code null} if no such providers have
* installed. The returned providers are ordered * been installed. The returned providers are ordered
* according to their * according to their
* {@linkplain #insertProviderAt(java.security.Provider, int) * {@linkplain #insertProviderAt(java.security.Provider, int)
* preference order}. * preference order}.
@ -592,11 +592,11 @@ public final class Security {
* providers. The filter is case-insensitive. * providers. The filter is case-insensitive.
* *
* @return all the installed providers that satisfy the selection * @return all the installed providers that satisfy the selection
* criteria, or null if no such providers have been installed. * criteria, or {@code null} if no such providers have been installed.
* *
* @throws InvalidParameterException * @throws InvalidParameterException
* if the filter is not in the required format * if the filter is not in the required format
* @throws NullPointerException if filter is null * @throws NullPointerException if filter is {@code null}
* *
* @see #getProviders(java.lang.String) * @see #getProviders(java.lang.String)
* @since 1.3 * @since 1.3
@ -673,7 +673,7 @@ public final class Security {
* an instance of an implementation of the requested algorithm * an instance of an implementation of the requested algorithm
* and type, and the second object in the array identifies the provider * and type, and the second object in the array identifies the provider
* of that implementation. * of that implementation.
* The {@code provider} argument can be null, in which case all * The {@code provider} argument can be {@code null}, in which case all
* configured providers will be searched in order of preference. * configured providers will be searched in order of preference.
*/ */
static Object[] getImpl(String algorithm, String type, String provider) static Object[] getImpl(String algorithm, String type, String provider)
@ -704,7 +704,7 @@ public final class Security {
* an instance of an implementation of the requested algorithm * an instance of an implementation of the requested algorithm
* and type, and the second object in the array identifies the provider * and type, and the second object in the array identifies the provider
* of that implementation. * of that implementation.
* The {@code provider} argument cannot be null. * The {@code provider} argument cannot be {@code null}.
*/ */
static Object[] getImpl(String algorithm, String type, Provider provider) static Object[] getImpl(String algorithm, String type, Provider provider)
throws NoSuchAlgorithmException { throws NoSuchAlgorithmException {
@ -737,7 +737,7 @@ public final class Security {
* java.lang.SecurityManager#checkPermission} method * java.lang.SecurityManager#checkPermission} method
* denies * denies
* access to retrieve the specified security property value * access to retrieve the specified security property value
* @throws NullPointerException is key is null * @throws NullPointerException is key is {@code null}
* *
* @see #setProperty * @see #setProperty
* @see java.security.SecurityPermission * @see java.security.SecurityPermission
@ -772,7 +772,7 @@ public final class Security {
* if a security manager exists and its {@link * if a security manager exists and its {@link
* java.lang.SecurityManager#checkPermission} method * java.lang.SecurityManager#checkPermission} method
* denies access to set the specified security property value * denies access to set the specified security property value
* @throws NullPointerException if key or datum is null * @throws NullPointerException if key or datum is {@code null}
* *
* @see #getProperty * @see #getProperty
* @see java.security.SecurityPermission * @see java.security.SecurityPermission
@ -876,7 +876,7 @@ public final class Security {
} }
/* /*
* Returns true if the given provider satisfies * Returns {@code true} if the given provider satisfies
* the selection criterion key:value. * the selection criterion key:value.
*/ */
private static boolean isCriterionSatisfied(Provider prov, private static boolean isCriterionSatisfied(Provider prov,
@ -935,8 +935,8 @@ public final class Security {
} }
/* /*
* Returns true if the attribute is a standard attribute; * Returns {@code true} if the attribute is a standard attribute;
* otherwise, returns false. * otherwise, returns {@code false}.
*/ */
private static boolean isStandardAttr(String attribute) { private static boolean isStandardAttr(String attribute) {
// For now, we just have two standard attributes: // For now, we just have two standard attributes:
@ -948,8 +948,8 @@ public final class Security {
} }
/* /*
* Returns true if the requested attribute value is supported; * Returns {@code true} if the requested attribute value is supported;
* otherwise, returns false. * otherwise, returns {@code false}.
*/ */
private static boolean isConstraintSatisfied(String attribute, private static boolean isConstraintSatisfied(String attribute,
String value, String value,
@ -1027,23 +1027,25 @@ public final class Security {
} }
/** /**
* Returns a Set of Strings containing the names of all available * Returns a Set of {@code String} objects containing the names of all
* algorithms or types for the specified Java cryptographic service * available algorithms or types for the specified Java cryptographic
* (e.g., Signature, MessageDigest, Cipher, Mac, KeyStore). Returns * service (e.g., {@code Signature}, {@code MessageDigest}, {@code Cipher},
* an empty Set if there is no provider that supports the * {@code Mac}, {@code KeyStore}).
* specified service or if serviceName is null. For a complete list * Returns an empty set if there is no provider that supports the
* of Java cryptographic services, please see the * specified service or if {@code serviceName} is {@code null}.
* For a complete list of Java cryptographic services, please see the
* {@extLink security_guide_jca * {@extLink security_guide_jca
* Java Cryptography Architecture (JCA) Reference Guide}. * Java Cryptography Architecture (JCA) Reference Guide}.
* Note: the returned set is immutable. * Note: the returned set is immutable.
* *
* @param serviceName the name of the Java cryptographic * @param serviceName the name of the Java cryptographic
* service (e.g., Signature, MessageDigest, Cipher, Mac, KeyStore). * service (e.g., {@code Signature}, {@code MessageDigest}, {@code Cipher},
* {@code Mac}, {@code KeyStore}).
* Note: this parameter is case-insensitive. * Note: this parameter is case-insensitive.
* *
* @return a Set of Strings containing the names of all available * @return a Set of {@code String} objects containing the names of all
* algorithms or types for the specified Java cryptographic service * available algorithms or types for the specified Java cryptographic
* or an empty set if no provider supports the specified service. * service or an empty set if no provider supports the specified service.
* *
* @since 1.4 * @since 1.4
*/ */

20
src/java.base/share/classes/java/security/SecurityPermission.java
View file

@ -334,12 +334,12 @@ public final class SecurityPermission extends BasicPermission {
private static final long serialVersionUID = 5236109936224050470L; private static final long serialVersionUID = 5236109936224050470L;
/** /**
* Creates a new SecurityPermission with the specified name. * Creates a new {@code SecurityPermission} with the specified name.
* The name is the symbolic name of the SecurityPermission. An asterisk * The name is the symbolic name of the {@code SecurityPermission}.
* may appear at the end of the name, following a ".", or by itself, to * An asterisk may appear at the end of the name, following a ".",
* signify a wildcard match. * or by itself, to signify a wildcard match.
* *
* @param name the name of the SecurityPermission * @param name the name of the {@code SecurityPermission}
* *
* @throws NullPointerException if {@code name} is {@code null}. * @throws NullPointerException if {@code name} is {@code null}.
* @throws IllegalArgumentException if {@code name} is empty. * @throws IllegalArgumentException if {@code name} is empty.
@ -350,12 +350,12 @@ public final class SecurityPermission extends BasicPermission {
} }
/** /**
* Creates a new SecurityPermission object with the specified name. * Creates a new {@code SecurityPermission} object with the specified name.
* The name is the symbolic name of the SecurityPermission, and the * The name is the symbolic name of the {@code SecurityPermission}, and the
* actions String is currently unused and should be null. * actions {@code String} is currently unused and should be {@code null}.
* *
* @param name the name of the SecurityPermission * @param name the name of the {@code SecurityPermission}
* @param actions should be null. * @param actions should be {@code null}.
* *
* @throws NullPointerException if {@code name} is {@code null}. * @throws NullPointerException if {@code name} is {@code null}.
* @throws IllegalArgumentException if {@code name} is empty. * @throws IllegalArgumentException if {@code name} is empty.

139
src/java.base/share/classes/java/security/Signature.java
View file

@ -49,7 +49,7 @@ import sun.security.jca.GetInstance.Instance;
import sun.security.util.KnownOIDs; import sun.security.util.KnownOIDs;
/** /**
* The Signature class is used to provide applications the functionality * The {@code Signature} class is used to provide applications the functionality
* of a digital signature algorithm. Digital signatures are used for * of a digital signature algorithm. Digital signatures are used for
* authentication and integrity assurance of digital data. * authentication and integrity assurance of digital data.
* *
@ -60,10 +60,10 @@ import sun.security.util.KnownOIDs;
* {@code SHA256withRSA}. * {@code SHA256withRSA}.
* The algorithm name must be specified, as there is no default. * The algorithm name must be specified, as there is no default.
* *
* <p> A Signature object can be used to generate and verify digital * <p> A {@code Signature} object can be used to generate and verify digital
* signatures. * signatures.
* *
* <p> There are three phases to the use of a Signature object for * <p> There are three phases to the use of a {@code Signature} object for
* either signing data or verifying a signature:<ol> * either signing data or verifying a signature:<ol>
* *
* <li>Initialization, with either * <li>Initialization, with either
@ -169,29 +169,29 @@ public abstract class Signature extends SignatureSpi {
/** /**
* Possible {@link #state} value, signifying that * Possible {@link #state} value, signifying that
* this signature object has not yet been initialized. * this {@code Signature} object has not yet been initialized.
*/ */
protected static final int UNINITIALIZED = 0; protected static final int UNINITIALIZED = 0;
/** /**
* Possible {@link #state} value, signifying that * Possible {@link #state} value, signifying that
* this signature object has been initialized for signing. * this {@code Signature} object has been initialized for signing.
*/ */
protected static final int SIGN = 2; protected static final int SIGN = 2;
/** /**
* Possible {@link #state} value, signifying that * Possible {@link #state} value, signifying that
* this signature object has been initialized for verification. * this {@code Signature} object has been initialized for verification.
*/ */
protected static final int VERIFY = 3; protected static final int VERIFY = 3;
/** /**
* Current state of this signature object. * Current state of this {@code Signature} object.
*/ */
protected int state = UNINITIALIZED; protected int state = UNINITIALIZED;
/** /**
* Creates a Signature object for the specified algorithm. * Creates a {@code Signature} object for the specified algorithm.
* *
* @param algorithm the standard string name of the algorithm. * @param algorithm the standard string name of the algorithm.
* See the Signature section in the <a href= * See the Signature section in the <a href=
@ -218,14 +218,14 @@ public abstract class Signature extends SignatureSpi {
new ServiceId("Cipher", "RSA")); new ServiceId("Cipher", "RSA"));
/** /**
* Returns a Signature object that implements the specified signature * Returns a {@code Signature} object that implements the specified
* algorithm. * signature algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security Providers,
* starting with the most preferred Provider. * starting with the most preferred Provider.
* A new Signature object encapsulating the * A new {@code Signature} object encapsulating the
* SignatureSpi implementation from the first * {@code SignatureSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -349,11 +349,11 @@ public abstract class Signature extends SignatureSpi {
} }
/** /**
* Returns a Signature object that implements the specified signature * Returns a {@code Signature} object that implements the specified
* algorithm. * signature algorithm.
* *
* <p> A new Signature object encapsulating the * <p> A new {@code Signature} object encapsulating the
* SignatureSpi implementation from the specified provider * {@code SignatureSpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -405,13 +405,13 @@ public abstract class Signature extends SignatureSpi {
} }
/** /**
* Returns a Signature object that implements the specified * Returns a {@code Signature} object that implements the specified
* signature algorithm. * signature algorithm.
* *
* <p> A new Signature object encapsulating the * <p> A new {@code Signature} object encapsulating the
* SignatureSpi implementation from the specified Provider * {@code SignatureSpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * is returned. Note that the specified provider does not
* does not have to be registered in the provider list. * have to be registered in the provider list.
* *
* @param algorithm the name of the algorithm requested. * @param algorithm the name of the algorithm requested.
* See the Signature section in the <a href= * See the Signature section in the <a href=
@ -473,9 +473,9 @@ public abstract class Signature extends SignatureSpi {
} }
/** /**
* Returns the provider of this signature object. * Returns the provider of this {@code Signature} object.
* *
* @return the provider of this signature object * @return the provider of this {@code Signature} object
*/ */
public final Provider getProvider() { public final Provider getProvider() {
chooseFirstProvider(); chooseFirstProvider();
@ -518,7 +518,8 @@ public abstract class Signature extends SignatureSpi {
* *
* @param publicKey the public key of the identity whose signature is * @param publicKey the public key of the identity whose signature is
* going to be verified * going to be verified
* @param params the parameters used for verifying this signature object * @param params the parameters used for verifying this {@code Signature}
* object
* *
* @throws InvalidKeyException if the key is invalid * @throws InvalidKeyException if the key is invalid
* @throws InvalidAlgorithmParameterException if the params is invalid * @throws InvalidAlgorithmParameterException if the params is invalid
@ -598,7 +599,8 @@ public abstract class Signature extends SignatureSpi {
* *
* @param certificate the certificate of the identity whose signature is * @param certificate the certificate of the identity whose signature is
* going to be verified * going to be verified
* @param params the parameters used for verifying this signature object * @param params the parameters used for verifying this {@code Signature}
* object
* *
* @throws InvalidKeyException if the public key in the certificate * @throws InvalidKeyException if the public key in the certificate
* is not encoded properly or does not include required parameter * is not encoded properly or does not include required parameter
@ -648,7 +650,7 @@ public abstract class Signature extends SignatureSpi {
* @param privateKey the private key of the identity whose signature * @param privateKey the private key of the identity whose signature
* is going to be generated * is going to be generated
* *
* @param random the source of randomness for this signature object * @param random the source of randomness for this {@code Signature} object
* *
* @throws InvalidKeyException if the key is invalid. * @throws InvalidKeyException if the key is invalid.
*/ */
@ -671,7 +673,7 @@ public abstract class Signature extends SignatureSpi {
* @param privateKey the private key of the identity whose signature * @param privateKey the private key of the identity whose signature
* is going to be generated * is going to be generated
* @param params the parameters used for generating signature * @param params the parameters used for generating signature
* @param random the source of randomness for this signature object * @param random the source of randomness for this {@code Signature} object
* *
* @throws InvalidKeyException if the key is invalid * @throws InvalidKeyException if the key is invalid
* @throws InvalidAlgorithmParameterException if the params is invalid * @throws InvalidAlgorithmParameterException if the params is invalid
@ -693,8 +695,8 @@ public abstract class Signature extends SignatureSpi {
* The format of the signature depends on the underlying * The format of the signature depends on the underlying
* signature scheme. * signature scheme.
* *
* <p>A call to this method resets this signature object to the state * <p>A call to this method resets this {@code Signature} object to the
* it was in when previously initialized for signing via a * state it was in when previously initialized for signing via a
* call to {@code initSign(PrivateKey)}. That is, the object is * call to {@code initSign(PrivateKey)}. That is, the object is
* reset and available to generate another signature from the same * reset and available to generate another signature from the same
* signer, if desired, via new calls to {@code update} and * signer, if desired, via new calls to {@code update} and
@ -702,7 +704,7 @@ public abstract class Signature extends SignatureSpi {
* *
* @return the signature bytes of the signing operation's result. * @return the signature bytes of the signing operation's result.
* *
* @throws SignatureException if this signature object is not * @throws SignatureException if this {@code Signature} object is not
* initialized properly or if this signature algorithm is unable to * initialized properly or if this signature algorithm is unable to
* process the input data provided. * process the input data provided.
*/ */
@ -721,8 +723,8 @@ public abstract class Signature extends SignatureSpi {
* The format of the signature depends on the underlying * The format of the signature depends on the underlying
* signature scheme. * signature scheme.
* *
* <p>This signature object is reset to its initial state (the state it * <p>This {@code Signature} object is reset to its initial state (the
* was in after a call to one of the {@code initSign} methods) and * state it was in after a call to one of the {@code initSign} methods) and
* can be reused to generate further signatures with the same private key. * can be reused to generate further signatures with the same private key.
* *
* @param outbuf buffer for the signature result. * @param outbuf buffer for the signature result.
@ -735,7 +737,7 @@ public abstract class Signature extends SignatureSpi {
* *
* @return the number of bytes placed into {@code outbuf}. * @return the number of bytes placed into {@code outbuf}.
* *
* @throws SignatureException if this signature object is not * @throws SignatureException if this {@code Signature} object is not
* initialized properly, if this signature algorithm is unable to * initialized properly, if this signature algorithm is unable to
* process the input data provided, or if {@code len} is less * process the input data provided, or if {@code len} is less
* than the actual signature length. * than the actual signature length.
@ -768,17 +770,17 @@ public abstract class Signature extends SignatureSpi {
/** /**
* Verifies the passed-in signature. * Verifies the passed-in signature.
* *
* <p>A call to this method resets this signature object to the state * <p>A call to this method resets this {@code Signature} object to the
* it was in when previously initialized for verification via a * state it was in when previously initialized for verification via a
* call to {@code initVerify(PublicKey)}. That is, the object is * call to {@code initVerify(PublicKey)}. That is, the object is
* reset and available to verify another signature from the identity * reset and available to verify another signature from the identity
* whose public key was specified in the call to {@code initVerify}. * whose public key was specified in the call to {@code initVerify}.
* *
* @param signature the signature bytes to be verified. * @param signature the signature bytes to be verified.
* *
* @return true if the signature was verified, false if not. * @return {@code true} if the signature was verified, {@code false} if not.
* *
* @throws SignatureException if this signature object is not * @throws SignatureException if this {@code Signature} object is not
* initialized properly, the passed-in signature is improperly * initialized properly, the passed-in signature is improperly
* encoded or of the wrong type, if this signature algorithm is unable to * encoded or of the wrong type, if this signature algorithm is unable to
* process the input data provided, etc. * process the input data provided, etc.
@ -795,8 +797,8 @@ public abstract class Signature extends SignatureSpi {
* Verifies the passed-in signature in the specified array * Verifies the passed-in signature in the specified array
* of bytes, starting at the specified offset. * of bytes, starting at the specified offset.
* *
* <p>A call to this method resets this signature object to the state * <p>A call to this method resets this {@code Signature} object to the
* it was in when previously initialized for verification via a * state it was in when previously initialized for verification via a
* call to {@code initVerify(PublicKey)}. That is, the object is * call to {@code initVerify(PublicKey)}. That is, the object is
* reset and available to verify another signature from the identity * reset and available to verify another signature from the identity
* whose public key was specified in the call to {@code initVerify}. * whose public key was specified in the call to {@code initVerify}.
@ -806,9 +808,9 @@ public abstract class Signature extends SignatureSpi {
* @param offset the offset to start from in the array of bytes. * @param offset the offset to start from in the array of bytes.
* @param length the number of bytes to use, starting at offset. * @param length the number of bytes to use, starting at offset.
* *
* @return true if the signature was verified, false if not. * @return {@code true} if the signature was verified, {@code false} if not.
* *
* @throws SignatureException if this signature object is not * @throws SignatureException if this {@code Signature} object is not
* initialized properly, the passed-in signature is improperly * initialized properly, the passed-in signature is improperly
* encoded or of the wrong type, if this signature algorithm is unable to * encoded or of the wrong type, if this signature algorithm is unable to
* process the input data provided, etc. * process the input data provided, etc.
@ -845,7 +847,7 @@ public abstract class Signature extends SignatureSpi {
* *
* @param b the byte to use for the update. * @param b the byte to use for the update.
* *
* @throws SignatureException if this signature object is not * @throws SignatureException if this {@code Signature} object is not
* initialized properly. * initialized properly.
*/ */
public final void update(byte b) throws SignatureException { public final void update(byte b) throws SignatureException {
@ -863,7 +865,7 @@ public abstract class Signature extends SignatureSpi {
* *
* @param data the byte array to use for the update. * @param data the byte array to use for the update.
* *
* @throws SignatureException if this signature object is not * @throws SignatureException if this {@code Signature} object is not
* initialized properly. * initialized properly.
*/ */
public final void update(byte[] data) throws SignatureException { public final void update(byte[] data) throws SignatureException {
@ -878,7 +880,7 @@ public abstract class Signature extends SignatureSpi {
* @param off the offset to start from in 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. * @param len the number of bytes to use, starting at offset.
* *
* @throws SignatureException if this signature object is not * @throws SignatureException if this {@code Signature} object is not
* initialized properly. * initialized properly.
* @throws IllegalArgumentException if {@code data} is {@code null}, * @throws IllegalArgumentException if {@code data} is {@code null},
* or {@code off} or {@code len} is less than 0, or the sum of * or {@code off} or {@code len} is less than 0, or the sum of
@ -914,7 +916,7 @@ public abstract class Signature extends SignatureSpi {
* *
* @param data the ByteBuffer * @param data the ByteBuffer
* *
* @throws SignatureException if this signature object is not * @throws SignatureException if this {@code Signature} object is not
* initialized properly. * initialized properly.
* @since 1.5 * @since 1.5
*/ */
@ -930,20 +932,20 @@ public abstract class Signature extends SignatureSpi {
} }
/** /**
* Returns the name of the algorithm for this signature object. * Returns the name of the algorithm for this {@code Signature} object.
* *
* @return the name of the algorithm for this signature object. * @return the name of the algorithm for this {@code Signature} object.
*/ */
public final String getAlgorithm() { public final String getAlgorithm() {
return this.algorithm; return this.algorithm;
} }
/** /**
* Returns a string representation of this signature object, * Returns a string representation of this {@code Signature} object,
* providing information that includes the state of the object * providing information that includes the state of the object
* and the name of the algorithm used. * and the name of the algorithm used.
* *
* @return a string representation of this signature object. * @return a string representation of this {@code Signature} object.
*/ */
public String toString() { public String toString() {
String initState = switch (state) { String initState = switch (state) {
@ -970,7 +972,7 @@ public abstract class Signature extends SignatureSpi {
* @param value the parameter value * @param value the parameter value
* *
* @throws InvalidParameterException if {@code param} is an * @throws InvalidParameterException if {@code param} is an
* invalid parameter for this signature object, * invalid parameter for this {@code Signature} object,
* the parameter is already set * the parameter is already set
* and cannot be set again, a security exception occurs, and so on. * and cannot be set again, a security exception occurs, and so on.
* *
@ -987,12 +989,13 @@ public abstract class Signature extends SignatureSpi {
} }
/** /**
* Initializes this signature object with the specified parameter values. * Initializes this {@code Signature} object with the specified parameter
* values.
* *
* @param params the parameter values * @param params the parameter values
* *
* @throws InvalidAlgorithmParameterException if the given parameter values * @throws InvalidAlgorithmParameterException if the given parameter values
* are inappropriate for this signature object * are inappropriate for this {@code Signature} object
* *
* @see #getParameters * @see #getParameters
*/ */
@ -1002,20 +1005,21 @@ public abstract class Signature extends SignatureSpi {
} }
/** /**
* Returns the parameters used with this signature object. * Returns the parameters used with this {@code Signature} object.
* *
* <p>The returned parameters may be the same that were used to initialize * <p>The returned parameters may be the same that were used to initialize
* this signature object, or may contain additional default or random * this {@code Signature} object, or may contain additional default or
* parameter values used by the underlying signature scheme. If the required * random parameter values used by the underlying signature scheme.
* parameters were not supplied and can be generated by the signature * If the required parameters were not supplied and can be generated by
* object, the generated parameters are returned; otherwise {@code null} is * the {@code Signature} object, the generated parameters are returned;
* returned. * otherwise {@code null} is returned.
* *
* <p>However, if the signature scheme does not support returning * <p>However, if the signature scheme does not support returning
* the parameters as {@code AlgorithmParameters}, {@code null} is always * the parameters as {@code AlgorithmParameters}, {@code null} is always
* returned. * returned.
* *
* @return the parameters used with this signature object, or {@code null} * @return the parameters used with this {@code Signature} object,
* or {@code null}
* @throws UnsupportedOperationException if the provider does not support * @throws UnsupportedOperationException if the provider does not support
* this method * this method
* *
@ -1072,15 +1076,16 @@ public abstract class Signature extends SignatureSpi {
} }
/* /*
* The following class allows providers to extend from SignatureSpi * The following class allows providers to extend from {@code SignatureSpi}
* rather than from Signature. It represents a Signature with an * rather than from {@code Signature}. It represents a {@code Signature}
* encapsulated, provider-supplied SPI object (of type SignatureSpi). * with an encapsulated, provider-supplied SPI object
* If the provider implementation is an instance of SignatureSpi, the * (of type {@code SignatureSpi}).
* getInstance() methods above return an instance of this class, with * If the provider implementation is an instance of {@code SignatureSpi},
* the getInstance() methods above return an instance of this class, with
* the SPI object encapsulated. * the SPI object encapsulated.
* *
* Note: All SPI methods from the original Signature class have been * Note: All SPI methods from the original {@code Signature} class have been
* moved up the hierarchy into a new class (SignatureSpi), which has * moved up the hierarchy into a new class (SignatureSpi}, which has
* been interposed in the hierarchy between the API (Signature) * been interposed in the hierarchy between the API (Signature)
* and its original parent (Object). * and its original parent (Object).
*/ */

10
src/java.base/share/classes/java/security/SignatureException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -38,8 +38,8 @@ public class SignatureException extends GeneralSecurityException {
private static final long serialVersionUID = 7509989324975124438L; private static final long serialVersionUID = 7509989324975124438L;
/** /**
* Constructs a SignatureException with no detail message. A * Constructs a {@code SignatureException} with no detail message. A
* detail message is a String that describes this particular * detail message is a {@code String} that describes this particular
* exception. * exception.
*/ */
public SignatureException() { public SignatureException() {
@ -47,8 +47,8 @@ public class SignatureException extends GeneralSecurityException {
} }
/** /**
* Constructs a SignatureException with the specified detail * Constructs a {@code SignatureException} with the specified detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
* *
* @param msg the detail message. * @param msg the detail message.

44
src/java.base/share/classes/java/security/SignatureSpi.java
View file

@ -60,7 +60,7 @@ public abstract class SignatureSpi {
protected SecureRandom appRandom = null; protected SecureRandom appRandom = null;
/** /**
* Initializes this signature object with the specified * Initializes this {@code Signature} object with the specified
* public key for verification operations. * public key for verification operations.
* *
* @param publicKey the public key of the identity whose signature is * @param publicKey the public key of the identity whose signature is
@ -73,12 +73,12 @@ public abstract class SignatureSpi {
throws InvalidKeyException; throws InvalidKeyException;
/** /**
* Initializes this signature object with the specified * Initializes this {@code Signature} object with the specified
* public key for verification operations. * public key for verification operations.
* *
* @param publicKey the public key of the identity whose signature is * @param publicKey the public key of the identity whose signature is
* going to be verified. * going to be verified.
* @param params the parameters for verifying this signature object * @param params the parameters for verifying this {@code Signature} object
* *
* @throws InvalidKeyException if the key is improperly * @throws InvalidKeyException if the key is improperly
* encoded, does not work with the given parameters, and so on. * encoded, does not work with the given parameters, and so on.
@ -100,7 +100,7 @@ public abstract class SignatureSpi {
} }
/** /**
* Initializes this signature object with the specified * Initializes this {@code Signature} object with the specified
* private key for signing operations. * private key for signing operations.
* *
* @param privateKey the private key of the identity whose signature * @param privateKey the private key of the identity whose signature
@ -113,7 +113,7 @@ public abstract class SignatureSpi {
throws InvalidKeyException; throws InvalidKeyException;
/** /**
* Initializes this signature object with the specified * Initializes this {@code Signature} object with the specified
* private key and source of randomness for signing operations. * private key and source of randomness for signing operations.
* *
* <p>This concrete method has been added to this previously-defined * <p>This concrete method has been added to this previously-defined
@ -134,7 +134,7 @@ public abstract class SignatureSpi {
} }
/** /**
* Initializes this signature object with the specified * Initializes this {@code Signature} object with the specified
* private key and source of randomness for signing operations. * private key and source of randomness for signing operations.
* *
* <p>This concrete method has been added to this previously-defined * <p>This concrete method has been added to this previously-defined
@ -269,7 +269,7 @@ public abstract class SignatureSpi {
* Both this default implementation and the SUN provider do not * Both this default implementation and the SUN provider do not
* return partial digests. If the value of this parameter is less * return partial digests. If the value of this parameter is less
* than the actual signature length, this method will throw a * than the actual signature length, this method will throw a
* SignatureException. * {@code SignatureException}.
* This parameter is ignored if its value is greater than or equal to * This parameter is ignored if its value is greater than or equal to
* the actual signature length. * the actual signature length.
* *
@ -303,7 +303,7 @@ public abstract class SignatureSpi {
* *
* @param sigBytes the signature bytes to be verified. * @param sigBytes the signature bytes to be verified.
* *
* @return true if the signature was verified, false if not. * @return {@code true} if the signature was verified, {@code false} if not.
* *
* @throws SignatureException if the engine is not * @throws SignatureException if the engine is not
* initialized properly, the passed-in signature is improperly * initialized properly, the passed-in signature is improperly
@ -324,7 +324,7 @@ public abstract class SignatureSpi {
* @param offset the offset to start from in the array of bytes. * @param offset the offset to start from in the array of bytes.
* @param length the number of bytes to use, starting at offset. * @param length the number of bytes to use, starting at offset.
* *
* @return true if the signature was verified, false if not. * @return {@code true} if the signature was verified, {@code false} if not.
* *
* @throws SignatureException if the engine is not * @throws SignatureException if the engine is not
* initialized properly, the passed-in signature is improperly * initialized properly, the passed-in signature is improperly
@ -355,7 +355,7 @@ public abstract class SignatureSpi {
* @param value the parameter value. * @param value the parameter value.
* *
* @throws InvalidParameterException if {@code param} is an * @throws InvalidParameterException if {@code param} is an
* invalid parameter for this signature object, * invalid parameter for this {@code Signature} object,
* the parameter is already set * the parameter is already set
* and cannot be set again, a security exception occurs, and so on. * and cannot be set again, a security exception occurs, and so on.
* *
@ -368,7 +368,8 @@ public abstract class SignatureSpi {
throws InvalidParameterException; throws InvalidParameterException;
/** /**
* Initializes this signature object with the specified parameter values. * Initializes this {@code Signature} object with the specified parameter
* values.
* *
* @param params the parameters * @param params the parameters
* *
@ -377,7 +378,7 @@ public abstract class SignatureSpi {
* *
* @throws InvalidAlgorithmParameterException if this method is * @throws InvalidAlgorithmParameterException if this method is
* overridden by a provider and the given parameters * overridden by a provider and the given parameters
* are inappropriate for this signature object * are inappropriate for this {@code Signature} object
*/ */
protected void engineSetParameter(AlgorithmParameterSpec params) protected void engineSetParameter(AlgorithmParameterSpec params)
throws InvalidAlgorithmParameterException { throws InvalidAlgorithmParameterException {
@ -385,20 +386,21 @@ public abstract class SignatureSpi {
} }
/** /**
* Returns the parameters used with this signature object. * Returns the parameters used with this {@code Signature} object.
* *
* <p>The returned parameters may be the same that were used to initialize * <p>The returned parameters may be the same that were used to initialize
* this signature object, or may contain additional default or random * this {@code Signature} object, or may contain additional default or
* parameter values used by the underlying signature scheme. If the required * random parameter values used by the underlying signature scheme.
* parameters were not supplied and can be generated by the signature * If the required parameters were not supplied and can be generated by
* object, the generated parameters are returned; otherwise {@code null} is * the {@code Signature} object, the generated parameters are returned;
* returned. * otherwise {@code null} is returned.
* *
* <p>However, if the signature scheme does not support returning * <p>However, if the signature scheme does not support returning
* the parameters as {@code AlgorithmParameters}, {@code null} is always * the parameters as {@code AlgorithmParameters}, {@code null} is always
* returned. * returned.
* *
* @return the parameters used with this signature object, or {@code null} * @return the parameters used with this {@code Signature} object, or
* {@code null}
* *
* @throws UnsupportedOperationException if this method is not overridden * @throws UnsupportedOperationException if this method is not overridden
* by a provider * by a provider
@ -421,8 +423,8 @@ public abstract class SignatureSpi {
* *
* @param param the string name of the parameter. * @param param the string name of the parameter.
* *
* @return the object that represents the parameter value, or {@code null} if * @return the object that represents the parameter value, or {@code null}
* there is none. * if there is none.
* *
* @throws InvalidParameterException if {@code param} is an * @throws InvalidParameterException if {@code param} is an
* invalid parameter for this engine, or another exception occurs while * invalid parameter for this engine, or another exception occurs while

18
src/java.base/share/classes/java/security/SignedObject.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -28,11 +28,11 @@ package java.security;
import java.io.*; import java.io.*;
/** /**
* <p> SignedObject is a class for the purpose of creating authentic * <p> {@code SignedObject} is a class for the purpose of creating authentic
* runtime objects whose integrity cannot be compromised without being * runtime objects whose integrity cannot be compromised without being
* detected. * detected.
* *
* <p> More specifically, a SignedObject contains another Serializable * <p> More specifically, a {@code SignedObject} contains another Serializable
* object, the (to-be-)signed object and its signature. * object, the (to-be-)signed object and its signature.
* *
* <p> The signed object is a "deep copy" (in serialized form) of an * <p> The signed object is a "deep copy" (in serialized form) of an
@ -67,7 +67,7 @@ import java.io.*;
* re-initialized inside the constructor and the {@code verify} * re-initialized inside the constructor and the {@code verify}
* method. Secondly, for verification to succeed, the specified * method. Secondly, for verification to succeed, the specified
* public key must be the public key corresponding to the private key * public key must be the public key corresponding to the private key
* used to generate the SignedObject. * used to generate the {@code SignedObject}.
* *
* <p> More importantly, for flexibility reasons, the * <p> More importantly, for flexibility reasons, the
* constructor and {@code verify} method allow for * constructor and {@code verify} method allow for
@ -95,7 +95,7 @@ import java.io.*;
* specified, the default provider is used. Each installation can * specified, the default provider is used. Each installation can
* be configured to use a particular provider as default. * be configured to use a particular provider as default.
* *
* <p> Potential applications of SignedObject include: * <p> Potential applications of {@code SignedObject} include:
* <ul> * <ul>
* <li> It can be used * <li> It can be used
* internally to any Java runtime as an unforgeable authorization * internally to any Java runtime as an unforgeable authorization
@ -138,7 +138,7 @@ public final class SignedObject implements Serializable {
private String thealgorithm; private String thealgorithm;
/** /**
* Constructs a SignedObject from any Serializable object. * Constructs a {@code SignedObject} from any Serializable object.
* The given object is signed with the given signing key, using the * The given object is signed with the given signing key, using the
* designated signature engine. * designated signature engine.
* *
@ -211,7 +211,7 @@ public final class SignedObject implements Serializable {
} }
/** /**
* Verifies that the signature in this SignedObject is the valid * Verifies that the signature in this {@code SignedObject} is the valid
* signature for the object stored inside, with the given * signature for the object stored inside, with the given
* verification key, using the designated verification engine. * verification key, using the designated verification engine.
* *
@ -254,8 +254,8 @@ public final class SignedObject implements Serializable {
} }
/** /**
* readObject is called to restore the state of the SignedObject from * readObject is called to restore the state of the {@code SignedObject}
* a stream. * from a stream.
* *
* @param s the {@code ObjectInputStream} from which data is read * @param s the {@code ObjectInputStream} from which data is read
* @throws IOException if an I/O error occurs * @throws IOException if an I/O error occurs

16
src/java.base/share/classes/java/security/Signer.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -60,7 +60,7 @@ public abstract class Signer extends Identity {
private PrivateKey privateKey; private PrivateKey privateKey;
/** /**
* Creates a signer. This constructor should only be used for * Creates a {@code Signer}. This constructor should only be used for
* serialization. * serialization.
*/ */
protected Signer() { protected Signer() {
@ -69,7 +69,7 @@ public abstract class Signer extends Identity {
/** /**
* Creates a signer with the specified identity name. * Creates a {@code Signer} with the specified identity name.
* *
* @param name the identity name. * @param name the identity name.
*/ */
@ -78,7 +78,7 @@ public abstract class Signer extends Identity {
} }
/** /**
* Creates a signer with the specified identity name and scope. * Creates a {@code Signer} with the specified identity name and scope.
* *
* @param name the identity name. * @param name the identity name.
* *
@ -99,7 +99,7 @@ public abstract class Signer extends Identity {
* method is called with {@code "getSignerPrivateKey"} * method is called with {@code "getSignerPrivateKey"}
* as its argument to see if it's ok to return the private key. * 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 * @return this signer's private key, or {@code null} if the private key has
* not yet been set. * not yet been set.
* *
* @throws SecurityException if a security manager exists and its * @throws SecurityException if a security manager exists and its
@ -114,7 +114,7 @@ public abstract class Signer extends Identity {
} }
/** /**
* Sets the key pair (public key and private key) for this signer. * Sets the key pair (public key and private key) for this {@code Signer}.
* *
* <p>First, if there is a security manager, its {@code checkSecurityAccess} * <p>First, if there is a security manager, its {@code checkSecurityAccess}
* method is called with {@code "setSignerKeyPair"} * method is called with {@code "setSignerKeyPair"}
@ -168,9 +168,9 @@ public abstract class Signer extends Identity {
} }
/** /**
* Returns a string of information about the signer. * Returns a string of information about the {@code Signer}.
* *
* @return a string of information about the signer. * @return a string of information about the {@code Signer}.
*/ */
public String toString() { public String toString() {
return "[Signer]" + super.toString(); return "[Signer]" + super.toString();

36
src/java.base/share/classes/java/security/Timestamp.java
View file

@ -68,11 +68,14 @@ public final class Timestamp implements Serializable {
private transient int myhash = -1; private transient int myhash = -1;
/** /**
* Constructs a Timestamp. * Constructs a {@code Timestamp}.
* *
* @param timestamp is the timestamp's date and time. It must not be null. * @param timestamp is the timestamp's date and time. It must not be
* @param signerCertPath is the TSA's certificate path. It must not be null. * {@code null}.
* @throws NullPointerException if timestamp or signerCertPath is null. * @param signerCertPath is the TSA's certificate path. It must not be
* {@code null}.
* @throws NullPointerException if timestamp or signerCertPath is
* {@code null}.
*/ */
public Timestamp(Date timestamp, CertPath signerCertPath) { public Timestamp(Date timestamp, CertPath signerCertPath) {
if (timestamp == null || signerCertPath == null) { if (timestamp == null || signerCertPath == null) {
@ -83,7 +86,7 @@ public final class Timestamp implements Serializable {
} }
/** /**
* Returns the date and time when the timestamp was generated. * Returns the date and time when the {@code Timestamp} was generated.
* *
* @return The timestamp's date and time. * @return The timestamp's date and time.
*/ */
@ -101,11 +104,11 @@ public final class Timestamp implements Serializable {
} }
/** /**
* Returns the hash code value for this timestamp. * Returns the hash code value for this {@code Timestamp}.
* The hash code is generated using the date and time of the timestamp * The hash code is generated using the date and time of the
* and the TSA's certificate path. * {@code Timestamp} and the TSA's certificate path.
* *
* @return a hash code value for this timestamp. * @return a hash code value for this {@code Timestamp}.
*/ */
public int hashCode() { public int hashCode() {
if (myhash == -1) { if (myhash == -1) {
@ -116,12 +119,13 @@ public final class Timestamp implements Serializable {
/** /**
* Tests for equality between the specified object and this * Tests for equality between the specified object and this
* timestamp. Two timestamps are considered equal if the date and time of * {@code Timestamp}. Two timestamps are considered equal if the date and
* their timestamp's and their signer's certificate paths are equal. * time of their timestamp's and their signer's certificate paths are equal.
* *
* @param obj the object to test for equality with this timestamp. * @param obj the object to test for equality with this {@code Timestamp}.
* *
* @return true if the timestamp are considered equal, false otherwise. * @return {@code true} if the timestamps are considered equal,
* {@code false} otherwise.
*/ */
public boolean equals(Object obj) { public boolean equals(Object obj) {
if (this == obj) { if (this == obj) {
@ -133,10 +137,10 @@ public final class Timestamp implements Serializable {
} }
/** /**
* Returns a string describing this timestamp. * Returns a string describing this {@code Timestamp}.
* *
* @return A string comprising the date and time of the timestamp and * @return A string comprising the date and time of the {@code Timestamp}
* its signer's certificate. * and its signer's certificate.
*/ */
public String toString() { public String toString() {
StringBuilder sb = new StringBuilder(); StringBuilder sb = new StringBuilder();

4
src/java.base/share/classes/java/security/URIParameter.java
View file

@ -39,12 +39,12 @@ public class URIParameter implements
private final java.net.URI uri; private final java.net.URI uri;
/** /**
* Constructs a URIParameter with the URI pointing to * Constructs a {@code URIParameter} with the URI pointing to
* data intended for an SPI implementation. * data intended for an SPI implementation.
* *
* @param uri the URI pointing to the data. * @param uri the URI pointing to the data.
* *
* @throws NullPointerException if the specified URI is null. * @throws NullPointerException if the specified URI is {@code null}.
*/ */
public URIParameter(java.net.URI uri) { public URIParameter(java.net.URI uri) {
if (uri == null) { if (uri == null) {

8
src/java.base/share/classes/java/security/UnrecoverableEntryException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -38,15 +38,15 @@ public class UnrecoverableEntryException extends GeneralSecurityException {
private static final long serialVersionUID = -4527142945246286535L; private static final long serialVersionUID = -4527142945246286535L;
/** /**
* Constructs an UnrecoverableEntryException with no detail message. * Constructs an {@code UnrecoverableEntryException} with no detail message.
*/ */
public UnrecoverableEntryException() { public UnrecoverableEntryException() {
super(); super();
} }
/** /**
* Constructs an UnrecoverableEntryException with the specified detail * Constructs an {@code UnrecoverableEntryException} with the specified
* message, which provides more information about why this exception * detail message, which provides more information about why this exception
* has been thrown. * has been thrown.
* *
* @param msg the detail message. * @param msg the detail message.

6
src/java.base/share/classes/java/security/UnrecoverableKeyException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -38,14 +38,14 @@ public class UnrecoverableKeyException extends UnrecoverableEntryException {
private static final long serialVersionUID = 7275063078190151277L; private static final long serialVersionUID = 7275063078190151277L;
/** /**
* Constructs an UnrecoverableKeyException with no detail message. * Constructs an {@code UnrecoverableKeyException} with no detail message.
*/ */
public UnrecoverableKeyException() { public UnrecoverableKeyException() {
super(); super();
} }
/** /**
* Constructs an UnrecoverableKeyException with the specified detail * Constructs an {@code UnrecoverableKeyException} with the specified detail
* message, which provides more information about why this exception * message, which provides more information about why this exception
* has been thrown. * has been thrown.
* *

58
src/java.base/share/classes/java/security/UnresolvedPermission.java
View file

@ -37,7 +37,7 @@ import java.security.cert.*;
import java.util.List; import java.util.List;
/** /**
* The UnresolvedPermission class is used to hold Permissions that * The {@code UnresolvedPermission} class is used to hold Permissions that
* were "unresolved" when the Policy was initialized. * were "unresolved" when the Policy was initialized.
* An unresolved permission is one whose actual Permission class * An unresolved permission is one whose actual Permission class
* does not yet exist at the time the Policy is initialized (see below). * does not yet exist at the time the Policy is initialized (see below).
@ -60,33 +60,33 @@ import java.util.List;
* <p>Other permission classes may not yet exist during Policy * <p>Other permission classes may not yet exist during Policy
* initialization. For example, a referenced permission class may * initialization. For example, a referenced permission class may
* be in a JAR file that will later be loaded. * be in a JAR file that will later be loaded.
* For each such class, an UnresolvedPermission is instantiated. * For each such class, an {@code UnresolvedPermission} is instantiated.
* Thus, an UnresolvedPermission is essentially a "placeholder" * Thus, an {@code UnresolvedPermission} is essentially a "placeholder"
* containing information about the permission. * containing information about the permission.
* *
* <p>Later, when code calls AccessController.checkPermission * <p>Later, when code calls {@link AccessController#checkPermission}
* on a permission of a type that was previously unresolved, * on a permission of a type that was previously unresolved,
* but whose class has since been loaded, previously-unresolved * but whose class has since been loaded, previously-unresolved
* permissions of that type are "resolved". That is, * permissions of that type are "resolved". That is,
* for each such UnresolvedPermission, a new object of * for each such {@code UnresolvedPermission}, a new object of
* the appropriate class type is instantiated, based on the * the appropriate class type is instantiated, based on the
* information in the UnresolvedPermission. * information in the {@code UnresolvedPermission}.
* *
* <p> To instantiate the new class, UnresolvedPermission assumes * <p> To instantiate the new class, {@code UnresolvedPermission} assumes
* the class provides a zero, one, and/or two-argument constructor. * the class provides a zero, one, and/or two-argument constructor.
* The zero-argument constructor would be used to instantiate * The zero-argument constructor would be used to instantiate
* a permission without a name and without actions. * a permission without a name and without actions.
* A one-arg constructor is assumed to take a {@code String} * A one-arg constructor is assumed to take a {@code String}
* name as input, and a two-arg constructor is assumed to take a * name as input, and a two-arg constructor is assumed to take a
* {@code String} name and {@code String} actions * {@code String} name and {@code String} actions
* as input. UnresolvedPermission may invoke a * as input. {@code UnresolvedPermission} may invoke a
* constructor with a {@code null} name and/or actions. * constructor with a {@code null} name and/or actions.
* If an appropriate permission constructor is not available, * If an appropriate permission constructor is not available,
* the UnresolvedPermission is ignored and the relevant permission * the {@code UnresolvedPermission} is ignored and the relevant permission
* will not be granted to executing code. * will not be granted to executing code.
* *
* <p> The newly created permission object replaces the * <p> The newly created permission object replaces the
* UnresolvedPermission, which is removed. * {@code UnresolvedPermission}, which is removed.
* *
* <p> Note that the {@code getName} method for an * <p> Note that the {@code getName} method for an
* {@code UnresolvedPermission} returns the * {@code UnresolvedPermission} returns the
@ -139,7 +139,7 @@ implements java.io.Serializable
private transient java.security.cert.Certificate[] certs; private transient java.security.cert.Certificate[] certs;
/** /**
* Creates a new UnresolvedPermission containing the permission * Creates a new {@code UnresolvedPermission} containing the permission
* information needed later to actually create a Permission of the * information needed later to actually create a Permission of the
* specified class, when the permission is resolved. * specified class, when the permission is resolved.
* *
@ -302,21 +302,21 @@ implements java.io.Serializable
} }
/** /**
* This method always returns false for unresolved permissions. * This method always returns {@code false} for unresolved permissions.
* That is, an UnresolvedPermission is never considered to * That is, an {@code UnresolvedPermission} is never considered to
* imply another permission. * imply another permission.
* *
* @param p the permission to check against. * @param p the permission to check against.
* *
* @return false. * @return {@code false}.
*/ */
public boolean implies(Permission p) { public boolean implies(Permission p) {
return false; return false;
} }
/** /**
* Checks two UnresolvedPermission objects for equality. * Checks two {@code UnresolvedPermission} objects for equality.
* Checks that {@code obj} is an UnresolvedPermission, and has * Checks that {@code obj} is an {@code UnresolvedPermission}, and has
* the same type (class) name, permission name, actions, and * the same type (class) name, permission name, actions, and
* certificates as this object. * certificates as this object.
* *
@ -326,8 +326,8 @@ implements java.io.Serializable
* *
* @param obj the object we are testing for equality with this object. * @param obj the object we are testing for equality with this object.
* *
* @return true if obj is an UnresolvedPermission, and has the same * @return true if {@code obj} is an {@code UnresolvedPermission},
* type (class) name, permission name, actions, and * and has the same type (class) name, permission name, actions, and
* certificates as this object. * certificates as this object.
*/ */
public boolean equals(Object obj) { public boolean equals(Object obj) {
@ -415,9 +415,9 @@ implements java.io.Serializable
/** /**
* Returns the canonical string representation of the actions, * Returns the canonical string representation of the actions,
* which currently is the empty string "", since there are no actions for * which currently is the empty string "", since there are no actions for
* an UnresolvedPermission. That is, the actions for the * an {@code UnresolvedPermission}. That is, the actions for the
* permission that will be created when this UnresolvedPermission * permission that will be created when this {@code UnresolvedPermission}
* is resolved may be non-null, but an UnresolvedPermission * is resolved may be non-null, but an {@code UnresolvedPermission}
* itself is never considered to have any actions. * itself is never considered to have any actions.
* *
* @return the empty string "". * @return the empty string "".
@ -473,7 +473,8 @@ implements java.io.Serializable
* for the underlying permission that has not been resolved. * for the underlying permission that has not been resolved.
* *
* @return the signer certificates for the underlying permission that * @return the signer certificates for the underlying permission that
* has not been resolved, or null, if there are no signer certificates. * has not been resolved, or {@code null}, if there are no signer
* certificates.
* Returns a new array each time this method is called. * Returns a new array each time this method is called.
* *
* @since 1.5 * @since 1.5
@ -483,11 +484,12 @@ implements java.io.Serializable
} }
/** /**
* Returns a string describing this UnresolvedPermission. The convention * Returns a string describing this {@code UnresolvedPermission}.
* is to specify the class name, the permission name, and the actions, in * The convention is to specify the class name, the permission name,
* the following format: '(unresolved "ClassName" "name" "actions")'. * and the actions, in the following format:
* '(unresolved "ClassName" "name" "actions")'.
* *
* @return information about this UnresolvedPermission. * @return information about this {@code UnresolvedPermission}.
*/ */
public String toString() { public String toString() {
return "(unresolved " + type + " " + name + " " + actions + ")"; return "(unresolved " + type + " " + name + " " + actions + ")";
@ -495,10 +497,10 @@ implements java.io.Serializable
/** /**
* Returns a new PermissionCollection object for storing * Returns a new PermissionCollection object for storing
* UnresolvedPermission objects. * {@code UnresolvedPermission} objects.
* *
* @return a new PermissionCollection object suitable for * @return a new PermissionCollection object suitable for
* storing UnresolvedPermissions. * storing {@code UnresolvedPermissions}.
*/ */
public PermissionCollection newPermissionCollection() { public PermissionCollection newPermissionCollection() {

10
src/java.base/share/classes/java/security/UnresolvedPermissionCollection.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -34,7 +34,7 @@ import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArrayList; import java.util.concurrent.CopyOnWriteArrayList;
/** /**
* A UnresolvedPermissionCollection stores a collection * A {@code UnresolvedPermissionCollection} stores a collection
* of UnresolvedPermission permissions. * of UnresolvedPermission permissions.
* *
* @see java.security.Permission * @see java.security.Permission
@ -60,7 +60,7 @@ implements java.io.Serializable
private transient ConcurrentHashMap<String, List<UnresolvedPermission>> perms; private transient ConcurrentHashMap<String, List<UnresolvedPermission>> perms;
/** /**
* Create an empty UnresolvedPermissionCollection object. * Create an empty {@code UnresolvedPermissionCollection} object.
* *
*/ */
public UnresolvedPermissionCollection() { public UnresolvedPermissionCollection() {
@ -68,7 +68,7 @@ implements java.io.Serializable
} }
/** /**
* Adds a permission to this UnresolvedPermissionCollection. * Adds a permission to this {@code UnresolvedPermissionCollection}.
* The key for the hash is the unresolved permission's type (class) name. * The key for the hash is the unresolved permission's type (class) name.
* *
* @param permission the Permission object to add. * @param permission the Permission object to add.
@ -109,7 +109,7 @@ implements java.io.Serializable
} }
/** /**
* always returns false for unresolved permissions * always returns {@code false} for unresolved permissions
* *
*/ */
@Override @Override

6
src/java.base/share/classes/javax/crypto/AEADBadTagException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2011, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -38,14 +38,14 @@ public class AEADBadTagException extends BadPaddingException {
private static final long serialVersionUID = -488059093241685509L; private static final long serialVersionUID = -488059093241685509L;
/** /**
* Constructs a AEADBadTagException with no detail message. * Constructs an {@code AEADBadTagException} with no detail message.
*/ */
public AEADBadTagException() { public AEADBadTagException() {
super(); super();
} }
/** /**
* Constructs a AEADBadTagException with the specified * Constructs an {@code AEADBadTagException} with the specified
* detail message. * detail message.
* *
* @param msg the detail message. * @param msg the detail message.

8
src/java.base/share/classes/javax/crypto/BadPaddingException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -41,8 +41,8 @@ public class BadPaddingException extends GeneralSecurityException {
private static final long serialVersionUID = -5315033893984728443L; private static final long serialVersionUID = -5315033893984728443L;
/** /**
* Constructs a BadPaddingException with no detail * Constructs a {@code BadPaddingException} with no detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
*/ */
public BadPaddingException() { public BadPaddingException() {
@ -50,7 +50,7 @@ public class BadPaddingException extends GeneralSecurityException {
} }
/** /**
* Constructs a BadPaddingException with the specified * Constructs a {@code BadPaddingException} with the specified
* detail message. * detail message.
* *
* @param msg the detail message. * @param msg the detail message.

456
src/java.base/share/classes/javax/crypto/Cipher.java
View file

@ -52,7 +52,7 @@ import sun.security.util.KnownOIDs;
* encryption and decryption. It forms the core of the Java Cryptographic * encryption and decryption. It forms the core of the Java Cryptographic
* Extension (JCE) framework. * Extension (JCE) framework.
* *
* <p>In order to create a {code Cipher} object, the application calls the * <p>In order to create a {@code Cipher} object, the application calls the
* cipher's {@code getInstance} method, and passes the name of the * cipher's {@code getInstance} method, and passes the name of the
* requested <i>transformation</i> to it. Optionally, the name of a provider * requested <i>transformation</i> to it. Optionally, the name of a provider
* may be specified. * may be specified.
@ -141,8 +141,8 @@ import sun.security.util.KnownOIDs;
* information on the ChaCha20 and ChaCha20-Poly1305 algorithms. * information on the ChaCha20 and ChaCha20-Poly1305 algorithms.
* <p> * <p>
* Every implementation of the Java platform is required to support * Every implementation of the Java platform is required to support
* the following standard {@code Cipher} transformations with the keysizes * the following standard {@code Cipher} object transformations with
* in parentheses: * the keysizes in parentheses:
* <ul> * <ul>
* <li>{@code AES/CBC/NoPadding} (128)</li> * <li>{@code AES/CBC/NoPadding} (128)</li>
* <li>{@code AES/CBC/PKCS5Padding} (128)</li> * <li>{@code AES/CBC/PKCS5Padding} (128)</li>
@ -258,14 +258,14 @@ public class Cipher {
private final Object lock; private final Object lock;
/** /**
* Creates a {code Cipher} object. * Creates a {@code Cipher} object.
* *
* @param cipherSpi the delegate * @param cipherSpi the delegate
* @param provider the provider * @param provider the provider
* @param transformation the transformation * @param transformation the transformation
* @throws NullPointerException if {@code provider} is {@code null} * @throws NullPointerException if {@code provider} is {@code null}
* @throws IllegalArgumentException if the supplied arguments * @throws IllegalArgumentException if the supplied arguments
* are deemed invalid for constructing the {code Cipher} object * are deemed invalid for constructing the {@code Cipher} object
*/ */
protected Cipher(CipherSpi cipherSpi, protected Cipher(CipherSpi cipherSpi,
Provider provider, Provider provider,
@ -515,7 +515,8 @@ public class Cipher {
* Java Security Standard Algorithm Names Specification</a> * Java Security Standard Algorithm Names Specification</a>
* for information about standard transformation names. * for information about standard transformation names.
* *
* @return a cipher that implements the requested transformation * @return a {@code Cipher} object that implements the requested
* transformation
* *
* @throws NoSuchAlgorithmException if {@code transformation} * @throws NoSuchAlgorithmException if {@code transformation}
* is {@code null}, empty, in an invalid format, * is {@code null}, empty, in an invalid format,
@ -606,7 +607,8 @@ public class Cipher {
* *
* @param provider the name of the provider * @param provider the name of the provider
* *
* @return a cipher that implements the requested transformation * @return a {@code Cipher} object that implements the requested
* transformation
* *
* @throws IllegalArgumentException if the {@code provider} * @throws IllegalArgumentException if the {@code provider}
* is {@code null} or empty * is {@code null} or empty
@ -677,7 +679,8 @@ public class Cipher {
* *
* @param provider the provider * @param provider the provider
* *
* @return a cipher that implements the requested transformation * @return a {@code Cipher} object that implements the requested
* transformation
* *
* @throws IllegalArgumentException if the {@code provider} * @throws IllegalArgumentException if the {@code provider}
* is {@code null} * is {@code null}
@ -1014,8 +1017,8 @@ public class Cipher {
* *
* @return the required output buffer size (in bytes) * @return the required output buffer size (in bytes)
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object is in a
* (e.g., has not yet been initialized) * wrong state (e.g., has not yet been initialized)
*/ */
public final int getOutputSize(int inputLen) { public final int getOutputSize(int inputLen) {
@ -1047,7 +1050,7 @@ public class Cipher {
} }
/** /**
* Returns the parameters used with this cipher. * Returns the parameters used with this {@code Cipher} object.
* *
* <p>The returned parameters may be the same that were used to initialize * <p>The returned parameters may be the same that were used to initialize
* this cipher, or may contain additional default or random parameter * this cipher, or may contain additional default or random parameter
@ -1063,10 +1066,12 @@ public class Cipher {
} }
/** /**
* Returns the exemption mechanism object used with this cipher. * Returns the exemption mechanism object used with this {@code Cipher}
* object.
* *
* @return the exemption mechanism object used with this cipher, or * @return the exemption mechanism object used with this {@code Cipher}
* {@code null} if this cipher does not use any exemption mechanism. * object, or {@code null} if this {@code Cipher} object does not use any
* exemption mechanism.
*/ */
public final ExemptionMechanism getExemptionMechanism() { public final ExemptionMechanism getExemptionMechanism() {
chooseFirstProvider(); chooseFirstProvider();
@ -1183,9 +1188,10 @@ public class Cipher {
} }
/** /**
* Initializes this cipher with a key. * Initializes this {@code Cipher} object with a key.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code Cipher} object is initialized for one of the following four
* operations:
* encryption, decryption, key wrapping or key unwrapping, depending * encryption, decryption, key wrapping or key unwrapping, depending
* on the value of {@code opmode}. * on the value of {@code opmode}.
* *
@ -1214,12 +1220,12 @@ public class Cipher {
* SecureRandom, a system-provided source of randomness will be used.) * SecureRandom, a system-provided source of randomness will be used.)
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code Cipher} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a {@code Cipher}
* equivalent to creating a new instance of that cipher and initializing * object is equivalent to creating a new instance of that {@code Cipher}
* it. * object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of * @param opmode the operation mode of this {@code Cipher} object
* the following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE} or {@code UNWRAP_MODE}) * {@code WRAP_MODE} or {@code UNWRAP_MODE})
* @param key the key * @param key the key
@ -1239,9 +1245,11 @@ public class Cipher {
} }
/** /**
* Initializes this cipher with a key and a source of randomness. * Initializes this {@code Cipher} object with a key and a
* source of randomness.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code Cipher} object is initialized for one of the following four
* operations:
* encryption, decryption, key wrapping or key unwrapping, depending * encryption, decryption, key wrapping or key unwrapping, depending
* on the value of {@code opmode}. * on the value of {@code opmode}.
* *
@ -1266,12 +1274,12 @@ public class Cipher {
* them from {@code random}. * them from {@code random}.
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code Cipher} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a {@code Cipher}
* equivalent to creating a new instance of that cipher and initializing * object is equivalent to creating a new instance of that
* it. * {@code Cipher} object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of the * @param opmode the operation mode of this {@code Cipher} object
* following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE} or {@code UNWRAP_MODE}) * {@code WRAP_MODE} or {@code UNWRAP_MODE})
* @param key the encryption key * @param key the encryption key
@ -1314,10 +1322,11 @@ public class Cipher {
} }
/** /**
* Initializes this cipher with a key and a set of algorithm * Initializes this {@code Cipher} object with a key and a set of algorithm
* parameters. * parameters.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code Cipher} object is initialized for one of the following four
* operations:
* encryption, decryption, key wrapping or key unwrapping, depending * encryption, decryption, key wrapping or key unwrapping, depending
* on the value of {@code opmode}. * on the value of {@code opmode}.
* *
@ -1346,12 +1355,12 @@ public class Cipher {
* SecureRandom, a system-provided source of randomness will be used.) * SecureRandom, a system-provided source of randomness will be used.)
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code Cipher} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a {@code Cipher}
* equivalent to creating a new instance of that cipher and initializing * object is equivalent to creating a new instance of that {@code Cipher}
* it. * object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of the * @param opmode the operation mode of this {@code Cipher} object
* following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE} or {@code UNWRAP_MODE}) * {@code WRAP_MODE} or {@code UNWRAP_MODE})
* @param key the encryption key * @param key the encryption key
@ -1378,10 +1387,11 @@ public class Cipher {
} }
/** /**
* Initializes this cipher with a key, a set of algorithm * Initializes this {@code Cipher} object with a key, a set of algorithm
* parameters, and a source of randomness. * parameters, and a source of randomness.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code Cipher} object is initialized for one of the following four
* operations:
* encryption, decryption, key wrapping or key unwrapping, depending * encryption, decryption, key wrapping or key unwrapping, depending
* on the value of {@code opmode}. * on the value of {@code opmode}.
* *
@ -1406,12 +1416,12 @@ public class Cipher {
* them from {@code random}. * them from {@code random}.
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code Cipher} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a {@code Cipher}
* equivalent to creating a new instance of that cipher and initializing * object is equivalent to creating a new instance of that {@code Cipher}
* it. * object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of the * @param opmode the operation mode of this {@code Cipher} object
* following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE} or {@code UNWRAP_MODE}) * {@code WRAP_MODE} or {@code UNWRAP_MODE})
* @param key the encryption key * @param key the encryption key
@ -1455,10 +1465,11 @@ public class Cipher {
} }
/** /**
* Initializes this cipher with a key and a set of algorithm * Initializes this {@code Cipher} object with a key and a set of algorithm
* parameters. * parameters.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code Cipher} object is initialized for one of the following four
* operations:
* encryption, decryption, key wrapping or key unwrapping, depending * encryption, decryption, key wrapping or key unwrapping, depending
* on the value of {@code opmode}. * on the value of {@code opmode}.
* *
@ -1487,12 +1498,12 @@ public class Cipher {
* SecureRandom, a system-provided source of randomness will be used.) * SecureRandom, a system-provided source of randomness will be used.)
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code Cipher} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a {@code Cipher}
* equivalent to creating a new instance of that cipher and initializing * object is equivalent to creating a new instance of that {@code Cipher}
* it. * object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of the * @param opmode the operation mode of this {@code Cipher} object
* following: {@code ENCRYPT_MODE}, * this is one of the following: {@code ENCRYPT_MODE},
* {@code DECRYPT_MODE}, {@code WRAP_MODE} * {@code DECRYPT_MODE}, {@code WRAP_MODE}
* or {@code UNWRAP_MODE}) * or {@code UNWRAP_MODE})
* @param key the encryption key * @param key the encryption key
@ -1519,10 +1530,11 @@ public class Cipher {
} }
/** /**
* Initializes this cipher with a key, a set of algorithm * Initializes this {@code Cipher} object with a key, a set of algorithm
* parameters, and a source of randomness. * parameters, and a source of randomness.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code Cipher} object is initialized for one of the following four
* operations:
* encryption, decryption, key wrapping or key unwrapping, depending * encryption, decryption, key wrapping or key unwrapping, depending
* on the value of {@code opmode}. * on the value of {@code opmode}.
* *
@ -1547,12 +1559,12 @@ public class Cipher {
* them from {@code random}. * them from {@code random}.
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code Cipher} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a {@code Cipher}
* equivalent to creating a new instance of that cipher and initializing * object is equivalent to creating a new instance of that {@code Cipher}
* it. * object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of the * @param opmode the operation mode of this {@code Cipher} object
* following: {@code ENCRYPT_MODE}, * (this is one of the following: {@code ENCRYPT_MODE},
* {@code DECRYPT_MODE}, {@code WRAP_MODE} * {@code DECRYPT_MODE}, {@code WRAP_MODE}
* or {@code UNWRAP_MODE}) * or {@code UNWRAP_MODE})
* @param key the encryption key * @param key the encryption key
@ -1596,8 +1608,10 @@ public class Cipher {
} }
/** /**
* Initializes this cipher with the public key from the given certificate. * Initializes this {@code Cipher} object with the public key from the given
* <p> The cipher is initialized for one of the following four operations: * certificate.
* <p> The {@code Cipher} object is initialized for one of the following
* four operations:
* encryption, decryption, key wrapping or key unwrapping, depending * encryption, decryption, key wrapping or key unwrapping, depending
* on the value of {@code opmode}. * on the value of {@code opmode}.
* *
@ -1637,12 +1651,12 @@ public class Cipher {
* SecureRandom, a system-provided source of randomness will be used.) * SecureRandom, a system-provided source of randomness will be used.)
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code Cipher} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a {@code Cipher}
* equivalent to creating a new instance of that cipher and initializing * object is equivalent to creating a new instance of that {@code Cipher}
* it. * object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of the * @param opmode the operation mode of this {@code Cipher} object
* following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE} or {@code UNWRAP_MODE}) * {@code WRAP_MODE} or {@code UNWRAP_MODE})
* @param certificate the certificate * @param certificate the certificate
@ -1665,11 +1679,11 @@ public class Cipher {
} }
/** /**
* Initializes this cipher with the public key from the given certificate * Initializes this {@code Cipher} object with the public key from the given
* and a source of randomness. * certificate and a source of randomness.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code Cipher} object is initialized for one of the following four
* encryption, decryption, key wrapping * operations: encryption, decryption, key wrapping
* or key unwrapping, depending on * or key unwrapping, depending on
* the value of {@code opmode}. * the value of {@code opmode}.
* *
@ -1704,12 +1718,12 @@ public class Cipher {
* them from {@code random}. * them from {@code random}.
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code Cipher} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a {@code Cipher}
* equivalent to creating a new instance of that cipher and initializing * object is equivalent to creating a new instance of that {@code Cipher}
* it. * object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of the * @param opmode the operation mode of this {@code Cipher} object
* following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE} or {@code UNWRAP_MODE}) * {@code WRAP_MODE} or {@code UNWRAP_MODE})
* @param certificate the certificate * @param certificate the certificate
@ -1782,9 +1796,11 @@ public class Cipher {
} }
/** /**
* Ensures that cipher is in a valid state for update() and doFinal() * Ensures that {@code Cipher} object is in a valid state for update() and
* calls - should be initialized and in ENCRYPT_MODE or DECRYPT_MODE. * doFinal() calls - should be initialized and in ENCRYPT_MODE or
* @throws IllegalStateException if this cipher is not in valid state * DECRYPT_MODE.
* @throws IllegalStateException if this {@code Cipher} object is not in
* valid state
*/ */
private void checkCipherState() { private void checkCipherState() {
if (!(this instanceof NullCipher)) { if (!(this instanceof NullCipher)) {
@ -1801,8 +1817,8 @@ public class Cipher {
/** /**
* Continues a multiple-part encryption or decryption operation * Continues a multiple-part encryption or decryption operation
* (depending on how this cipher was initialized), processing another data * (depending on how this {@code Cipher} object was initialized),
* part. * processing another data part.
* *
* <p>The bytes in the {@code input} buffer are processed, and the * <p>The bytes in the {@code input} buffer are processed, and the
* result is stored in a new buffer. * result is stored in a new buffer.
@ -1816,8 +1832,8 @@ public class Cipher {
* cipher is a block cipher and the input data is too short to result in a * cipher is a block cipher and the input data is too short to result in a
* new block * new block
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object is in a
* (e.g., has not been initialized) * wrong state (e.g., has not been initialized)
*/ */
public final byte[] update(byte[] input) { public final byte[] update(byte[] input) {
checkCipherState(); checkCipherState();
@ -1836,8 +1852,8 @@ public class Cipher {
/** /**
* Continues a multiple-part encryption or decryption operation * Continues a multiple-part encryption or decryption operation
* (depending on how this cipher was initialized), processing another data * (depending on how this {@code Cipher} object was initialized),
* part. * processing another data part.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, are processed, * buffer, starting at {@code inputOffset} inclusive, are processed,
@ -1851,12 +1867,12 @@ public class Cipher {
* starts * starts
* @param inputLen the input length * @param inputLen the input length
* *
* @return the new buffer with the result, or null if this * @return the new buffer with the result, or {@code null} if this
* cipher is a block cipher and the input data is too short to result in a * cipher is a block cipher and the input data is too short to result in a
* new block. * new block.
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
*/ */
public final byte[] update(byte[] input, int inputOffset, int inputLen) { public final byte[] update(byte[] input, int inputOffset, int inputLen) {
checkCipherState(); checkCipherState();
@ -1876,8 +1892,8 @@ public class Cipher {
/** /**
* Continues a multiple-part encryption or decryption operation * Continues a multiple-part encryption or decryption operation
* (depending on how this cipher was initialized), processing another data * (depending on how this {@code Cipher} object was initialized),
* part. * processing another data part.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, are processed, * buffer, starting at {@code inputOffset} inclusive, are processed,
@ -1905,8 +1921,8 @@ public class Cipher {
* *
* @return the number of bytes stored in {@code output} * @return the number of bytes stored in {@code output}
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws ShortBufferException if the given output buffer is too small * @throws ShortBufferException if the given output buffer is too small
* to hold the result * to hold the result
*/ */
@ -1931,8 +1947,8 @@ public class Cipher {
/** /**
* Continues a multiple-part encryption or decryption operation * Continues a multiple-part encryption or decryption operation
* (depending on how this cipher was initialized), processing another data * (depending on how this {@code Cipher} object was initialized),
* part. * processing another data part.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, are processed, * buffer, starting at {@code inputOffset} inclusive, are processed,
@ -1963,8 +1979,8 @@ public class Cipher {
* *
* @return the number of bytes stored in {@code output} * @return the number of bytes stored in {@code output}
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws ShortBufferException if the given output buffer is too small * @throws ShortBufferException if the given output buffer is too small
* to hold the result * to hold the result
*/ */
@ -1990,8 +2006,8 @@ public class Cipher {
/** /**
* Continues a multiple-part encryption or decryption operation * Continues a multiple-part encryption or decryption operation
* (depending on how this cipher was initialized), processing another data * (depending on how this {@code Cipher} object was initialized),
* part. * processing another data part.
* *
* <p>All {@code input.remaining()} bytes starting at * <p>All {@code input.remaining()} bytes starting at
* {@code input.position()} are processed. The result is stored * {@code input.position()} are processed. The result is stored
@ -2017,8 +2033,8 @@ public class Cipher {
* *
* @return the number of bytes stored in {@code output} * @return the number of bytes stored in {@code output}
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws IllegalArgumentException if input and output are the * @throws IllegalArgumentException if input and output are the
* same object * same object
* @throws ReadOnlyBufferException if the output buffer is read-only * @throws ReadOnlyBufferException if the output buffer is read-only
@ -2047,7 +2063,7 @@ public class Cipher {
/** /**
* Finishes a multiple-part encryption or decryption operation, depending * Finishes a multiple-part encryption or decryption operation, depending
* on how this cipher was initialized. * on how this {@code Cipher} object was initialized.
* *
* <p>Input data that may have been buffered during a previous * <p>Input data that may have been buffered during a previous
* {@code update} operation is processed, with padding (if requested) * {@code update} operation is processed, with padding (if requested)
@ -2057,29 +2073,30 @@ public class Cipher {
* case of decryption. * case of decryption.
* The result is stored in a new buffer. * The result is stored in a new buffer.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code Cipher} object
* it was in when previously initialized via a call to {@code init}. * to the state it was in when previously initialized via a call to
* {@code init}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code init}) more data. * {@code init}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code Cipher} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* @return the new buffer with the result * @return the new buffer with the result
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws IllegalBlockSizeException if this cipher is a block cipher, * @throws IllegalBlockSizeException if this cipher is a block cipher,
* no padding has been requested (only in encryption mode), and the total * no padding has been requested (only in encryption mode), and the total
* input length of the data processed by this cipher is not a multiple of * input length of the data processed by this cipher is not a multiple of
* block size; or if this encryption algorithm is unable to * block size; or if this encryption algorithm is unable to
* process the input data provided. * process the input data provided.
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code Cipher} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the decrypted
* bounded by the appropriate padding bytes * data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code Cipher} object is decrypting
* AEAD mode (such as GCM/CCM), and the received authentication tag * in an AEAD mode (such as GCM/CCM), and the received authentication tag
* does not match the calculated value * does not match the calculated value
*/ */
public final byte[] doFinal() public final byte[] doFinal()
@ -2092,7 +2109,7 @@ public class Cipher {
/** /**
* Finishes a multiple-part encryption or decryption operation, depending * Finishes a multiple-part encryption or decryption operation, depending
* on how this cipher was initialized. * on how this {@code Cipher} object was initialized.
* *
* <p>Input data that may have been buffered during a previous * <p>Input data that may have been buffered during a previous
* {@code update} operation is processed, with padding (if requested) * {@code update} operation is processed, with padding (if requested)
@ -2109,14 +2126,15 @@ public class Cipher {
* {@link #getOutputSize(int) getOutputSize} to determine how big * {@link #getOutputSize(int) getOutputSize} to determine how big
* the output buffer should be. * the output buffer should be.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code Cipher} object
* it was in when previously initialized via a call to {@code init}. * to the state it was in when previously initialized via a call to
* {@code init}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code init}) more data. * {@code init}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code Cipher} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* @param output the buffer for the result * @param output the buffer for the result
* @param outputOffset the offset in {@code output} where the result * @param outputOffset the offset in {@code output} where the result
@ -2124,8 +2142,8 @@ public class Cipher {
* *
* @return the number of bytes stored in {@code output} * @return the number of bytes stored in {@code output}
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws IllegalBlockSizeException if this cipher is a block cipher, * @throws IllegalBlockSizeException if this cipher is a block cipher,
* no padding has been requested (only in encryption mode), and the total * no padding has been requested (only in encryption mode), and the total
* input length of the data processed by this cipher is not a multiple of * input length of the data processed by this cipher is not a multiple of
@ -2133,11 +2151,11 @@ public class Cipher {
* process the input data provided. * process the input data provided.
* @throws ShortBufferException if the given output buffer is too small * @throws ShortBufferException if the given output buffer is too small
* to hold the result * to hold the result
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code Cipher} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the
* bounded by the appropriate padding bytes * decrypted data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code Cipher} object is decrypting
* AEAD mode (such as GCM/CCM), and the received authentication tag * in an AEAD mode (such as GCM/CCM), and the received authentication tag
* does not match the calculated value * does not match the calculated value
*/ */
public final int doFinal(byte[] output, int outputOffset) public final int doFinal(byte[] output, int outputOffset)
@ -2157,7 +2175,7 @@ public class Cipher {
/** /**
* Encrypts or decrypts data in a single-part operation, or finishes a * Encrypts or decrypts data in a single-part operation, or finishes a
* multiple-part operation. The data is encrypted or decrypted, * multiple-part operation. The data is encrypted or decrypted,
* depending on how this cipher was initialized. * depending on how this {@code Cipher} object was initialized.
* *
* <p>The bytes in the {@code input} buffer, and any input bytes that * <p>The bytes in the {@code input} buffer, and any input bytes that
* may have been buffered during a previous {@code update} operation, * may have been buffered during a previous {@code update} operation,
@ -2167,31 +2185,32 @@ public class Cipher {
* case of decryption. * case of decryption.
* The result is stored in a new buffer. * The result is stored in a new buffer.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code Cipher} object
* it was in when previously initialized via a call to {@code init}. * to the state it was in when previously initialized via a call to
* {@code init}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code init}) more data. * {@code init}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code Cipher} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* @param input the input buffer * @param input the input buffer
* *
* @return the new buffer with the result * @return the new buffer with the result
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws IllegalBlockSizeException if this cipher is a block cipher, * @throws IllegalBlockSizeException if this cipher is a block cipher,
* no padding has been requested (only in encryption mode), and the total * no padding has been requested (only in encryption mode), and the total
* input length of the data processed by this cipher is not a multiple of * input length of the data processed by this cipher is not a multiple of
* block size; or if this encryption algorithm is unable to * block size; or if this encryption algorithm is unable to
* process the input data provided. * process the input data provided.
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code Cipher} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the
* bounded by the appropriate padding bytes * decrypted data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code Cipher} object is decrypting
* AEAD mode (such as GCM/CCM), and the received authentication tag * in an AEAD mode (such as GCM/CCM), and the received authentication tag
* does not match the calculated value * does not match the calculated value
*/ */
public final byte[] doFinal(byte[] input) public final byte[] doFinal(byte[] input)
@ -2210,7 +2229,7 @@ public class Cipher {
/** /**
* Encrypts or decrypts data in a single-part operation, or finishes a * Encrypts or decrypts data in a single-part operation, or finishes a
* multiple-part operation. The data is encrypted or decrypted, * multiple-part operation. The data is encrypted or decrypted,
* depending on how this cipher was initialized. * depending on how this {@code Cipher} object was initialized.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, and any input * buffer, starting at {@code inputOffset} inclusive, and any input
@ -2221,14 +2240,15 @@ public class Cipher {
* case of decryption. * case of decryption.
* The result is stored in a new buffer. * The result is stored in a new buffer.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code Cipher} object
* it was in when previously initialized via a call to {@code init}. * to the state it was in when previously initialized via a call to
* {@code init}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code init}) more data. * {@code init}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code Cipher} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* @param input the input buffer * @param input the input buffer
* @param inputOffset the offset in {@code input} where the input * @param inputOffset the offset in {@code input} where the input
@ -2237,18 +2257,18 @@ public class Cipher {
* *
* @return the new buffer with the result * @return the new buffer with the result
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws IllegalBlockSizeException if this cipher is a block cipher, * @throws IllegalBlockSizeException if this cipher is a block cipher,
* no padding has been requested (only in encryption mode), and the total * no padding has been requested (only in encryption mode), and the total
* input length of the data processed by this cipher is not a multiple of * input length of the data processed by this cipher is not a multiple of
* block size; or if this encryption algorithm is unable to * block size; or if this encryption algorithm is unable to
* process the input data provided. * process the input data provided.
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code Cipher} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the decrypted
* bounded by the appropriate padding bytes * data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code Cipher} object is decrypting
* AEAD mode (such as GCM/CCM), and the received authentication tag * in an AEAD mode (such as GCM/CCM), and the received authentication tag
* does not match the calculated value * does not match the calculated value
*/ */
public final byte[] doFinal(byte[] input, int inputOffset, int inputLen) public final byte[] doFinal(byte[] input, int inputOffset, int inputLen)
@ -2268,7 +2288,7 @@ public class Cipher {
/** /**
* Encrypts or decrypts data in a single-part operation, or finishes a * Encrypts or decrypts data in a single-part operation, or finishes a
* multiple-part operation. The data is encrypted or decrypted, * multiple-part operation. The data is encrypted or decrypted,
* depending on how this cipher was initialized. * depending on how this {@code Cipher} object was initialized.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, and any input * buffer, starting at {@code inputOffset} inclusive, and any input
@ -2285,14 +2305,15 @@ public class Cipher {
* {@link #getOutputSize(int) getOutputSize} to determine how big * {@link #getOutputSize(int) getOutputSize} to determine how big
* the output buffer should be. * the output buffer should be.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code Cipher} object
* it was in when previously initialized via a call to {@code init}. * to the state it was in when previously initialized via a call to
* {@code init}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code init}) more data. * {@code init}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code Cipher} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* <p>Note: this method should be copy-safe, which means the * <p>Note: this method should be copy-safe, which means the
* {@code input} and {@code output} buffers can reference * {@code input} and {@code output} buffers can reference
@ -2307,8 +2328,8 @@ public class Cipher {
* *
* @return the number of bytes stored in {@code output} * @return the number of bytes stored in {@code output}
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws IllegalBlockSizeException if this cipher is a block cipher, * @throws IllegalBlockSizeException if this cipher is a block cipher,
* no padding has been requested (only in encryption mode), and the total * no padding has been requested (only in encryption mode), and the total
* input length of the data processed by this cipher is not a multiple of * input length of the data processed by this cipher is not a multiple of
@ -2316,11 +2337,11 @@ public class Cipher {
* process the input data provided. * process the input data provided.
* @throws ShortBufferException if the given output buffer is too small * @throws ShortBufferException if the given output buffer is too small
* to hold the result * to hold the result
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code Cipher} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the decrypted
* bounded by the appropriate padding bytes * data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code Cipher} object is decrypting
* AEAD mode (such as GCM/CCM), and the received authentication tag * in an AEAD mode (such as GCM/CCM), and the received authentication tag
* does not match the calculated value * does not match the calculated value
*/ */
public final int doFinal(byte[] input, int inputOffset, int inputLen, public final int doFinal(byte[] input, int inputOffset, int inputLen,
@ -2343,7 +2364,7 @@ public class Cipher {
/** /**
* Encrypts or decrypts data in a single-part operation, or finishes a * Encrypts or decrypts data in a single-part operation, or finishes a
* multiple-part operation. The data is encrypted or decrypted, * multiple-part operation. The data is encrypted or decrypted,
* depending on how this cipher was initialized. * depending on how this {@code Cipher} object was initialized.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, and any input * buffer, starting at {@code inputOffset} inclusive, and any input
@ -2362,14 +2383,15 @@ public class Cipher {
* {@link #getOutputSize(int) getOutputSize} to determine how big * {@link #getOutputSize(int) getOutputSize} to determine how big
* the output buffer should be. * the output buffer should be.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code Cipher} object
* it was in when previously initialized via a call to {@code init}. * to the state it was in when previously initialized via a call to
* {@code init}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code init}) more data. * {@code init}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code Cipher} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* <p>Note: this method should be copy-safe, which means the * <p>Note: this method should be copy-safe, which means the
* {@code input} and {@code output} buffers can reference * {@code input} and {@code output} buffers can reference
@ -2386,8 +2408,8 @@ public class Cipher {
* *
* @return the number of bytes stored in {@code output} * @return the number of bytes stored in {@code output}
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws IllegalBlockSizeException if this cipher is a block cipher, * @throws IllegalBlockSizeException if this cipher is a block cipher,
* no padding has been requested (only in encryption mode), and the total * no padding has been requested (only in encryption mode), and the total
* input length of the data processed by this cipher is not a multiple of * input length of the data processed by this cipher is not a multiple of
@ -2395,11 +2417,11 @@ public class Cipher {
* process the input data provided. * process the input data provided.
* @throws ShortBufferException if the given output buffer is too small * @throws ShortBufferException if the given output buffer is too small
* to hold the result * to hold the result
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code Cipher} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the decrypted
* bounded by the appropriate padding bytes * data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code Cipher} object is decrypting
* AEAD mode (such as GCM/CCM), and the received authentication tag * in an AEAD mode (such as GCM/CCM), and the received authentication tag
* does not match the calculated value * does not match the calculated value
*/ */
public final int doFinal(byte[] input, int inputOffset, int inputLen, public final int doFinal(byte[] input, int inputOffset, int inputLen,
@ -2423,7 +2445,7 @@ public class Cipher {
/** /**
* Encrypts or decrypts data in a single-part operation, or finishes a * Encrypts or decrypts data in a single-part operation, or finishes a
* multiple-part operation. The data is encrypted or decrypted, * multiple-part operation. The data is encrypted or decrypted,
* depending on how this cipher was initialized. * depending on how this {@code Cipher} object was initialized.
* *
* <p>All {@code input.remaining()} bytes starting at * <p>All {@code input.remaining()} bytes starting at
* {@code input.position()} are processed. * {@code input.position()} are processed.
@ -2442,14 +2464,15 @@ public class Cipher {
* {@link #getOutputSize(int) getOutputSize} to determine how big * {@link #getOutputSize(int) getOutputSize} to determine how big
* the output buffer should be. * the output buffer should be.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code Cipher} object
* it was in when previously initialized via a call to {@code init}. * to the state it was in when previously initialized via a call to
* {@code init}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code init}) more data. * {@code init}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code Cipher} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* <p>Note: this method should be copy-safe, which means the * <p>Note: this method should be copy-safe, which means the
* {@code input} and {@code output} buffers can reference * {@code input} and {@code output} buffers can reference
@ -2461,8 +2484,8 @@ public class Cipher {
* *
* @return the number of bytes stored in {@code output} * @return the number of bytes stored in {@code output}
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* @throws IllegalArgumentException if input and output are the * @throws IllegalArgumentException if input and output are the
* same object * same object
* @throws ReadOnlyBufferException if the output buffer is read-only * @throws ReadOnlyBufferException if the output buffer is read-only
@ -2473,11 +2496,11 @@ public class Cipher {
* process the input data provided. * process the input data provided.
* @throws ShortBufferException if there is insufficient space in the * @throws ShortBufferException if there is insufficient space in the
* output buffer * output buffer
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code Cipher} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the
* bounded by the appropriate padding bytes * decrypted data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code Cipher} object is decrypting
* AEAD mode (such as GCM/CCM), and the received authentication tag * in an AEAD mode (such as GCM/CCM), and the received authentication tag
* does not match the calculated value * does not match the calculated value
* *
* @since 1.5 * @since 1.5
@ -2509,7 +2532,7 @@ public class Cipher {
* *
* @return the wrapped key * @return the wrapped key
* *
* @throws IllegalStateException if this cipher is in a wrong * @throws IllegalStateException if this {@code Cipher} object is in a wrong
* state (e.g., has not been initialized) * state (e.g., has not been initialized)
* *
* @throws IllegalBlockSizeException if this cipher is a block * @throws IllegalBlockSizeException if this cipher is a block
@ -2554,8 +2577,8 @@ public class Cipher {
* *
* @return the unwrapped key * @return the unwrapped key
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized) * is in a wrong state (e.g., has not been initialized)
* *
* @throws NoSuchAlgorithmException if no installed providers * @throws NoSuchAlgorithmException if no installed providers
* can create keys of type {@code wrappedKeyType} for the * can create keys of type {@code wrappedKeyType} for the
@ -2654,7 +2677,7 @@ public class Cipher {
/** /**
* Returns an {code AlgorithmParameterSpec} object which contains * Returns an {code AlgorithmParameterSpec} object which contains
* the maximum cipher parameter value according to the * the maximum {@code Cipher} parameter value according to the
* jurisdiction policy file. If JCE unlimited strength jurisdiction * jurisdiction policy file. If JCE unlimited strength jurisdiction
* policy files are installed or there is no maximum limit on the * policy files are installed or there is no maximum limit on the
* parameters for the specified transformation in the policy file, * parameters for the specified transformation in the policy file,
@ -2680,20 +2703,20 @@ public class Cipher {
* Continues a multi-part update of the Additional Authentication * Continues a multi-part update of the Additional Authentication
* Data (AAD). * Data (AAD).
* <p> * <p>
* Calls to this method provide AAD to the cipher when operating in * Calls to this method provide AAD to the {@code Cipher} object
* modes such as AEAD (GCM/CCM). If this cipher is operating in * when operating in modes such as AEAD (GCM/CCM). If this
* either GCM or CCM mode, all AAD must be supplied before beginning * {@code Cipher} object is operating in either GCM or CCM mode, all AAD
* operations on the ciphertext (via the {@code update} and * must be supplied before beginning operations on the ciphertext
* {@code doFinal} methods). * (via the {@code update} and {@code doFinal} methods).
* *
* @param src the buffer containing the Additional Authentication Data * @param src the buffer containing the Additional Authentication Data
* *
* @throws IllegalArgumentException if the {@code src} * @throws IllegalArgumentException if the {@code src}
* byte array is {@code null} * byte array is {@code null}
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized), does not accept AAD, or if * is in a wrong state (e.g., has not been initialized),
* operating in either GCM or CCM mode and one of the {@code update} * does not accept AAD, or if operating in either GCM or CCM mode and
* methods has already been called for the active * one of the {@code update} methods has already been called for the active
* encryption/decryption operation * encryption/decryption operation
* @throws UnsupportedOperationException if the corresponding method * @throws UnsupportedOperationException if the corresponding method
* in the {@code CipherSpi} has not been overridden by an * in the {@code CipherSpi} has not been overridden by an
@ -2713,11 +2736,11 @@ public class Cipher {
* Continues a multi-part update of the Additional Authentication * Continues a multi-part update of the Additional Authentication
* Data (AAD), using a subset of the provided buffer. * Data (AAD), using a subset of the provided buffer.
* <p> * <p>
* Calls to this method provide AAD to the cipher when operating in * Calls to this method provide AAD to the {@code Cipher} object
* modes such as AEAD (GCM/CCM). If this cipher is operating in * when operating in modes such as AEAD (GCM/CCM). If this
* either GCM or CCM mode, all AAD must be supplied before beginning * {@code Cipher} object is operating in either GCM or CCM mode,
* operations on the ciphertext (via the {@code update} * all AAD must be supplied before beginning operations on the
* and {@code doFinal} methods). * ciphertext (via the {@code update} and {@code doFinal} methods).
* *
* @param src the buffer containing the AAD * @param src the buffer containing the AAD
* @param offset the offset in {@code src} where the AAD input starts * @param offset the offset in {@code src} where the AAD input starts
@ -2728,10 +2751,10 @@ public class Cipher {
* is less than 0, or the sum of the {@code offset} and * is less than 0, or the sum of the {@code offset} and
* {@code len} is greater than the length of the * {@code len} is greater than the length of the
* {@code src} byte array * {@code src} byte array
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized), does not accept AAD, or if * is in a wrong state (e.g., has not been initialized),
* operating in either GCM or CCM mode and one of the {@code update} * does not accept AAD, or if operating in either GCM or CCM mode and
* methods has already been called for the active * one of the {@code update} methods has already been called for the active
* encryption/decryption operation * encryption/decryption operation
* @throws UnsupportedOperationException if the corresponding method * @throws UnsupportedOperationException if the corresponding method
* in the {@code CipherSpi} has not been overridden by an * in the {@code CipherSpi} has not been overridden by an
@ -2759,11 +2782,11 @@ public class Cipher {
* Continues a multi-part update of the Additional Authentication * Continues a multi-part update of the Additional Authentication
* Data (AAD). * Data (AAD).
* <p> * <p>
* Calls to this method provide AAD to the cipher when operating in * Calls to this method provide AAD to the {@code Cipher} object
* modes such as AEAD (GCM/CCM). If this cipher is operating in * when operating in modes such as AEAD (GCM/CCM). If this
* either GCM or CCM mode, all AAD must be supplied before beginning * {@code Cipher} object is operating in either GCM or CCM mode, all AAD
* operations on the ciphertext (via the {@code update} * must be supplied before beginning operations on the ciphertext
* and {@code doFinal} methods). * (via the {@code update} and {@code doFinal} methods).
* <p> * <p>
* All {@code src.remaining()} bytes starting at * All {@code src.remaining()} bytes starting at
* {@code src.position()} are processed. * {@code src.position()} are processed.
@ -2774,10 +2797,10 @@ public class Cipher {
* *
* @throws IllegalArgumentException if the {@code src ByteBuffer} * @throws IllegalArgumentException if the {@code src ByteBuffer}
* is {@code null} * is {@code null}
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code Cipher} object
* (e.g., has not been initialized), does not accept AAD, or if * is in a wrong state (e.g., has not been initialized),
* operating in either GCM or CCM mode and one of the {@code update} * does not accept AAD, or if operating in either GCM or CCM mode and
* methods has already been called for the active * one of the {@code update} methods has already been called for the active
* encryption/decryption operation * encryption/decryption operation
* @throws UnsupportedOperationException if the corresponding method * @throws UnsupportedOperationException if the corresponding method
* in the {@code CipherSpi} has not been overridden by an * in the {@code CipherSpi} has not been overridden by an
@ -2801,14 +2824,15 @@ public class Cipher {
} }
/** /**
* Returns a String representation of this cipher. * Returns a {@code String} representation of this {@code Cipher} object.
* *
* @implNote * @implNote
* This implementation returns a String containing the transformation, * This implementation returns a {@code String} containing the
* mode, and provider of this cipher. * transformation, mode, and provider of this {@code Cipher} object.
* The exact format of the String is unspecified and is subject to change. * The exact format of the {@code String} is unspecified and is subject
* to change.
* *
* @return a String describing this cipher * @return a String describing this {@code Cipher} object
*/ */
@Override @Override
public String toString() { public String toString() {

107
src/java.base/share/classes/javax/crypto/CipherInputStream.java
View file

@ -30,38 +30,40 @@ import java.io.IOException;
import java.io.InputStream; import java.io.InputStream;
/** /**
* A CipherInputStream is composed of an InputStream and a Cipher so * A {@code CipherInputStream} is composed of an {@code InputStream}
* that read() methods return data that are read in from the * and a {@code Cipher} object so that read() methods return data that are
* underlying InputStream but have been additionally processed by the * read in from the underlying {@code InputStream} but have been
* Cipher. The Cipher must be fully initialized before being used by * additionally processed by the {@code Cipher} object. The {@code Cipher}
* a CipherInputStream. * object must be fully initialized before being used by a
* {@code CipherInputStream}.
* *
* <p> For example, if the Cipher is initialized for decryption, the * <p> For example, if the {@code Cipher} object is initialized for decryption,
* CipherInputStream will attempt to read in data and decrypt them, * the {@code CipherInputStream} will attempt to read in data and decrypt
* before returning the decrypted data. * them, before returning the decrypted data.
* *
* <p> This class adheres strictly to the semantics, especially the * <p> This class adheres strictly to the semantics, especially the
* failure semantics, of its ancestor classes * failure semantics, of its ancestor classes
* java.io.FilterInputStream and java.io.InputStream. This class has * {@code java.io.FilterInputStream} and {@code java.io.InputStream}.
* exactly those methods specified in its ancestor classes, and * This class has exactly those methods specified in its ancestor classes, and
* overrides them all. Moreover, this class catches all exceptions * overrides them all. Moreover, this class catches all exceptions
* that are not thrown by its ancestor classes. In particular, the * that are not thrown by its ancestor classes. In particular, the
* <code>skip</code> method skips, and the <code>available</code> * {@code skip} method skips, and the {@code available}
* method counts only data that have been processed by the encapsulated Cipher. * method counts only data that have been processed by the encapsulated
* This class may catch BadPaddingException and other exceptions thrown by * {@code Cipher} object.
* failed integrity checks during decryption. These exceptions are not * This class may catch {@code BadPaddingException} and other exceptions
* thrown by failed integrity checks during decryption. These exceptions are not
* re-thrown, so the client may not be informed that integrity checks * re-thrown, so the client may not be informed that integrity checks
* failed. Because of this behavior, this class may not be suitable * failed. Because of this behavior, this class may not be suitable
* for use with decryption in an authenticated mode of operation (e.g. GCM). * for use with decryption in an authenticated mode of operation (e.g. GCM).
* Applications that require authenticated encryption can use the Cipher API * Applications that require authenticated encryption can use the
* directly as an alternative to using this class. * {@code Cipher} API directly as an alternative to using this class.
* *
* <p> It is crucial for a programmer using this class not to use * <p> It is crucial for a programmer using this class not to use
* methods that are not defined or overridden in this class (such as a * methods that are not defined or overridden in this class (such as a
* new method or constructor that is later added to one of the super * new method or constructor that is later added to one of the super
* classes), because the design and implementation of those methods * classes), because the design and implementation of those methods
* are unlikely to have considered security impact with regard to * are unlikely to have considered security impact with regard to
* CipherInputStream. * {@code CipherInputStream}.
* *
* @author Li Gong * @author Li Gong
* @see java.io.InputStream * @see java.io.InputStream
@ -100,7 +102,7 @@ public class CipherInputStream extends FilterInputStream {
/** /**
* Ensure obuffer is big enough for the next update or doFinal * Ensure obuffer is big enough for the next update or doFinal
* operation, given the input length <code>inLen</code> (in bytes) * operation, given the input length {@code inLen} (in bytes)
* The ostart and ofinish indices are reset to 0. * The ostart and ofinish indices are reset to 0.
* *
* @param inLen the input length (in bytes) * @param inLen the input length (in bytes)
@ -163,13 +165,13 @@ public class CipherInputStream extends FilterInputStream {
} }
/** /**
* Constructs a CipherInputStream from an InputStream and a * Constructs a {@code CipherInputStream} from an
* Cipher. * {@code InputStream} and a {@code Cipher} object.
* <br>Note: if the specified input stream or cipher is * <br>Note: if the specified input stream or cipher is
* null, a NullPointerException may be thrown later when * {@code null}, a {@code NullPointerException} may be thrown later when
* they are used. * they are used.
* @param is the to-be-processed input stream * @param is the to-be-processed input stream
* @param c an initialized Cipher object * @param c an initialized {@code Cipher} object
*/ */
public CipherInputStream(InputStream is, Cipher c) { public CipherInputStream(InputStream is, Cipher c) {
super(is); super(is);
@ -178,11 +180,12 @@ public class CipherInputStream extends FilterInputStream {
} }
/** /**
* Constructs a CipherInputStream from an InputStream without * Constructs a {@code CipherInputStream} from an
* specifying a Cipher. This has the effect of constructing a * {@code InputStream} without specifying a {@code Cipher} object.
* CipherInputStream using a NullCipher. * This has the effect of constructing a {@code CipherInputStream}
* <br>Note: if the specified input stream is null, a * using a {@code NullCipher}.
* NullPointerException may be thrown later when it is used. * <br>Note: if the specified input stream is {@code null}, a
* {@code NullPointerException} may be thrown later when it is used.
* @param is the to-be-processed input stream * @param is the to-be-processed input stream
*/ */
protected CipherInputStream(InputStream is) { protected CipherInputStream(InputStream is) {
@ -193,14 +196,14 @@ public class CipherInputStream extends FilterInputStream {
/** /**
* Reads the next byte of data from this input stream. The value * Reads the next byte of data from this input stream. The value
* byte is returned as an <code>int</code> in the range * byte is returned as an {@code int} in the range
* <code>0</code> to <code>255</code>. If no byte is available * {@code 0} to {@code 255}. If no byte is available
* because the end of the stream has been reached, the value * because the end of the stream has been reached, the value
* <code>-1</code> is returned. This method blocks until input data * {@code -1} is returned. This method blocks until input data
* is available, the end of the stream is detected, or an exception * is available, the end of the stream is detected, or an exception
* is thrown. * is thrown.
* *
* @return the next byte of data, or <code>-1</code> if the end of the * @return the next byte of data, or {@code -1} if the end of the
* stream is reached. * stream is reached.
* @exception IOException if an I/O error occurs. * @exception IOException if an I/O error occurs.
*/ */
@ -216,16 +219,16 @@ public class CipherInputStream extends FilterInputStream {
} }
/** /**
* Reads up to <code>b.length</code> bytes of data from this input * Reads up to {@code b.length} bytes of data from this input
* stream into an array of bytes. * stream into an array of bytes.
* <p> * <p>
* The <code>read</code> method of <code>InputStream</code> calls * The {@code read} method of {@code InputStream} calls
* the <code>read</code> method of three arguments with the arguments * the {@code read} method of three arguments with the arguments
* <code>b</code>, <code>0</code>, and <code>b.length</code>. * {@code b}, {@code 0}, and {@code b.length}.
* *
* @param b the buffer into which the data is read. * @param b the buffer into which the data is read.
* @return the total number of bytes read into the buffer, or * @return the total number of bytes read into the buffer, or
* <code>-1</code> is there is no more data because the end of * {@code -1} is there is no more data because the end of
* the stream has been reached. * the stream has been reached.
* @exception IOException if an I/O error occurs. * @exception IOException if an I/O error occurs.
* @see java.io.InputStream#read(byte[], int, int) * @see java.io.InputStream#read(byte[], int, int)
@ -236,17 +239,17 @@ public class CipherInputStream extends FilterInputStream {
} }
/** /**
* Reads up to <code>len</code> bytes of data from this input stream * Reads up to {@code len} bytes of data from this input stream
* into an array of bytes. This method blocks until some input is * into an array of bytes. This method blocks until some input is
* available. If the first argument is <code>null,</code> up to * available. If the first argument is {@code null}, up to
* <code>len</code> bytes are read and discarded. * {@code len} bytes are read and discarded.
* *
* @param b the buffer into which the data is read. * @param b the buffer into which the data is read.
* @param off the start offset in the destination array * @param off the start offset in the destination array
* <code>buf</code> * {@code buf}
* @param len the maximum number of bytes read. * @param len the maximum number of bytes read.
* @return the total number of bytes read into the buffer, or * @return the total number of bytes read into the buffer, or
* <code>-1</code> if there is no more data because the end of * {@code -1} if there is no more data because the end of
* the stream has been reached. * the stream has been reached.
* @exception IOException if an I/O error occurs. * @exception IOException if an I/O error occurs.
* @see java.io.InputStream#read() * @see java.io.InputStream#read()
@ -272,15 +275,15 @@ public class CipherInputStream extends FilterInputStream {
} }
/** /**
* Skips <code>n</code> bytes of input from the bytes that can be read * Skips {@code n} bytes of input from the bytes that can be read
* from this input stream without blocking. * from this input stream without blocking.
* *
* <p>Fewer bytes than requested might be skipped. * <p>Fewer bytes than requested might be skipped.
* The actual number of bytes skipped is equal to <code>n</code> or * The actual number of bytes skipped is equal to {@code n} or
* the result of a call to * the result of a call to
* {@link #available() available}, * {@link #available() available},
* whichever is smaller. * whichever is smaller.
* If <code>n</code> is less than zero, no bytes are skipped. * If {@code n} is less than zero, no bytes are skipped.
* *
* <p>The actual number of bytes skipped is returned. * <p>The actual number of bytes skipped is returned.
* *
@ -303,8 +306,8 @@ public class CipherInputStream extends FilterInputStream {
/** /**
* Returns the number of bytes that can be read from this input * Returns the number of bytes that can be read from this input
* stream without blocking. The <code>available</code> method of * stream without blocking. The {@code available} method of
* <code>InputStream</code> returns <code>0</code>. This method * {@code InputStream} returns {@code 0}. This method
* <B>should</B> be overridden by subclasses. * <B>should</B> be overridden by subclasses.
* *
* @return the number of bytes that can be read from this input stream * @return the number of bytes that can be read from this input stream
@ -320,8 +323,8 @@ public class CipherInputStream extends FilterInputStream {
* Closes this input stream and releases any system resources * Closes this input stream and releases any system resources
* associated with the stream. * associated with the stream.
* <p> * <p>
* The <code>close</code> method of <code>CipherInputStream</code> * The {@code close} method of {@code CipherInputStream}
* calls the <code>close</code> method of its underlying input * calls the {@code close} method of its underlying input
* stream. * stream.
* *
* @exception IOException if an I/O error occurs. * @exception IOException if an I/O error occurs.
@ -350,11 +353,11 @@ public class CipherInputStream extends FilterInputStream {
} }
/** /**
* Tests if this input stream supports the <code>mark</code> * Tests if this input stream supports the {@code mark}
* and <code>reset</code> methods, which it does not. * and {@code reset} methods, which it does not.
* *
* @return <code>false</code>, since this class does not support the * @return {@code false}, since this class does not support the
* <code>mark</code> and <code>reset</code> methods. * {@code mark} and {@code reset} methods.
* @see java.io.InputStream#mark(int) * @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset() * @see java.io.InputStream#reset()
*/ */

96
src/java.base/share/classes/javax/crypto/CipherOutputStream.java
View file

@ -28,36 +28,38 @@ package javax.crypto;
import java.io.*; import java.io.*;
/** /**
* A CipherOutputStream is composed of an OutputStream and a Cipher so * A {@code CipherOutputStream} is composed of an {@code OutputStream}
* that write() methods first process the data before writing them out * and a {@code Cipher} object so that write() methods first process the data
* to the underlying OutputStream. The cipher must be fully * before writing them out to the underlying {@code OutputStream}.
* initialized before being used by a CipherOutputStream. * The {@code Cipher} object must be fully initialized before being used by a
* {@code CipherOutputStream}.
* *
* <p> For example, if the cipher is initialized for encryption, the * <p> For example, if the {@code Cipher} object is initialized for encryption,
* CipherOutputStream will attempt to encrypt data before writing out the * the {@code CipherOutputStream} will attempt to encrypt data before
* encrypted data. * writing out the encrypted data.
* *
* <p> This class adheres strictly to the semantics, especially the * <p> This class adheres strictly to the semantics, especially the
* failure semantics, of its ancestor classes * failure semantics, of its ancestor classes
* java.io.OutputStream and java.io.FilterOutputStream. This class * {@code java.io.OutputStream} and
* has exactly those methods specified in its ancestor classes, and * {@code java.io.FilterOutputStream}.
* This class has exactly those methods specified in its ancestor classes, and
* overrides them all. Moreover, this class catches all exceptions * overrides them all. Moreover, this class catches all exceptions
* that are not thrown by its ancestor classes. In particular, this * that are not thrown by its ancestor classes. In particular, this
* class catches BadPaddingException and other exceptions thrown by * class catches {@code BadPaddingException} and other exceptions thrown by
* failed integrity checks during decryption. These exceptions are not * failed integrity checks during decryption. These exceptions are not
* re-thrown, so the client will not be informed that integrity checks * re-thrown, so the client will not be informed that integrity checks
* failed. Because of this behavior, this class may not be suitable * failed. Because of this behavior, this class may not be suitable
* for use with decryption in an authenticated mode of operation (e.g. GCM) * for use with decryption in an authenticated mode of operation (e.g. GCM)
* if the application requires explicit notification when authentication * if the application requires explicit notification when authentication
* fails. Such an application can use the Cipher API directly as an * fails. Such an application can use the {@code Cipher} API directly as
* alternative to using this class. * an alternative to using this class.
* *
* <p> It is crucial for a programmer using this class not to use * <p> It is crucial for a programmer using this class not to use
* methods that are not defined or overridden in this class (such as a * methods that are not defined or overridden in this class (such as a
* new method or constructor that is later added to one of the super * new method or constructor that is later added to one of the super
* classes), because the design and implementation of those methods * classes), because the design and implementation of those methods
* are unlikely to have considered security impact with regard to * are unlikely to have considered security impact with regard to
* CipherOutputStream. * {@code CipherOutputStream}.
* *
* @author Li Gong * @author Li Gong
* @see java.io.OutputStream * @see java.io.OutputStream
@ -87,7 +89,7 @@ public class CipherOutputStream extends FilterOutputStream {
/** /**
* Ensure obuffer is big enough for the next update or doFinal * Ensure obuffer is big enough for the next update or doFinal
* operation, given the input length <code>inLen</code> (in bytes) * operation, given the input length {@code inLen} (in bytes)
* *
* @param inLen the input length (in bytes) * @param inLen the input length (in bytes)
*/ */
@ -100,14 +102,14 @@ public class CipherOutputStream extends FilterOutputStream {
/** /**
* *
* Constructs a CipherOutputStream from an OutputStream and a * Constructs a {@code CipherOutputStream} from an
* Cipher. * {@code OutputStream} and a {@code Cipher} object.
* <br>Note: if the specified output stream or cipher is * <br>Note: if the specified output stream or cipher is
* null, a NullPointerException may be thrown later when * {@code null}, {@code a NullPointerException} may be thrown later when
* they are used. * they are used.
* *
* @param os the OutputStream object * @param os the {@code OutputStream} object
* @param c an initialized Cipher object * @param c an initialized {@code Cipher} object
*/ */
public CipherOutputStream(OutputStream os, Cipher c) { public CipherOutputStream(OutputStream os, Cipher c) {
super(os); super(os);
@ -116,13 +118,14 @@ public class CipherOutputStream extends FilterOutputStream {
} }
/** /**
* Constructs a CipherOutputStream from an OutputStream without * Constructs a {@code CipherOutputStream} from an
* specifying a Cipher. This has the effect of constructing a * {@code OutputStream} without specifying a {@code Cipher} object.
* CipherOutputStream using a NullCipher. * This has the effect of constructing a {@code CipherOutputStream}
* <br>Note: if the specified output stream is null, a * using a {@code NullCipher}.
* NullPointerException may be thrown later when it is used. * <br>Note: if the specified output stream is {@code null}, a
* {@code NullPointerException} may be thrown later when it is used.
* *
* @param os the OutputStream object * @param os the {@code OutputStream} object
*/ */
protected CipherOutputStream(OutputStream os) { protected CipherOutputStream(OutputStream os) {
super(os); super(os);
@ -133,7 +136,7 @@ public class CipherOutputStream extends FilterOutputStream {
/** /**
* Writes the specified byte to this output stream. * Writes the specified byte to this output stream.
* *
* @param b the <code>byte</code>. * @param b the {@code byte}.
* @exception IOException if an I/O error occurs. * @exception IOException if an I/O error occurs.
*/ */
@Override @Override
@ -152,16 +155,16 @@ public class CipherOutputStream extends FilterOutputStream {
} }
/** /**
* Writes <code>b.length</code> bytes from the specified byte array * Writes {@code b.length} bytes from the specified byte array
* to this output stream. * to this output stream.
* <p> * <p>
* The <code>write</code> method of * The {@code write} method of
* <code>CipherOutputStream</code> calls the <code>write</code> * {@code CipherOutputStream} calls the {@code write}
* method of three arguments with the three arguments * method of three arguments with the three arguments
* <code>b</code>, <code>0</code>, and <code>b.length</code>. * {@code b}, {@code 0}, and {@code b.length}.
* *
* @param b the data. * @param b the data.
* @exception NullPointerException if <code>b</code> is null. * @exception NullPointerException if {@code b} is {@code null}.
* @exception IOException if an I/O error occurs. * @exception IOException if an I/O error occurs.
* @see javax.crypto.CipherOutputStream#write(byte[], int, int) * @see javax.crypto.CipherOutputStream#write(byte[], int, int)
*/ */
@ -171,8 +174,8 @@ public class CipherOutputStream extends FilterOutputStream {
} }
/** /**
* Writes <code>len</code> bytes from the specified byte array * Writes {@code len} bytes from the specified byte array
* starting at offset <code>off</code> to this output stream. * starting at offset {@code off} to this output stream.
* *
* @param b the data. * @param b the data.
* @param off the start offset in the data. * @param off the start offset in the data.
@ -195,14 +198,15 @@ public class CipherOutputStream extends FilterOutputStream {
/** /**
* Flushes this output stream by forcing any buffered output bytes * Flushes this output stream by forcing any buffered output bytes
* that have already been processed by the encapsulated cipher object * that have already been processed by the encapsulated {@code Cipher}
* to be written out. * object to be written out.
* *
* <p>Any bytes buffered by the encapsulated cipher * <p>Any bytes buffered by the encapsulated {@code Cipher} object
* and waiting to be processed by it will not be written out. For example, * and waiting to be processed by it will not be written out. For example,
* if the encapsulated cipher is a block cipher, and the total number of * if the encapsulated {@code Cipher} object is a block cipher, and the
* bytes written using one of the <code>write</code> methods is less than * total number of bytes written using one of the {@code write}
* the cipher's block size, no bytes will be written out. * methods is less than the cipher's block size, no bytes will be written
* out.
* *
* @exception IOException if an I/O error occurs. * @exception IOException if an I/O error occurs.
*/ */
@ -217,14 +221,14 @@ public class CipherOutputStream extends FilterOutputStream {
* Closes this output stream and releases any system resources * Closes this output stream and releases any system resources
* associated with this stream. * associated with this stream.
* <p> * <p>
* This method invokes the <code>doFinal</code> method of the encapsulated * This method invokes the {@code doFinal} method of the encapsulated
* cipher object, which causes any bytes buffered by the encapsulated * {@code Cipher} object, which causes any bytes buffered by the
* cipher to be processed. The result is written out by calling the * encapsulated {@code Cipher} object to be processed. The result is written
* <code>flush</code> method of this output stream. * out by calling the {@code flush} method of this output stream.
* <p> * <p>
* This method resets the encapsulated cipher object to its initial state * This method resets the encapsulated {@code Cipher} object to its
* and calls the <code>close</code> method of the underlying output * initial state and calls the {@code close} method of the underlying
* stream. * output stream.
* *
* @exception IOException if an I/O error occurs. * @exception IOException if an I/O error occurs.
*/ */

156
src/java.base/share/classes/javax/crypto/CipherSpi.java
View file

@ -228,8 +228,8 @@ public abstract class CipherSpi {
* *
* @param mode the cipher mode * @param mode the cipher mode
* *
* @throws NoSuchAlgorithmException if the requested cipher mode does * @throws NoSuchAlgorithmException if the requested cipher mode
* not exist * does not exist
*/ */
protected abstract void engineSetMode(String mode) protected abstract void engineSetMode(String mode)
throws NoSuchAlgorithmException; throws NoSuchAlgorithmException;
@ -298,10 +298,11 @@ public abstract class CipherSpi {
protected abstract AlgorithmParameters engineGetParameters(); protected abstract AlgorithmParameters engineGetParameters();
/** /**
* Initializes this cipher with a key and a source * Initializes this {@code CipherSpi} object with a key and a source
* of randomness. * of randomness.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code CipherSpi} object is initialized for one of the
* following four operations:
* encryption, decryption, key wrapping or key unwrapping, depending on * encryption, decryption, key wrapping or key unwrapping, depending on
* the value of {@code opmode}. * the value of {@code opmode}.
* *
@ -325,13 +326,13 @@ public abstract class CipherSpi {
* requires any random bytes (e.g., for parameter generation), it will get * requires any random bytes (e.g., for parameter generation), it will get
* them from {@code random}. * them from {@code random}.
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code CipherSpi} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a
* equivalent to creating a new instance of that cipher and initializing * {@code CipherSpi} object is equivalent to creating a new instance
* it. * of that {@code CipherSpi} object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of * @param opmode the operation mode of this {@code CipherSpi} object
* the following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE} or {@code UNWRAP_MODE}) * {@code WRAP_MODE} or {@code UNWRAP_MODE})
* @param key the encryption key * @param key the encryption key
@ -350,10 +351,11 @@ public abstract class CipherSpi {
throws InvalidKeyException; throws InvalidKeyException;
/** /**
* Initializes this cipher with a key, a set of * Initializes this {@code CipherSpi} object with a key, a set of
* algorithm parameters, and a source of randomness. * algorithm parameters, and a source of randomness.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code CipherSpi} object is initialized for one of the
* following four operations:
* encryption, decryption, key wrapping or key unwrapping, depending on * encryption, decryption, key wrapping or key unwrapping, depending on
* the value of {@code opmode}. * the value of {@code opmode}.
* *
@ -377,15 +379,15 @@ public abstract class CipherSpi {
* requires any random bytes (e.g., for parameter generation), it will get * requires any random bytes (e.g., for parameter generation), it will get
* them from {@code random}. * them from {@code random}.
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code CipherSpi} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a
* equivalent to creating a new instance of that Cipher and initializing * {@code CipherSpi} object is equivalent to creating a new instance of that
* it. * {@code CipherSpi} object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of * @param opmode the operation mode of this {@code CipherSpi} object
* the following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE}> or {@code UNWRAP_MODE}) * {@code WRAP_MODE}, or {@code UNWRAP_MODE})
* @param key the encryption key * @param key the encryption key
* @param params the algorithm parameters * @param params the algorithm parameters
* @param random the source of randomness * @param random the source of randomness
@ -406,10 +408,11 @@ public abstract class CipherSpi {
throws InvalidKeyException, InvalidAlgorithmParameterException; throws InvalidKeyException, InvalidAlgorithmParameterException;
/** /**
* Initializes this cipher with a key, a set of * Initializes this {@code CipherSpi} object with a key, a set of
* algorithm parameters, and a source of randomness. * algorithm parameters, and a source of randomness.
* *
* <p>The cipher is initialized for one of the following four operations: * <p>The {@code CipherSpi} object is initialized for one of the
* following four operations:
* encryption, decryption, key wrapping or key unwrapping, depending on * encryption, decryption, key wrapping or key unwrapping, depending on
* the value of {@code opmode}. * the value of {@code opmode}.
* *
@ -433,15 +436,15 @@ public abstract class CipherSpi {
* requires any random bytes (e.g., for parameter generation), it will get * requires any random bytes (e.g., for parameter generation), it will get
* them from {@code random}. * them from {@code random}.
* *
* <p>Note that when a {@code Cipher} object is initialized, it loses all * <p>Note that when a {@code CipherSpi} object is initialized, it loses all
* previously-acquired state. In other words, initializing a cipher is * previously-acquired state. In other words, initializing a
* equivalent to creating a new instance of that cipher and initializing * {@code CipherSpi} object is equivalent to creating a new instance of that
* it. * {@code CipherSpi} object and initializing it.
* *
* @param opmode the operation mode of this cipher (this is one of * @param opmode the operation mode of this {@code CipherSpi} object
* the following: * (this is one of the following:
* {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, * {@code ENCRYPT_MODE}, {@code DECRYPT_MODE},
* {@code WRAP_MODE} or {@code UNWRAP_MODE}) * {@code WRAP_MODE}, or {@code UNWRAP_MODE})
* @param key the encryption key * @param key the encryption key
* @param params the algorithm parameters * @param params the algorithm parameters
* @param random the source of randomness * @param random the source of randomness
@ -463,8 +466,8 @@ public abstract class CipherSpi {
/** /**
* Continues a multiple-part encryption or decryption operation * Continues a multiple-part encryption or decryption operation
* (depending on how this cipher was initialized), processing another data * (depending on how this {@code CipherSpi} object was initialized),
* part. * processing another data part.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, are processed, * buffer, starting at {@code inputOffset} inclusive, are processed,
@ -483,8 +486,8 @@ public abstract class CipherSpi {
/** /**
* Continues a multiple-part encryption or decryption operation * Continues a multiple-part encryption or decryption operation
* (depending on how this cipher was initialized), processing another data * (depending on how this {@code CipherSpi} object was initialized),
* part. * processing another data part.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, are processed, * buffer, starting at {@code inputOffset} inclusive, are processed,
@ -514,8 +517,8 @@ public abstract class CipherSpi {
/** /**
* Continues a multiple-part encryption or decryption operation * Continues a multiple-part encryption or decryption operation
* (depending on how this cipher was initialized), processing another data * (depending on how this {@code CipherSpi} object was initialized),
* part. * processing another data part.
* *
* <p>All {@code input.remaining()} bytes starting at * <p>All {@code input.remaining()} bytes starting at
* {@code input.position()} are processed. The result is stored * {@code input.position()} are processed. The result is stored
@ -555,8 +558,8 @@ public abstract class CipherSpi {
/** /**
* Encrypts or decrypts data in a single-part operation, * Encrypts or decrypts data in a single-part operation,
* or finishes a multiple-part operation. * or finishes a multiple-part operation.
* The data is encrypted or decrypted, depending on how this cipher was * The data is encrypted or decrypted, depending on how this
* initialized. * {@code CipherSpi} object was initialized.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, and any input * buffer, starting at {@code inputOffset} inclusive, and any input
@ -567,15 +570,15 @@ public abstract class CipherSpi {
* case of decryption. * case of decryption.
* The result is stored in a new buffer. * The result is stored in a new buffer.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code CipherSpi} object
* it was in when previously initialized via a call to * to the state it was in when previously initialized via a call to
* {@code engineInit}. * {@code engineInit}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code engineInit}) more data. * {@code engineInit}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code CipherSpi} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* @param input the input buffer * @param input the input buffer
* @param inputOffset the offset in {@code input} where the input starts * @param inputOffset the offset in {@code input} where the input starts
@ -588,12 +591,12 @@ public abstract class CipherSpi {
* input length of the data processed by this cipher is not a multiple of * input length of the data processed by this cipher is not a multiple of
* block size; or if this encryption algorithm is unable to * block size; or if this encryption algorithm is unable to
* process the input data provided * process the input data provided
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code CipherSpi} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the decrypted
* bounded by the appropriate padding bytes * data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code CipherSpi} object is
* AEAD mode (such as GCM or CCM), and the received authentication tag * decrypting in an AEAD mode (such as GCM or CCM), and the received
* does not match the calculated value * authentication tag does not match the calculated value
*/ */
protected abstract byte[] engineDoFinal(byte[] input, int inputOffset, protected abstract byte[] engineDoFinal(byte[] input, int inputOffset,
int inputLen) int inputLen)
@ -602,8 +605,8 @@ public abstract class CipherSpi {
/** /**
* Encrypts or decrypts data in a single-part operation, * Encrypts or decrypts data in a single-part operation,
* or finishes a multiple-part operation. * or finishes a multiple-part operation.
* The data is encrypted or decrypted, depending on how this cipher was * The data is encrypted or decrypted, depending on how this
* initialized. * {@code CipherSpi} object was initialized.
* *
* <p>The first {@code inputLen} bytes in the {@code input} * <p>The first {@code inputLen} bytes in the {@code input}
* buffer, starting at {@code inputOffset} inclusive, and any input * buffer, starting at {@code inputOffset} inclusive, and any input
@ -618,15 +621,15 @@ public abstract class CipherSpi {
* <p>If the {@code output} buffer is too small to hold the result, * <p>If the {@code output} buffer is too small to hold the result,
* a {@code ShortBufferException} is thrown. * a {@code ShortBufferException} is thrown.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code CipherSpi} object
* it was in when previously initialized via a call to * to the state it was in when previously initialized via a call to
* {@code engineInit}. * {@code engineInit}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code engineInit}) more data. * {@code engineInit}) more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code CipherSpi} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* @param input the input buffer * @param input the input buffer
* @param inputOffset the offset in {@code input} where the input * @param inputOffset the offset in {@code input} where the input
@ -645,12 +648,13 @@ public abstract class CipherSpi {
* process the input data provided * process the input data provided
* @throws ShortBufferException if the given output buffer is too small * @throws ShortBufferException if the given output buffer is too small
* to hold the result * to hold the result
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code CipherSpi} object is in
* decryption mode,
* and (un)padding has been requested, but the decrypted data is not * and (un)padding has been requested, but the decrypted data is not
* bounded by the appropriate padding bytes * bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code CipherSpi} object is
* AEAD mode (such as GCM or CCM), and the received authentication tag * decrypting in an AEAD mode (such as GCM or CCM), and the received
* does not match the calculated value * authentication tag does not match the calculated value
*/ */
protected abstract int engineDoFinal(byte[] input, int inputOffset, protected abstract int engineDoFinal(byte[] input, int inputOffset,
int inputLen, byte[] output, int inputLen, byte[] output,
@ -661,8 +665,8 @@ public abstract class CipherSpi {
/** /**
* Encrypts or decrypts data in a single-part operation, * Encrypts or decrypts data in a single-part operation,
* or finishes a multiple-part operation. * or finishes a multiple-part operation.
* The data is encrypted or decrypted, depending on how this cipher was * The data is encrypted or decrypted, depending on how this
* initialized. * {@code CipherSpi} object was initialized.
* *
* <p>All {@code input.remaining()} bytes starting at * <p>All {@code input.remaining()} bytes starting at
* {@code input.position()} are processed. * {@code input.position()} are processed.
@ -678,15 +682,15 @@ public abstract class CipherSpi {
* <p>If {@code output.remaining()} bytes are insufficient to * <p>If {@code output.remaining()} bytes are insufficient to
* hold the result, a {@code ShortBufferException} is thrown. * hold the result, a {@code ShortBufferException} is thrown.
* *
* <p>Upon finishing, this method resets this cipher to the state * <p>Upon finishing, this method resets this {@code CipherSpi} object
* it was in when previously initialized via a call to * to the state it was in when previously initialized via a call to
* {@code engineInit}. * {@code engineInit}.
* That is, the object is reset and available to encrypt or decrypt * That is, the object is reset and available to encrypt or decrypt
* (depending on the operation mode that was specified in the call to * (depending on the operation mode that was specified in the call to
* {@code engineInit} more data. * {@code engineInit} more data.
* *
* <p>Note: if any exception is thrown, this cipher may need to * <p>Note: if any exception is thrown, this {@code CipherSpi} object
* be reset before it can be used again. * may need to be reset before it can be used again.
* *
* <p>Subclasses should consider overriding this method if they can * <p>Subclasses should consider overriding this method if they can
* process ByteBuffers more efficiently than byte arrays. * process ByteBuffers more efficiently than byte arrays.
@ -703,12 +707,12 @@ public abstract class CipherSpi {
* process the input data provided * process the input data provided
* @throws ShortBufferException if there is insufficient space in the * @throws ShortBufferException if there is insufficient space in the
* output buffer * output buffer
* @throws BadPaddingException if this cipher is in decryption mode, * @throws BadPaddingException if this {@code CipherSpi} object is in
* and (un)padding has been requested, but the decrypted data is not * decryption mode, and (un)padding has been requested, but the decrypted
* bounded by the appropriate padding bytes * data is not bounded by the appropriate padding bytes
* @throws AEADBadTagException if this cipher is decrypting in an * @throws AEADBadTagException if this {@code CipherSpi} object is
* AEAD mode (such as GCM or CCM), and the received authentication tag * decrypting in an AEAD mode (such as GCM or CCM), and the received
* does not match the calculated value * authentication tag does not match the calculated value
* *
* @throws NullPointerException if either parameter is {@code null} * @throws NullPointerException if either parameter is {@code null}
* @since 1.5 * @since 1.5
@ -935,10 +939,10 @@ public abstract class CipherSpi {
* @param offset the offset in {@code src} where the AAD input starts * @param offset the offset in {@code src} where the AAD input starts
* @param len the number of AAD bytes * @param len the number of AAD bytes
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code CipherSpi} object is in
* (e.g., has not been initialized), does not accept AAD, or if * a wrong state (e.g., has not been initialized), does not accept AAD,
* operating in either GCM or CCM mode and one of the {@code update} * or if operating in either GCM or CCM mode and one of the
* methods has already been called for the active * {@code update} methods has already been called for the active
* encryption/decryption operation * encryption/decryption operation
* @throws UnsupportedOperationException if this method * @throws UnsupportedOperationException if this method
* has not been overridden by an implementation * has not been overridden by an implementation
@ -968,10 +972,10 @@ public abstract class CipherSpi {
* *
* @param src the buffer containing the AAD * @param src the buffer containing the AAD
* *
* @throws IllegalStateException if this cipher is in a wrong state * @throws IllegalStateException if this {@code CipherSpi} object is in
* (e.g., has not been initialized), does not accept AAD, or if * a wrong state (e.g., has not been initialized), does not accept AAD,
* operating in either GCM or CCM mode and one of the {@code update} * or if operating in either GCM or CCM mode and one of the
* methods has already been called for the active * {@code update} methods has already been called for the active
* encryption/decryption operation * encryption/decryption operation
* @throws UnsupportedOperationException if this method * @throws UnsupportedOperationException if this method
* has not been overridden by an implementation * has not been overridden by an implementation

46
src/java.base/share/classes/javax/crypto/CryptoAllPermission.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -60,20 +60,21 @@ final class CryptoAllPermission extends CryptoPermission {
* *
* @param p the permission to check against. * @param p the permission to check against.
* *
* @return true if the specified permission is an * @return {@code true} if the specified permission is an
* instance of CryptoPermission. * instance of {@code CryptoPermission}.
*/ */
public boolean implies(Permission p) { public boolean implies(Permission p) {
return (p instanceof CryptoPermission); return (p instanceof CryptoPermission);
} }
/** /**
* Checks two CryptoAllPermission objects for equality. * Checks two {@code CryptoAllPermission} objects for equality.
* Two CryptoAllPermission objects are always equal. * Two {@code CryptoAllPermission} objects are always equal.
* *
* @param obj the object to test for equality with this object. * @param obj the object to test for equality with this object.
* *
* @return true if <i>obj</i> is a CryptoAllPermission object. * @return {@code true} if <i>obj</i> is a
* {@code CryptoAllPermission} object.
*/ */
public boolean equals(Object obj) { public boolean equals(Object obj) {
return (obj == INSTANCE); return (obj == INSTANCE);
@ -90,12 +91,11 @@ final class CryptoAllPermission extends CryptoPermission {
} }
/** /**
* Returns a new PermissionCollection object for storing * Returns a new {@code PermissionCollection} object for storing
* CryptoAllPermission objects. * {@code CryptoAllPermission} objects.
* <p>
* *
* @return a new PermissionCollection object suitable for * @return a new {@code PermissionCollection} object suitable for
* storing CryptoAllPermissions. * storing {@code CryptoAllPermission} objects.
*/ */
public PermissionCollection newPermissionCollection() { public PermissionCollection newPermissionCollection() {
return new CryptoAllPermissionCollection(); return new CryptoAllPermissionCollection();
@ -103,8 +103,8 @@ final class CryptoAllPermission extends CryptoPermission {
} }
/** /**
* A CryptoAllPermissionCollection stores a collection * A {@code CryptoAllPermissionCollection} stores a collection
* of CryptoAllPermission permissions. * of {@code CryptoAllPermission} objects.
* *
* @see java.security.Permission * @see java.security.Permission
* @see java.security.Permissions * @see java.security.Permissions
@ -123,18 +123,18 @@ final class CryptoAllPermissionCollection extends PermissionCollection
private boolean all_allowed; private boolean all_allowed;
/** /**
* Create an empty CryptoAllPermissions object. * Create an empty {@code CryptoAllPermission} object.
*/ */
CryptoAllPermissionCollection() { CryptoAllPermissionCollection() {
all_allowed = false; all_allowed = false;
} }
/** /**
* Adds a permission to the CryptoAllPermissions. * Adds a permission to {@code CryptoAllPermission} object.
* *
* @param permission the Permission object to add. * @param permission the {@code Permission} object to add.
* *
* @exception SecurityException - if this CryptoAllPermissionCollection * @exception SecurityException if this {@code CryptoAllPermissionCollection}
* object has been marked readonly * object has been marked readonly
*/ */
public void add(Permission permission) { public void add(Permission permission) {
@ -152,10 +152,10 @@ final class CryptoAllPermissionCollection extends PermissionCollection
* Check and see if this set of permissions implies the permissions * Check and see if this set of permissions implies the permissions
* expressed in "permission". * expressed in "permission".
* *
* @param permission the Permission object to compare * @param permission the {@code Permission} object to compare
* *
* @return true if the given permission is implied by this * @return {@code true} if the given permission is implied by this
* CryptoAllPermissionCollection. * {@code CryptoAllPermissionCollection} object.
*/ */
public boolean implies(Permission permission) { public boolean implies(Permission permission) {
if (!(permission instanceof CryptoPermission)) { if (!(permission instanceof CryptoPermission)) {
@ -165,10 +165,10 @@ final class CryptoAllPermissionCollection extends PermissionCollection
} }
/** /**
* Returns an enumeration of all the CryptoAllPermission * Returns an enumeration of all the {@code CryptoAllPermission}
* objects in the container. * objects in the container.
* *
* @return an enumeration of all the CryptoAllPermission objects. * @return an enumeration of all {@code CryptoAllPermission} objects.
*/ */
public Enumeration<Permission> elements() { public Enumeration<Permission> elements() {
Vector<Permission> v = new Vector<>(1); Vector<Permission> v = new Vector<>(1);

100
src/java.base/share/classes/javax/crypto/CryptoPermission.java
View file

@ -35,9 +35,9 @@ import java.util.Vector;
import javax.crypto.spec.*; import javax.crypto.spec.*;
/** /**
* The CryptoPermission class extends the * The {@code CryptoPermission} class extends the
* java.security.Permission class. A * {@code java.security.Permission} class. A
* CryptoPermission object is used to represent * {@code CryptoPermission} object is used to represent
* the ability of an application/applet to use certain * the ability of an application/applet to use certain
* algorithms with certain key sizes and other * algorithms with certain key sizes and other
* restrictions in certain environments. * restrictions in certain environments.
@ -80,7 +80,7 @@ class CryptoPermission extends java.security.Permission {
* key size. * key size.
* *
* This constructor implies that the given algorithm can be * This constructor implies that the given algorithm can be
* used with a key size up to <code>maxKeySize</code>. * used with a key size up to {@code maxKeySize}.
* *
* @param alg the algorithm name. * @param alg the algorithm name.
* *
@ -95,12 +95,12 @@ class CryptoPermission extends java.security.Permission {
/** /**
* Constructor that takes an algorithm name, a maximum * Constructor that takes an algorithm name, a maximum
* key size, and an AlgorithmParameterSpec object. * key size, and an {@code AlgorithmParameterSpec} object.
* *
* This constructor implies that the given algorithm can be * This constructor implies that the given algorithm can be
* used with a key size up to <code>maxKeySize</code>, and * used with a key size up to {@code maxKeySize}, and
* algorithm * algorithm
* parameters up to the limits set in <code>algParamSpec</code>. * parameters up to the limits set in {@code algParamSpec}.
* *
* @param alg the algorithm name. * @param alg the algorithm name.
* *
@ -144,7 +144,7 @@ class CryptoPermission extends java.security.Permission {
* size, and the name of an exemption mechanism. * size, and the name of an exemption mechanism.
* *
* This constructor implies that the given algorithm can be * This constructor implies that the given algorithm can be
* used with a key size up to <code>maxKeySize</code> * used with a key size up to {@code maxKeySize}
* provided that the * provided that the
* specified exemption mechanism is enforced. * specified exemption mechanism is enforced.
* *
@ -166,12 +166,12 @@ class CryptoPermission extends java.security.Permission {
/** /**
* Constructor that takes an algorithm name, a maximum key * Constructor that takes an algorithm name, a maximum key
* size, the name of an exemption mechanism, and an * size, the name of an exemption mechanism, and an
* AlgorithmParameterSpec object. * {@code AlgorithmParameterSpec} object.
* *
* This constructor implies that the given algorithm can be * This constructor implies that the given algorithm can be
* used with a key size up to <code>maxKeySize</code> * used with a key size up to {@code maxKeySize}
* and algorithm * and algorithm
* parameters up to the limits set in <code>algParamSpec</code> * parameters up to the limits set in {@code algParamSpec}
* provided that * provided that
* the specified exemption mechanism is enforced. * the specified exemption mechanism is enforced.
* *
@ -199,9 +199,9 @@ class CryptoPermission extends java.security.Permission {
* Checks if the specified permission is "implied" by * Checks if the specified permission is "implied" by
* this object. * this object.
* <p> * <p>
* More specifically, this method returns true if: * More specifically, this method returns {@code true} if:
* <ul> * <ul>
* <li> <i>p</i> is an instance of CryptoPermission, and</li> * <li> <i>p</i> is an instance of {@code CryptoPermission}, and</li>
* <li> <i>p</i>'s algorithm name equals or (in the case of wildcards) * <li> <i>p</i>'s algorithm name equals or (in the case of wildcards)
* is implied by this permission's algorithm name, and</li> * is implied by this permission's algorithm name, and</li>
* <li> <i>p</i>'s maximum allowable key size is less or * <li> <i>p</i>'s maximum allowable key size is less or
@ -210,14 +210,14 @@ class CryptoPermission extends java.security.Permission {
* implied by this permission's algorithm parameter spec, and</li> * implied by this permission's algorithm parameter spec, and</li>
* <li> <i>p</i>'s exemptionMechanism equals or * <li> <i>p</i>'s exemptionMechanism equals or
* is implied by this permission's * is implied by this permission's
* exemptionMechanism (a <code>null</code> exemption mechanism * exemptionMechanism (a {@code null} exemption mechanism
* implies any other exemption mechanism).</li> * implies any other exemption mechanism).</li>
* </ul> * </ul>
* *
* @param p the permission to check against. * @param p the permission to check against.
* *
* @return true if the specified permission is equal to or * @return {@code true} if the specified permission is equal to or
* implied by this permission, false otherwise. * implied by this permission, {@code false} otherwise.
*/ */
public boolean implies(Permission p) { public boolean implies(Permission p) {
if (!(p instanceof CryptoPermission cp)) if (!(p instanceof CryptoPermission cp))
@ -244,15 +244,13 @@ class CryptoPermission extends java.security.Permission {
} }
/** /**
* Checks two CryptoPermission objects for equality. Checks that * Checks two {@code CryptoPermission} objects for equality.
* <code>obj</code> is a CryptoPermission, and has the same * Checks that {@code obj} is a {@code CryptoPermission}
* algorithm name, * object, and has the same algorithm name,
* exemption mechanism name, maximum allowable key size and * exemption mechanism name, maximum allowable key size and
* algorithm parameter spec * algorithm parameter spec as this object.
* as this object.
* <P>
* @param obj the object to test for equality with this object. * @param obj the object to test for equality with this object.
* @return true if <code>obj</code> is equal to this object. * @return {@code true} if {@code obj} is equal to this object.
*/ */
public boolean equals(Object obj) { public boolean equals(Object obj) {
if (obj == this) if (obj == this)
@ -294,7 +292,7 @@ class CryptoPermission extends java.security.Permission {
} }
/** /**
* There is no action defined for a CryptoPermission * There is no action defined for a {@code CryptoPermission}
* object. * object.
*/ */
public String getActions() public String getActions()
@ -303,10 +301,10 @@ class CryptoPermission extends java.security.Permission {
} }
/** /**
* Returns a new PermissionCollection object for storing * Returns a new {@code PermissionCollection} object for storing
* CryptoPermission objects. * {@code CryptoPermission} objects.
* *
* @return a new PermissionCollection object suitable for storing * @return a new {@code PermissionCollection} object suitable for storing
* CryptoPermissions. * CryptoPermissions.
*/ */
@ -316,7 +314,7 @@ class CryptoPermission extends java.security.Permission {
/** /**
* Returns the algorithm name associated with * Returns the algorithm name associated with
* this CryptoPermission object. * this {@code CryptoPermission} object.
*/ */
final String getAlgorithm() { final String getAlgorithm() {
return alg; return alg;
@ -324,7 +322,7 @@ class CryptoPermission extends java.security.Permission {
/** /**
* Returns the exemption mechanism name * Returns the exemption mechanism name
* associated with this CryptoPermission * associated with this {@code CryptoPermission}
* object. * object.
*/ */
final String getExemptionMechanism() { final String getExemptionMechanism() {
@ -333,16 +331,16 @@ class CryptoPermission extends java.security.Permission {
/** /**
* Returns the maximum allowable key size associated * Returns the maximum allowable key size associated
* with this CryptoPermission object. * with this {@code CryptoPermission} object.
*/ */
final int getMaxKeySize() { final int getMaxKeySize() {
return maxKeySize; return maxKeySize;
} }
/** /**
* Returns true if there is a limitation on the * Returns {@code true} if there is a limitation on the
* AlgorithmParameterSpec associated with this * {@code AlgorithmParameterSpec} associated with this
* CryptoPermission object and false if otherwise. * {@code CryptoPermission} object and {@code false} if otherwise.
*/ */
final boolean getCheckParam() { final boolean getCheckParam() {
return checkParam; return checkParam;
@ -358,12 +356,13 @@ class CryptoPermission extends java.security.Permission {
} }
/** /**
* Returns a string describing this CryptoPermission. The convention is to * Returns a string describing this {@code CryptoPermission} object.
* specify the class name, the algorithm name, the maximum allowable * The convention is to specify the class name, the algorithm name,
* key size, and the name of the exemption mechanism, in the following * the maximum allowable key size, and the name of the exemption mechanism,
* in the following
* format: '("ClassName" "algorithm" "keysize" "exemption_mechanism")'. * format: '("ClassName" "algorithm" "keysize" "exemption_mechanism")'.
* *
* @return information about this CryptoPermission. * @return information about this {@code CryptoPermission} object.
*/ */
public String toString() { public String toString() {
StringBuilder buf = new StringBuilder(100); StringBuilder buf = new StringBuilder(100);
@ -449,8 +448,8 @@ class CryptoPermission extends java.security.Permission {
} }
/** /**
* A CryptoPermissionCollection stores a set of CryptoPermission * A {@code CryptoPermissionCollection} object stores a set of
* permissions. * {@code CryptoPermission} objects.
* *
* @see java.security.Permission * @see java.security.Permission
* @see java.security.Permissions * @see java.security.Permissions
@ -475,12 +474,13 @@ final class CryptoPermissionCollection extends PermissionCollection
} }
/** /**
* Adds a permission to the CryptoPermissionCollection. * Adds a permission to the {@code CryptoPermissionCollection} object.
* *
* @param permission the Permission object to add. * @param permission the {@code Permission} object to add.
* *
* @exception SecurityException - if this CryptoPermissionCollection * @exception SecurityException if this
* object has been marked <i>readOnly</i>. * {@code CryptoPermissionCollection} object has been marked
* <i>readOnly</i>.
*/ */
public void add(Permission permission) { public void add(Permission permission) {
if (isReadOnly()) if (isReadOnly())
@ -494,13 +494,13 @@ final class CryptoPermissionCollection extends PermissionCollection
} }
/** /**
* Check and see if this CryptoPermission object implies * Check and see if this {@code CryptoPermission} object implies
* the given Permission object. * the given {@code Permission} object.
* *
* @param permission the Permission object to compare * @param permission the {@code Permission} object to compare
* *
* @return true if the given permission is implied by this * @return {@code true} if the given permission is implied by this
* CryptoPermissionCollection, false if not. * {@code CryptoPermissionCollection}, {@code false} if not.
*/ */
public boolean implies(Permission permission) { public boolean implies(Permission permission) {
if (!(permission instanceof CryptoPermission cp)) if (!(permission instanceof CryptoPermission cp))
@ -518,10 +518,10 @@ final class CryptoPermissionCollection extends PermissionCollection
} }
/** /**
* Returns an enumeration of all the CryptoPermission objects * Returns an enumeration of all the {@code CryptoPermission} objects
* in the container. * in the container.
* *
* @return an enumeration of all the CryptoPermission objects. * @return an enumeration of all the {@code CryptoPermission} objects.
*/ */
public Enumeration<Permission> elements() { public Enumeration<Permission> elements() {

114
src/java.base/share/classes/javax/crypto/CryptoPermissions.java
View file

@ -43,17 +43,17 @@ import java.io.IOException;
import static java.nio.charset.StandardCharsets.UTF_8; import static java.nio.charset.StandardCharsets.UTF_8;
/** /**
* This class contains CryptoPermission objects, organized into * This class contains {@code CryptoPermission} objects, organized into
* PermissionCollections according to algorithm names. * {@code PermissionCollection} objects according to algorithm names.
* *
* <p>When the <code>add</code> method is called to add a * <p>When the {@code add} method is called to add a
* CryptoPermission, the CryptoPermission is stored in the * {@code CryptoPermission}, the {@code CryptoPermission} is stored in the
* appropriate PermissionCollection. If no such * appropriate {@code PermissionCollection}. If no such
* collection exists yet, the algorithm name associated with * collection exists yet, the algorithm name associated with
* the CryptoPermission object is * the {@code CryptoPermission} object is
* determined and the <code>newPermissionCollection</code> method * determined and the {@code newPermissionCollection} method
* is called on the CryptoPermission or CryptoAllPermission class to * is called on the {@code CryptoPermission} or {@code CryptoAllPermission} class to
* create the PermissionCollection and add it to the Permissions object. * create the {@code PermissionCollection} and add it to the {@code Permissions} object.
* *
* @see javax.crypto.CryptoPermission * @see javax.crypto.CryptoPermission
* @see java.security.PermissionCollection * @see java.security.PermissionCollection
@ -82,8 +82,8 @@ implements Serializable {
private transient ConcurrentHashMap<String,PermissionCollection> perms; private transient ConcurrentHashMap<String,PermissionCollection> perms;
/** /**
* Creates a new CryptoPermissions object containing * Creates a new {@code CryptoPermissions} object containing
* no CryptoPermissionCollections. * no {@code CryptoPermissionCollection} objects.
*/ */
CryptoPermissions() { CryptoPermissions() {
perms = new ConcurrentHashMap<>(7); perms = new ConcurrentHashMap<>(7);
@ -91,7 +91,7 @@ implements Serializable {
/** /**
* Populates the crypto policy from the specified * Populates the crypto policy from the specified
* InputStream into this CryptoPermissions object. * {@code InputStream} into this {@code CryptoPermissions} object.
* *
* @param in the InputStream to load from. * @param in the InputStream to load from.
* *
@ -110,29 +110,29 @@ implements Serializable {
} }
/** /**
* Returns true if this CryptoPermissions object doesn't * Returns {@code true} if this {@code CryptoPermissions} object doesn't
* contain any CryptoPermission objects; otherwise, returns * contain any {@code CryptoPermission} objects; otherwise, returns
* false. * {@code false}.
*/ */
boolean isEmpty() { boolean isEmpty() {
return perms.isEmpty(); return perms.isEmpty();
} }
/** /**
* Adds a permission object to the PermissionCollection for the * Adds a permission object to the
* algorithm returned by * {@code PermissionCollection} for the algorithm returned by
* <code>(CryptoPermission)permission.getAlgorithm()</code>. * {@code (CryptoPermission)permission.getAlgorithm()}.
* *
* This method creates * This method creates
* a new PermissionCollection object (and adds the permission to it) * a new {@code PermissionCollection} object (and adds the
* if an appropriate collection does not yet exist. <p> * permission to it) if an appropriate collection does not yet exist.
* *
* @param permission the Permission object to add. * @param permission the {@code Permission} object to add.
* *
* @exception SecurityException if this CryptoPermissions object is * @exception SecurityException if this {@code CryptoPermissions}
* marked as readonly. * object is marked as readonly.
* *
* @see isReadOnly * @see PermissionCollection#isReadOnly
*/ */
@Override @Override
public void add(Permission permission) { public void add(Permission permission) {
@ -155,14 +155,14 @@ implements Serializable {
} }
/** /**
* Checks if this object's PermissionCollection for permissions * Checks if this object's {@code PermissionCollection} for permissions
* of the specified permission's algorithm implies the specified * of the specified permission's algorithm implies the specified
* permission. Returns true if the checking succeeded. * permission. Returns {@code true} if the checking succeeded.
* *
* @param permission the Permission object to check. * @param permission the {@code Permission} object to check.
* *
* @return true if "permission" is implied by the permissions * @return {@code true} if {@code permission} is implied by the permissions
* in the PermissionCollection it belongs to, false if not. * in the {@code PermissionCollection} it belongs to, {@code false} if not.
* *
*/ */
@Override @Override
@ -183,10 +183,9 @@ implements Serializable {
} }
/** /**
* Returns an enumeration of all the Permission objects in all the * Returns an enumeration of all the {@code Permission} objects
* PermissionCollections in this CryptoPermissions object. * in this {@code CryptoPermissions} object.
* * @return an enumeration of all the {@code Permission} objects.
* @return an enumeration of all the Permissions.
*/ */
@Override @Override
public Enumeration<Permission> elements() { public Enumeration<Permission> elements() {
@ -196,12 +195,12 @@ implements Serializable {
} }
/** /**
* Returns a CryptoPermissions object which * Returns a {@code CryptoPermissions} object which
* represents the minimum of the specified * represents the minimum of the specified
* CryptoPermissions object and this * {@code CryptoPermissions} object and this
* CryptoPermissions object. * {@code CryptoPermissions} object.
* *
* @param other the CryptoPermission * @param other the {@code CryptoPermission}
* object to compare with this object. * object to compare with this object.
*/ */
CryptoPermissions getMinimum(CryptoPermissions other) { CryptoPermissions getMinimum(CryptoPermissions other) {
@ -293,13 +292,13 @@ implements Serializable {
} }
/** /**
* Get the minimum of the two given PermissionCollection * Get the minimum of the two given {@code PermissionCollection}
* <code>thisPc</code> and <code>thatPc</code>. * {@code thisPc} and {@code thatPc}.
* *
* @param thisPc the first given PermissionCollection * @param thisPc the first given {@code PermissionCollection}
* object. * object.
* *
* @param thatPc the second given PermissionCollection * @param thatPc the second given {@code PermissionCollection}
* object. * object.
*/ */
private CryptoPermission[] getMinimum(PermissionCollection thisPc, private CryptoPermission[] getMinimum(PermissionCollection thisPc,
@ -344,17 +343,18 @@ implements Serializable {
} }
/** /**
* Returns all the CryptoPermission objects in the given * Returns all the {@code CryptoPermission} objects in the given
* PermissionCollection object * {@code PermissionCollection} object
* whose maximum keysize no greater than <code>maxKeySize</code>. * whose maximum keysize no greater than {@code maxKeySize}.
* For all CryptoPermission objects with a maximum keysize greater * For all {@code CryptoPermission} objects with a maximum keysize
* than <code>maxKeySize</code>, this method constructs a * greater than {@code maxKeySize}, this method constructs a
* corresponding CryptoPermission object whose maximum keysize is * corresponding {@code CryptoPermission} object whose maximum
* set to <code>maxKeySize</code>, and includes that in the result. * keysize is set to {@code maxKeySize}, and includes that in
* the result.
* *
* @param maxKeySize the given maximum key size. * @param maxKeySize the given maximum key size.
* *
* @param pc the given PermissionCollection object. * @param pc the given {@code PermissionCollection} object.
*/ */
private CryptoPermission[] getMinimum(int maxKeySize, private CryptoPermission[] getMinimum(int maxKeySize,
PermissionCollection pc) { PermissionCollection pc) {
@ -387,9 +387,9 @@ implements Serializable {
} }
/** /**
* Returns the PermissionCollection for the * Returns the {@code PermissionCollection} for the
* specified algorithm. Returns null if there * specified algorithm. Returns {@code null} if there
* isn't such a PermissionCollection. * isn't such a {@code PermissionCollection}.
* *
* @param alg the algorithm name. * @param alg the algorithm name.
*/ */
@ -412,13 +412,13 @@ implements Serializable {
} }
/** /**
* Returns the PermissionCollection for the algorithm * Returns the {@code PermissionCollection} for the algorithm
* associated with the specified CryptoPermission * associated with the specified {@code CryptoPermission}
* object. Creates such a PermissionCollection * object. Creates such a {@code PermissionCollection}
* if such a PermissionCollection does not * if such a {@code PermissionCollection} does not
* exist yet. * exist yet.
* *
* @param cryptoPerm the CryptoPermission object. * @param cryptoPerm the {@code CryptoPermission} object.
*/ */
private PermissionCollection getPermissionCollection( private PermissionCollection getPermissionCollection(
CryptoPermission cryptoPerm) { CryptoPermission cryptoPerm) {

21
src/java.base/share/classes/javax/crypto/CryptoPolicyParser.java
View file

@ -42,8 +42,9 @@ import java.lang.reflect.*;
* JCE will be used. * JCE will be used.
* *
* The jurisdiction policy file has the same syntax as JDK policy files except * The jurisdiction policy file has the same syntax as JDK policy files except
* that JCE has new permission classes called javax.crypto.CryptoPermission * that JCE has new permission classes called
* and javax.crypto.CryptoAllPermission. * {@code javax.crypto.CryptoPermission} and
* {@code javax.crypto.CryptoAllPermission}.
* *
* The format of a permission entry in the jurisdiction policy file is: * The format of a permission entry in the jurisdiction policy file is:
* *
@ -74,16 +75,16 @@ final class CryptoPolicyParser {
private boolean allPermEntryFound = false; private boolean allPermEntryFound = false;
/** /**
* Creates a CryptoPolicyParser object. * Creates a {@code CryptoPolicyParser} object.
*/ */
CryptoPolicyParser() { CryptoPolicyParser() {
grantEntries = new Vector<>(); grantEntries = new Vector<>();
} }
/** /**
* Reads a policy configuration using a Reader object. <p> * Reads a policy configuration using a {@code Reader} object. <p>
* *
* @param policy the policy Reader object. * @param policy the policy {@code Reader} object.
* *
* @exception ParsingException if the policy configuration * @exception ParsingException if the policy configuration
* contains a syntax error. * contains a syntax error.
@ -537,8 +538,8 @@ final class CryptoPolicyParser {
} }
/** /**
* Each grant entry in the policy configuration file is represented by a * Each grant entry in the policy configuration file is represented by a
* GrantEntry object. * {@code GrantEntry} object.
* <p> * <p>
* For example, the entry * For example, the entry
* <pre> * <pre>
@ -588,7 +589,7 @@ final class CryptoPolicyParser {
} }
/** /**
* Enumerate all the permission entries in this GrantEntry. * Enumerate all the permission entries in this {@code GrantEntry}.
*/ */
Enumeration<CryptoPermissionEntry> permissionElements(){ Enumeration<CryptoPermissionEntry> permissionElements(){
return permissionEntries.elements(); return permissionEntries.elements();
@ -598,7 +599,7 @@ final class CryptoPolicyParser {
/** /**
* Each crypto permission entry in the policy configuration file is * Each crypto permission entry in the policy configuration file is
* represented by a CryptoPermissionEntry object. * represented by a {@code CryptoPermissionEntry} object.
* <p> * <p>
* For example, the entry * For example, the entry
* <pre> * <pre>
@ -692,7 +693,7 @@ final class CryptoPolicyParser {
private static final long serialVersionUID = 7147241245566588374L; private static final long serialVersionUID = 7147241245566588374L;
/** /**
* Constructs a ParsingException with the specified * Constructs a {@code ParsingException} with the specified
* detail message. * detail message.
* @param msg the detail message. * @param msg the detail message.
*/ */

75
src/java.base/share/classes/javax/crypto/EncryptedPrivateKeyInfo.java
View file

@ -34,7 +34,7 @@ import sun.security.util.DerInputStream;
import sun.security.util.DerOutputStream; import sun.security.util.DerOutputStream;
/** /**
* This class implements the <code>EncryptedPrivateKeyInfo</code> type * This class implements the {@code EncryptedPrivateKeyInfo} type
* as defined in PKCS #8. * as defined in PKCS #8.
* <p>Its ASN.1 definition is as follows: * <p>Its ASN.1 definition is as follows:
* *
@ -70,11 +70,12 @@ public class EncryptedPrivateKeyInfo {
private byte[] encoded; private byte[] encoded;
/** /**
* Constructs (i.e., parses) an <code>EncryptedPrivateKeyInfo</code> from * Constructs (i.e., parses) an {@code EncryptedPrivateKeyInfo} from
* its ASN.1 encoding. * its ASN.1 encoding.
* @param encoded the ASN.1 encoding of this object. The contents of * @param encoded the ASN.1 encoding of this object. The contents of
* the array are copied to protect against subsequent modification. * the array are copied to protect against subsequent modification.
* @exception NullPointerException if the <code>encoded</code> is null. * @exception NullPointerException if the {@code encoded} is
* {@code null}.
* @exception IOException if error occurs when parsing the ASN.1 encoding. * @exception IOException if error occurs when parsing the ASN.1 encoding.
*/ */
public EncryptedPrivateKeyInfo(byte[] encoded) throws IOException { public EncryptedPrivateKeyInfo(byte[] encoded) throws IOException {
@ -110,12 +111,12 @@ public class EncryptedPrivateKeyInfo {
} }
/** /**
* Constructs an <code>EncryptedPrivateKeyInfo</code> from the * Constructs an {@code EncryptedPrivateKeyInfo} from the
* encryption algorithm name and the encrypted data. * encryption algorithm name and the encrypted data.
* *
* <p>Note: This constructor will use null as the value of the * <p>Note: This constructor will use {@code null} as the value of the
* algorithm parameters. If the encryption algorithm has * algorithm parameters. If the encryption algorithm has
* parameters whose value is not null, a different constructor, * parameters whose value is not {@code null}, a different constructor,
* e.g. EncryptedPrivateKeyInfo(AlgorithmParameters, byte[]), * e.g. EncryptedPrivateKeyInfo(AlgorithmParameters, byte[]),
* should be used. * should be used.
* *
@ -124,11 +125,11 @@ public class EncryptedPrivateKeyInfo {
* Java Security Standard Algorithm Names</a> document * Java Security Standard Algorithm Names</a> document
* for information about standard Cipher algorithm names. * for information about standard Cipher algorithm names.
* @param encryptedData encrypted data. The contents of * @param encryptedData encrypted data. The contents of
* <code>encryptedData</code> are copied to protect against subsequent * {@code encryptedData} are copied to protect against subsequent
* modification when constructing this object. * modification when constructing this object.
* @exception NullPointerException if <code>algName</code> or * @exception NullPointerException if {@code algName} or
* <code>encryptedData</code> is null. * {@code encryptedData} is {@code null}.
* @exception IllegalArgumentException if <code>encryptedData</code> * @exception IllegalArgumentException if {@code encryptedData}
* is empty, i.e. 0-length. * is empty, i.e. 0-length.
* @exception NoSuchAlgorithmException if the specified algName is * @exception NoSuchAlgorithmException if the specified algName is
* not supported. * not supported.
@ -156,23 +157,23 @@ public class EncryptedPrivateKeyInfo {
} }
/** /**
* Constructs an <code>EncryptedPrivateKeyInfo</code> from the * Constructs an {@code EncryptedPrivateKeyInfo} from the
* encryption algorithm parameters and the encrypted data. * encryption algorithm parameters and the encrypted data.
* *
* @param algParams the algorithm parameters for the encryption * @param algParams the algorithm parameters for the encryption
* algorithm. <code>algParams.getEncoded()</code> should return * algorithm. {@code algParams.getEncoded()} should return
* the ASN.1 encoded bytes of the <code>parameters</code> field * the ASN.1 encoded bytes of the {@code parameters} field
* of the <code>AlgorithmIdentifier</code> component of the * of the {@code AlgorithmIdentifier} component of the
* <code>EncryptedPrivateKeyInfo</code> type. * {@code EncryptedPrivateKeyInfo} type.
* @param encryptedData encrypted data. The contents of * @param encryptedData encrypted data. The contents of
* <code>encryptedData</code> are copied to protect against * {@code encryptedData} are copied to protect against
* subsequent modification when constructing this object. * subsequent modification when constructing this object.
* @exception NullPointerException if <code>algParams</code> or * @exception NullPointerException if {@code algParams} or
* <code>encryptedData</code> is null. * {@code encryptedData} is {@code null}.
* @exception IllegalArgumentException if <code>encryptedData</code> * @exception IllegalArgumentException if {@code encryptedData}
* is empty, i.e. 0-length. * is empty, i.e. 0-length.
* @exception NoSuchAlgorithmException if the specified algName of * @exception NoSuchAlgorithmException if the specified algName of
* the specified <code>algParams</code> parameter is not supported. * the specified {@code algParams} parameter is not supported.
*/ */
public EncryptedPrivateKeyInfo(AlgorithmParameters algParams, public EncryptedPrivateKeyInfo(AlgorithmParameters algParams,
byte[] encryptedData) throws NoSuchAlgorithmException { byte[] encryptedData) throws NoSuchAlgorithmException {
@ -232,16 +233,16 @@ public class EncryptedPrivateKeyInfo {
* Extract the enclosed PKCS8EncodedKeySpec object from the * Extract the enclosed PKCS8EncodedKeySpec object from the
* encrypted data and return it. * encrypted data and return it.
* <br>Note: In order to successfully retrieve the enclosed * <br>Note: In order to successfully retrieve the enclosed
* PKCS8EncodedKeySpec object, <code>cipher</code> needs * PKCS8EncodedKeySpec object, {@code cipher} needs
* to be initialized to either Cipher.DECRYPT_MODE or * to be initialized to either Cipher.DECRYPT_MODE or
* Cipher.UNWRAP_MODE, with the same key and parameters used * Cipher.UNWRAP_MODE, with the same key and parameters used
* for generating the encrypted data. * for generating the encrypted data.
* *
* @param cipher the initialized cipher object which will be * @param cipher the initialized {@code Cipher} object which will be
* used for decrypting the encrypted data. * used for decrypting the encrypted data.
* @return the PKCS8EncodedKeySpec object. * @return the PKCS8EncodedKeySpec object.
* @exception NullPointerException if <code>cipher</code> * @exception NullPointerException if {@code cipher}
* is null. * is {@code null}.
* @exception InvalidKeySpecException if the given cipher is * @exception InvalidKeySpecException if the given cipher is
* inappropriate for the encrypted data or the encrypted * inappropriate for the encrypted data or the encrypted
* data is corrupted and cannot be decrypted. * data is corrupted and cannot be decrypted.
@ -291,11 +292,11 @@ public class EncryptedPrivateKeyInfo {
* encrypted data and return it. * encrypted data and return it.
* @param decryptKey key used for decrypting the encrypted data. * @param decryptKey key used for decrypting the encrypted data.
* @return the PKCS8EncodedKeySpec object. * @return the PKCS8EncodedKeySpec object.
* @exception NullPointerException if <code>decryptKey</code> * @exception NullPointerException if {@code decryptKey}
* is null. * is {@code null}.
* @exception NoSuchAlgorithmException if cannot find appropriate * @exception NoSuchAlgorithmException if cannot find appropriate
* cipher to decrypt the encrypted data. * cipher to decrypt the encrypted data.
* @exception InvalidKeyException if <code>decryptKey</code> * @exception InvalidKeyException if {@code decryptKey}
* cannot be used to decrypt the encrypted data or the decryption * cannot be used to decrypt the encrypted data or the decryption
* result is not a valid PKCS8KeySpec. * result is not a valid PKCS8KeySpec.
* *
@ -313,16 +314,16 @@ public class EncryptedPrivateKeyInfo {
* Extract the enclosed PKCS8EncodedKeySpec object from the * Extract the enclosed PKCS8EncodedKeySpec object from the
* encrypted data and return it. * encrypted data and return it.
* @param decryptKey key used for decrypting the encrypted data. * @param decryptKey key used for decrypting the encrypted data.
* @param providerName the name of provider whose Cipher * @param providerName the name of provider whose cipher
* implementation will be used. * implementation will be used.
* @return the PKCS8EncodedKeySpec object. * @return the PKCS8EncodedKeySpec object.
* @exception NullPointerException if <code>decryptKey</code> * @exception NullPointerException if {@code decryptKey}
* or <code>providerName</code> is null. * or {@code providerName} is {@code null}.
* @exception NoSuchProviderException if no provider * @exception NoSuchProviderException if no provider
* <code>providerName</code> is registered. * {@code providerName} is registered.
* @exception NoSuchAlgorithmException if cannot find appropriate * @exception NoSuchAlgorithmException if cannot find appropriate
* cipher to decrypt the encrypted data. * cipher to decrypt the encrypted data.
* @exception InvalidKeyException if <code>decryptKey</code> * @exception InvalidKeyException if {@code decryptKey}
* cannot be used to decrypt the encrypted data or the decryption * cannot be used to decrypt the encrypted data or the decryption
* result is not a valid PKCS8KeySpec. * result is not a valid PKCS8KeySpec.
* *
@ -349,14 +350,14 @@ public class EncryptedPrivateKeyInfo {
* Extract the enclosed PKCS8EncodedKeySpec object from the * Extract the enclosed PKCS8EncodedKeySpec object from the
* encrypted data and return it. * encrypted data and return it.
* @param decryptKey key used for decrypting the encrypted data. * @param decryptKey key used for decrypting the encrypted data.
* @param provider the name of provider whose Cipher implementation * @param provider the name of provider whose cipher implementation
* will be used. * will be used.
* @return the PKCS8EncodedKeySpec object. * @return the PKCS8EncodedKeySpec object.
* @exception NullPointerException if <code>decryptKey</code> * @exception NullPointerException if {@code decryptKey}
* or <code>provider</code> is null. * or {@code provider} is {@code null}.
* @exception NoSuchAlgorithmException if cannot find appropriate * @exception NoSuchAlgorithmException if cannot find appropriate
* cipher to decrypt the encrypted data in <code>provider</code>. * cipher to decrypt the encrypted data in {@code provider}.
* @exception InvalidKeyException if <code>decryptKey</code> * @exception InvalidKeyException if {@code decryptKey}
* cannot be used to decrypt the encrypted data or the decryption * cannot be used to decrypt the encrypted data or the decryption
* result is not a valid PKCS8KeySpec. * result is not a valid PKCS8KeySpec.
* *

82
src/java.base/share/classes/javax/crypto/ExemptionMechanism.java
View file

@ -71,7 +71,7 @@ public class ExemptionMechanism {
private Key keyStored = null; private Key keyStored = null;
/** /**
* Creates a ExemptionMechanism object. * Creates an {@code ExemptionMechanism} object.
* *
* @param exmechSpi the delegate * @param exmechSpi the delegate
* @param provider the provider * @param provider the provider
@ -87,28 +87,28 @@ public class ExemptionMechanism {
/** /**
* Returns the exemption mechanism name of this * Returns the exemption mechanism name of this
* <code>ExemptionMechanism</code> object. * {@code ExemptionMechanism} object.
* *
* <p>This is the same name that was specified in one of the * <p>This is the same name that was specified in one of the
* <code>getInstance</code> calls that created this * {@code getInstance} calls that created this
* <code>ExemptionMechanism</code> object. * {@code ExemptionMechanism} object.
* *
* @return the exemption mechanism name of this * @return the exemption mechanism name of this
* <code>ExemptionMechanism</code> object. * {@code ExemptionMechanism} object.
*/ */
public final String getName() { public final String getName() {
return this.mechanism; return this.mechanism;
} }
/** /**
* Returns an <code>ExemptionMechanism</code> object that implements the * Returns an {@code ExemptionMechanism} object that implements the
* specified exemption mechanism algorithm. * specified exemption mechanism algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new ExemptionMechanism object encapsulating the * A new {@code ExemptionMechanism} object encapsulating the
* ExemptionMechanismSpi implementation from the first * {@code ExemptionMechanismSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -150,12 +150,12 @@ public class ExemptionMechanism {
/** /**
* Returns an <code>ExemptionMechanism</code> object that implements the * Returns an {@code ExemptionMechanism} object that implements the
* specified exemption mechanism algorithm. * specified exemption mechanism algorithm.
* *
* <p> A new ExemptionMechanism object encapsulating the * <p> A new {@code ExemptionMechanism} object encapsulating the
* ExemptionMechanismSpi implementation from the specified provider * {@code ExemptionMechanismSpi} implementation from the specified
* is returned. The specified provider must be registered * provider is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
@ -197,12 +197,12 @@ public class ExemptionMechanism {
} }
/** /**
* Returns an <code>ExemptionMechanism</code> object that implements the * Returns an {@code ExemptionMechanism} object that implements the
* specified exemption mechanism algorithm. * specified exemption mechanism algorithm.
* *
* <p> A new ExemptionMechanism object encapsulating the * <p> A new {@code ExemptionMechanism} object encapsulating the
* ExemptionMechanismSpi implementation from the specified Provider * {@code ExemptionMechanismSpi} implementation from the specified
* object is returned. Note that the specified Provider object * provider object is returned. Note that the specified provider object
* does not have to be registered in the provider list. * does not have to be registered in the provider list.
* *
* @param algorithm the standard name of the requested exemption mechanism. * @param algorithm the standard name of the requested exemption mechanism.
@ -217,11 +217,11 @@ public class ExemptionMechanism {
* @return the new {@code ExemptionMechanism} object * @return the new {@code ExemptionMechanism} object
* *
* @throws IllegalArgumentException if the {@code provider} * @throws IllegalArgumentException if the {@code provider}
* is null * is {@code null}
* *
* @throws NoSuchAlgorithmException if an {@code ExemptionMechanismSpi} * @throws NoSuchAlgorithmException if an {@code ExemptionMechanismSpi}
* implementation for the specified algorithm is not available * implementation for the specified algorithm is not available
* from the specified {@code Provider object} * from the specified {@code Provider} object
* *
* @exception NullPointerException if {@code algorithm} is {@code null} * @exception NullPointerException if {@code algorithm} is {@code null}
* *
@ -237,9 +237,9 @@ public class ExemptionMechanism {
} }
/** /**
* Returns the provider of this <code>ExemptionMechanism</code> object. * Returns the provider of this {@code ExemptionMechanism} object.
* *
* @return the provider of this <code>ExemptionMechanism</code> object. * @return the provider of this {@code ExemptionMechanism} object.
*/ */
public final Provider getProvider() { public final Provider getProvider() {
return this.provider; return this.provider;
@ -256,8 +256,8 @@ public class ExemptionMechanism {
* @param key the key the crypto is going to use. * @param key the key the crypto is going to use.
* *
* @return whether the result blob of the same key has been generated * @return whether the result blob of the same key has been generated
* successfully by this exemption mechanism; false if <code>key</code> * successfully by this exemption mechanism; {@code false} if {@code key}
* is null. * is {@code null}.
* *
* @exception ExemptionMechanismException if problem(s) encountered * @exception ExemptionMechanismException if problem(s) encountered
* while determining whether the result blob has been generated successfully * while determining whether the result blob has been generated successfully
@ -278,7 +278,7 @@ public class ExemptionMechanism {
* Returns the length in bytes that an output buffer would need to be in * Returns the length in bytes that an output buffer would need to be in
* order to hold the result of the next * order to hold the result of the next
* {@link #genExemptionBlob(byte[]) genExemptionBlob} * {@link #genExemptionBlob(byte[]) genExemptionBlob}
* operation, given the input length <code>inputLen</code> (in bytes). * operation, given the input length {@code inputLen} (in bytes).
* *
* <p>The actual output length of the next * <p>The actual output length of the next
* {@link #genExemptionBlob(byte[]) genExemptionBlob} * {@link #genExemptionBlob(byte[]) genExemptionBlob}
@ -307,11 +307,11 @@ public class ExemptionMechanism {
* Initializes this exemption mechanism with a key. * Initializes this exemption mechanism with a key.
* *
* <p>If this exemption mechanism requires any algorithm parameters * <p>If this exemption mechanism requires any algorithm parameters
* that cannot be derived from the given <code>key</code>, the * that cannot be derived from the given {@code key}, the
* underlying exemption mechanism implementation is supposed to * underlying exemption mechanism implementation is supposed to
* generate the required parameters itself (using provider-specific * generate the required parameters itself (using provider-specific
* default values); in the case that algorithm parameters must be * default values); in the case that algorithm parameters must be
* specified by the caller, an <code>InvalidKeyException</code> is raised. * specified by the caller, an {@code InvalidKeyException} is raised.
* *
* @param key the key for this exemption mechanism * @param key the key for this exemption mechanism
* *
@ -335,11 +335,11 @@ public class ExemptionMechanism {
* parameters. * parameters.
* *
* <p>If this exemption mechanism requires any algorithm parameters * <p>If this exemption mechanism requires any algorithm parameters
* and <code>params</code> is null, the underlying exemption * and {@code params} is {@code null}, the underlying exemption
* mechanism implementation is supposed to generate the required * mechanism implementation is supposed to generate the required
* parameters itself (using provider-specific default values); in the case * parameters itself (using provider-specific default values); in the case
* that algorithm parameters must be specified by the caller, an * that algorithm parameters must be specified by the caller, an
* <code>InvalidAlgorithmParameterException</code> is raised. * {@code InvalidAlgorithmParameterException} is raised.
* *
* @param key the key for this exemption mechanism * @param key the key for this exemption mechanism
* @param params the algorithm parameters * @param params the algorithm parameters
@ -367,11 +367,11 @@ public class ExemptionMechanism {
* parameters. * parameters.
* *
* <p>If this exemption mechanism requires any algorithm parameters * <p>If this exemption mechanism requires any algorithm parameters
* and <code>params</code> is null, the underlying exemption mechanism * and {@code params} is {@code null}, the underlying exemption mechanism
* implementation is supposed to generate the required parameters itself * implementation is supposed to generate the required parameters itself
* (using provider-specific default values); in the case that algorithm * (using provider-specific default values); in the case that algorithm
* parameters must be specified by the caller, an * parameters must be specified by the caller, an
* <code>InvalidAlgorithmParameterException</code> is raised. * {@code InvalidAlgorithmParameterException} is raised.
* *
* @param key the key for this exemption mechanism * @param key the key for this exemption mechanism
* @param params the algorithm parameters * @param params the algorithm parameters
@ -417,17 +417,17 @@ public class ExemptionMechanism {
/** /**
* Generates the exemption mechanism key blob, and stores the result in * Generates the exemption mechanism key blob, and stores the result in
* the <code>output</code> buffer. * the {@code output} buffer.
* *
* <p>If the <code>output</code> buffer is too small to hold the result, * <p>If the {@code output} buffer is too small to hold the result,
* a <code>ShortBufferException</code> is thrown. In this case, repeat this * a {@code ShortBufferException} is thrown. In this case, repeat this
* call with a larger output buffer. Use * call with a larger output buffer. Use
* {@link #getOutputSize(int) getOutputSize} to determine how big * {@link #getOutputSize(int) getOutputSize} to determine how big
* the output buffer should be. * the output buffer should be.
* *
* @param output the buffer for the result * @param output the buffer for the result
* *
* @return the number of bytes stored in <code>output</code> * @return the number of bytes stored in {@code output}
* *
* @exception IllegalStateException if this exemption mechanism is in * @exception IllegalStateException if this exemption mechanism is in
* a wrong state (e.g., has not been initialized). * a wrong state (e.g., has not been initialized).
@ -450,20 +450,20 @@ public class ExemptionMechanism {
/** /**
* Generates the exemption mechanism key blob, and stores the result in * Generates the exemption mechanism key blob, and stores the result in
* the <code>output</code> buffer, starting at <code>outputOffset</code> * the {@code output} buffer, starting at {@code outputOffset}
* inclusive. * inclusive.
* *
* <p>If the <code>output</code> buffer is too small to hold the result, * <p>If the {@code output} buffer is too small to hold the result,
* a <code>ShortBufferException</code> is thrown. In this case, repeat this * a {@code ShortBufferException} is thrown. In this case, repeat this
* call with a larger output buffer. Use * call with a larger output buffer. Use
* {@link #getOutputSize(int) getOutputSize} to determine how big * {@link #getOutputSize(int) getOutputSize} to determine how big
* the output buffer should be. * the output buffer should be.
* *
* @param output the buffer for the result * @param output the buffer for the result
* @param outputOffset the offset in <code>output</code> where the result * @param outputOffset the offset in {@code output} where the result
* is stored * is stored
* *
* @return the number of bytes stored in <code>output</code> * @return the number of bytes stored in {@code output}
* *
* @exception IllegalStateException if this exemption mechanism is in * @exception IllegalStateException if this exemption mechanism is in
* a wrong state (e.g., has not been initialized). * a wrong state (e.g., has not been initialized).

12
src/java.base/share/classes/javax/crypto/ExemptionMechanismException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -39,17 +39,17 @@ public class ExemptionMechanismException extends GeneralSecurityException {
private static final long serialVersionUID = 1572699429277957109L; private static final long serialVersionUID = 1572699429277957109L;
/** /**
* Constructs a ExemptionMechanismException with no detailed message. * Constructs an {@code ExemptionMechanismException} with no detailed
* (A detailed message is a String that describes this particular * message. (A detailed message is a {@code String} that describes this
* exception.) * particular exception.)
*/ */
public ExemptionMechanismException() { public ExemptionMechanismException() {
super(); super();
} }
/** /**
* Constructs a ExemptionMechanismException with the specified * Constructs an {@code ExemptionMechanismException} with the specified
* detailed message. (A detailed message is a String that describes * detailed message. (A detailed message is a {@code String} that describes
* this particular exception.) * this particular exception.)
* *
* @param msg the detailed message. * @param msg the detailed message.

26
src/java.base/share/classes/javax/crypto/ExemptionMechanismSpi.java
View file

@ -33,7 +33,7 @@ import java.security.spec.AlgorithmParameterSpec;
/** /**
* This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
* for the <code>ExemptionMechanism</code> class. * for the {@code ExemptionMechanism} class.
* All the abstract methods in this class must be implemented by each * All the abstract methods in this class must be implemented by each
* cryptographic service provider who wishes to supply the implementation * cryptographic service provider who wishes to supply the implementation
* of a particular exemption mechanism. * of a particular exemption mechanism.
@ -54,7 +54,7 @@ public abstract class ExemptionMechanismSpi {
* Returns the length in bytes that an output buffer would need to be in * Returns the length in bytes that an output buffer would need to be in
* order to hold the result of the next * order to hold the result of the next
* {@link #engineGenExemptionBlob(byte[], int) engineGenExemptionBlob} * {@link #engineGenExemptionBlob(byte[], int) engineGenExemptionBlob}
* operation, given the input length <code>inputLen</code> (in bytes). * operation, given the input length {@code inputLen} (in bytes).
* *
* <p>The actual output length of the next * <p>The actual output length of the next
* {@link #engineGenExemptionBlob(byte[], int) engineGenExemptionBlob} * {@link #engineGenExemptionBlob(byte[], int) engineGenExemptionBlob}
@ -70,11 +70,11 @@ public abstract class ExemptionMechanismSpi {
* Initializes this exemption mechanism with a key. * Initializes this exemption mechanism with a key.
* *
* <p>If this exemption mechanism requires any algorithm parameters * <p>If this exemption mechanism requires any algorithm parameters
* that cannot be derived from the given <code>key</code>, the underlying * that cannot be derived from the given {@code key}, the underlying
* exemption mechanism implementation is supposed to generate the required * exemption mechanism implementation is supposed to generate the required
* parameters itself (using provider-specific default values); in the case * parameters itself (using provider-specific default values); in the case
* that algorithm parameters must be specified by the caller, an * that algorithm parameters must be specified by the caller, an
* <code>InvalidKeyException</code> is raised. * {@code InvalidKeyException} is raised.
* *
* @param key the key for this exemption mechanism * @param key the key for this exemption mechanism
* *
@ -91,11 +91,11 @@ public abstract class ExemptionMechanismSpi {
* parameters. * parameters.
* *
* <p>If this exemption mechanism requires any algorithm parameters and * <p>If this exemption mechanism requires any algorithm parameters and
* <code>params</code> is null, the underlying exemption mechanism * {@code params} is null, the underlying exemption mechanism
* implementation is supposed to generate the required parameters * implementation is supposed to generate the required parameters
* itself (using provider-specific default values); in the case that * itself (using provider-specific default values); in the case that
* algorithm parameters must be specified by the caller, an * algorithm parameters must be specified by the caller, an
* <code>InvalidAlgorithmParameterException</code> is raised. * {@code InvalidAlgorithmParameterException} is raised.
* *
* @param key the key for this exemption mechanism * @param key the key for this exemption mechanism
* @param params the algorithm parameters * @param params the algorithm parameters
@ -116,11 +116,11 @@ public abstract class ExemptionMechanismSpi {
* parameters. * parameters.
* *
* <p>If this exemption mechanism requires any algorithm parameters * <p>If this exemption mechanism requires any algorithm parameters
* and <code>params</code> is null, the underlying exemption mechanism * and {@code params} is null, the underlying exemption mechanism
* implementation is supposed to generate the required parameters * implementation is supposed to generate the required parameters
* itself (using provider-specific default values); in the case that * itself (using provider-specific default values); in the case that
* algorithm parameters must be specified by the caller, an * algorithm parameters must be specified by the caller, an
* <code>InvalidAlgorithmParameterException</code> is raised. * {@code InvalidAlgorithmParameterException} is raised.
* *
* @param key the key for this exemption mechanism * @param key the key for this exemption mechanism
* @param params the algorithm parameters * @param params the algorithm parameters
@ -149,20 +149,20 @@ public abstract class ExemptionMechanismSpi {
/** /**
* Generates the exemption mechanism key blob, and stores the result in * Generates the exemption mechanism key blob, and stores the result in
* the <code>output</code> buffer, starting at <code>outputOffset</code> * the {@code output} buffer, starting at {@code outputOffset}
* inclusive. * inclusive.
* *
* <p>If the <code>output</code> buffer is too small to hold the result, * <p>If the {@code output} buffer is too small to hold the result,
* a <code>ShortBufferException</code> is thrown. In this case, repeat this * a {@code ShortBufferException} is thrown. In this case, repeat this
* call with a larger output buffer. Use * call with a larger output buffer. Use
* {@link #engineGetOutputSize(int) engineGetOutputSize} to determine * {@link #engineGetOutputSize(int) engineGetOutputSize} to determine
* how big the output buffer should be. * how big the output buffer should be.
* *
* @param output the buffer for the result * @param output the buffer for the result
* @param outputOffset the offset in <code>output</code> where the result * @param outputOffset the offset in {@code output} where the result
* is stored * is stored
* *
* @return the number of bytes stored in <code>output</code> * @return the number of bytes stored in {@code output}
* *
* @exception ShortBufferException if the given output buffer is too small * @exception ShortBufferException if the given output buffer is too small
* to hold the result. * to hold the result.

8
src/java.base/share/classes/javax/crypto/IllegalBlockSizeException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -41,8 +41,8 @@ public class IllegalBlockSizeException
private static final long serialVersionUID = -1965144811953540392L; private static final long serialVersionUID = -1965144811953540392L;
/** /**
* Constructs an IllegalBlockSizeException with no detail message. * Constructs an {@code IllegalBlockSizeException} with no detail message.
* A detail message is a String that describes this particular * A detail message is a {@code String} that describes this particular
* exception. * exception.
*/ */
public IllegalBlockSizeException() { public IllegalBlockSizeException() {
@ -50,7 +50,7 @@ public class IllegalBlockSizeException
} }
/** /**
* Constructs an IllegalBlockSizeException with the specified * Constructs an {@code IllegalBlockSizeException} with the specified
* detail message. * detail message.
* *
* @param msg the detail message. * @param msg the detail message.

32
src/java.base/share/classes/javax/crypto/KeyAgreement.java
View file

@ -105,7 +105,7 @@ public class KeyAgreement {
private final Object lock; private final Object lock;
/** /**
* Creates a KeyAgreement object. * Creates a {@code KeyAgreement} object.
* *
* @param keyAgreeSpi the delegate * @param keyAgreeSpi the delegate
* @param provider the provider * @param provider the provider
@ -143,11 +143,11 @@ public class KeyAgreement {
* Returns a {@code KeyAgreement} object that implements the * Returns a {@code KeyAgreement} object that implements the
* specified key agreement algorithm. * specified key agreement algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new KeyAgreement object encapsulating the * A new {@code KeyAgreement} object encapsulating the
* KeyAgreementSpi implementation from the first * {@code KeyAgreementSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -199,8 +199,8 @@ public class KeyAgreement {
* Returns a {@code KeyAgreement} object that implements the * Returns a {@code KeyAgreement} object that implements the
* specified key agreement algorithm. * specified key agreement algorithm.
* *
* <p> A new KeyAgreement object encapsulating the * <p> A new {@code KeyAgreement} object encapsulating the
* KeyAgreementSpi implementation from the specified provider * {@code KeyAgreementSpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -246,9 +246,9 @@ public class KeyAgreement {
* Returns a {@code KeyAgreement} object that implements the * Returns a {@code KeyAgreement} object that implements the
* specified key agreement algorithm. * specified key agreement algorithm.
* *
* <p> A new KeyAgreement object encapsulating the * <p> A new {@code KeyAgreement} object encapsulating the
* KeyAgreementSpi implementation from the specified Provider * {@code KeyAgreementSpi} implementation from the specified
* object is returned. Note that the specified Provider object * provider is returned. Note that the specified provider
* does not have to be registered in the provider list. * does not have to be registered in the provider list.
* *
* @param algorithm the standard name of the requested key agreement * @param algorithm the standard name of the requested key agreement
@ -267,7 +267,7 @@ public class KeyAgreement {
* *
* @throws NoSuchAlgorithmException if a {@code KeyAgreementSpi} * @throws NoSuchAlgorithmException if a {@code KeyAgreementSpi}
* implementation for the specified algorithm is not available * implementation for the specified algorithm is not available
* from the specified Provider object * from the specified {@code Provider} object
* *
* @throws NullPointerException if {@code algorithm} is {@code null} * @throws NullPointerException if {@code algorithm} is {@code null}
* *
@ -437,7 +437,8 @@ public class KeyAgreement {
* implementation of the highest-priority * implementation of the highest-priority
* installed provider as the source of randomness. * installed provider as the source of randomness.
* (If none of the installed providers supply an implementation of * (If none of the installed providers supply an implementation of
* SecureRandom, a system-provided source of randomness will be used.) * {@code SecureRandom}, a system-provided source of randomness
* will be used.)
* *
* @param key the party's private information. For example, in the case * @param key the party's private information. For example, in the case
* of the Diffie-Hellman key agreement, this would be the party's own * of the Diffie-Hellman key agreement, this would be the party's own
@ -500,7 +501,8 @@ public class KeyAgreement {
* implementation of the highest-priority * implementation of the highest-priority
* installed provider as the source of randomness. * installed provider as the source of randomness.
* (If none of the installed providers supply an implementation of * (If none of the installed providers supply an implementation of
* SecureRandom, a system-provided source of randomness will be used.) * {@code SecureRandom}, a system-provided source of randomness
* will be used.)
* *
* @param key the party's private information. For example, in the case * @param key the party's private information. For example, in the case
* of the Diffie-Hellman key agreement, this would be the party's own * of the Diffie-Hellman key agreement, this would be the party's own
@ -566,7 +568,7 @@ public class KeyAgreement {
* @param lastPhase flag which indicates whether this is the last * @param lastPhase flag which indicates whether this is the last
* phase of this key agreement. * phase of this key agreement.
* *
* @return the (intermediate) key resulting from this phase, or null * @return the (intermediate) key resulting from this phase, or {@code null}
* if this phase does not yield a key * if this phase does not yield a key
* *
* @exception InvalidKeyException if the given key is inappropriate for * @exception InvalidKeyException if the given key is inappropriate for

36
src/java.base/share/classes/javax/crypto/KeyAgreementSpi.java
View file

@ -30,27 +30,27 @@ import java.security.spec.*;
/** /**
* This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
* for the <code>KeyAgreement</code> class. * for the {@code KeyAgreement} class.
* All the abstract methods in this class must be implemented by each * All the abstract methods in this class must be implemented by each
* cryptographic service provider who wishes to supply the implementation * cryptographic service provider who wishes to supply the implementation
* of a particular key agreement algorithm. * of a particular key agreement algorithm.
* *
* <p> The keys involved in establishing a shared secret are created by one * <p> The keys involved in establishing a shared secret are created by one
* of the * of the
* key generators (<code>KeyPairGenerator</code> or * key generators ({@code KeyPairGenerator} or
* <code>KeyGenerator</code>), a <code>KeyFactory</code>, or as a result from * {@code KeyGenerator}), a {@code KeyFactory}, or as a result from
* an intermediate phase of the key agreement protocol * an intermediate phase of the key agreement protocol
* ({@link #engineDoPhase(java.security.Key, boolean) engineDoPhase}). * ({@link #engineDoPhase(java.security.Key, boolean) engineDoPhase}).
* *
* <p> For each of the correspondents in the key exchange, * <p> For each of the correspondents in the key exchange,
* <code>engineDoPhase</code> * {@code engineDoPhase}
* needs to be called. For example, if the key exchange is with one other * needs to be called. For example, if the key exchange is with one other
* party, <code>engineDoPhase</code> needs to be called once, with the * party, {@code engineDoPhase} needs to be called once, with the
* <code>lastPhase</code> flag set to <code>true</code>. * {@code lastPhase} flag set to {@code true}.
* If the key exchange is * If the key exchange is
* with two other parties, <code>engineDoPhase</code> needs to be called twice, * with two other parties, {@code engineDoPhase} needs to be called twice,
* the first time setting the <code>lastPhase</code> flag to * the first time setting the {@code lastPhase} flag to
* <code>false</code>, and the second time setting it to <code>true</code>. * {@code false}, and the second time setting it to {@code true}.
* There may be any number of parties involved in a key exchange. * There may be any number of parties involved in a key exchange.
* *
* @author Jan Luehe * @author Jan Luehe
@ -73,10 +73,10 @@ public abstract class KeyAgreementSpi {
* parameters required for this key agreement. * parameters required for this key agreement.
* *
* <p> If the key agreement algorithm requires random bytes, it gets them * <p> If the key agreement algorithm requires random bytes, it gets them
* from the given source of randomness, <code>random</code>. * from the given source of randomness, {@code random}.
* However, if the underlying * However, if the underlying
* algorithm implementation does not require any random bytes, * algorithm implementation does not require any random bytes,
* <code>random</code> is ignored. * {@code random} is ignored.
* *
* @param key the party's private information. For example, in the case * @param key the party's private information. For example, in the case
* of the Diffie-Hellman key agreement, this would be the party's own * of the Diffie-Hellman key agreement, this would be the party's own
@ -121,8 +121,8 @@ public abstract class KeyAgreementSpi {
* @param lastPhase flag which indicates whether this is the last * @param lastPhase flag which indicates whether this is the last
* phase of this key agreement. * phase of this key agreement.
* *
* @return the (intermediate) key resulting from this phase, or null if * @return the (intermediate) key resulting from this phase,
* this phase does not yield a key * or {@code null} if this phase does not yield a key
* *
* @exception InvalidKeyException if the given key is inappropriate for * @exception InvalidKeyException if the given key is inappropriate for
* this phase. * this phase.
@ -157,10 +157,10 @@ public abstract class KeyAgreementSpi {
/** /**
* Generates the shared secret, and places it into the buffer * Generates the shared secret, and places it into the buffer
* <code>sharedSecret</code>, beginning at <code>offset</code> inclusive. * {@code sharedSecret}, beginning at {@code offset} inclusive.
* *
* <p>If the <code>sharedSecret</code> buffer is too small to hold the * <p>If the {@code sharedSecret} buffer is too small to hold the
* result, a <code>ShortBufferException</code> is thrown. * result, a {@code ShortBufferException} is thrown.
* In this case, this call should be repeated with a larger output buffer. * In this case, this call should be repeated with a larger output buffer.
* *
* <p>This method resets this {@code KeyAgreementSpi} object to the state * <p>This method resets this {@code KeyAgreementSpi} object to the state
@ -175,10 +175,10 @@ public abstract class KeyAgreementSpi {
* subsequent operations. * subsequent operations.
* *
* @param sharedSecret the buffer for the shared secret * @param sharedSecret the buffer for the shared secret
* @param offset the offset in <code>sharedSecret</code> where the * @param offset the offset in {@code sharedSecret} where the
* shared secret will be stored * shared secret will be stored
* *
* @return the number of bytes placed into <code>sharedSecret</code> * @return the number of bytes placed into {@code sharedSecret}
* *
* @exception IllegalStateException if this key agreement has not been * @exception IllegalStateException if this key agreement has not been
* initialized or if {@code doPhase} has not been called to supply the * initialized or if {@code doPhase} has not been called to supply the

42
src/java.base/share/classes/javax/crypto/KeyGenerator.java
View file

@ -41,9 +41,9 @@ import sun.security.util.Debug;
* <p>Key generators are constructed using one of the {@code getInstance} * <p>Key generators are constructed using one of the {@code getInstance}
* class methods of this class. * class methods of this class.
* *
* <p>KeyGenerator objects are reusable, i.e., after a key has been * <p>{@code KeyGenerator} objects are reusable, i.e., after a key has been
* generated, the same KeyGenerator object can be re-used to generate further * generated, the same {@code KeyGenerator} object can be re-used
* keys. * to generate further keys.
* *
* <p>There are two ways to generate a key: in an algorithm-independent * <p>There are two ways to generate a key: in an algorithm-independent
* manner, and in an algorithm-specific manner. * manner, and in an algorithm-specific manner.
@ -55,9 +55,9 @@ import sun.security.util.Debug;
* <i>source of randomness</i>. * <i>source of randomness</i>.
* There is an * There is an
* {@link #init(int, java.security.SecureRandom) init} * {@link #init(int, java.security.SecureRandom) init}
* method in this KeyGenerator class that takes these two universally * method in this {@code KeyGenerator} class that takes these two universally
* shared types of arguments. There is also one that takes just a * shared types of arguments. There is also one that takes just a
* {@code keysize} argument, and uses the SecureRandom implementation * {@code keysize} argument, and uses the {@code SecureRandom} implementation
* of the highest-priority installed provider as the source of randomness * of the highest-priority installed provider as the source of randomness
* (or a system-provided source of randomness if none of the installed * (or a system-provided source of randomness if none of the installed
* providers supply a SecureRandom implementation), and one that takes just a * providers supply a SecureRandom implementation), and one that takes just a
@ -80,17 +80,17 @@ import sun.security.util.Debug;
* providers supply a SecureRandom implementation). * providers supply a SecureRandom implementation).
* </ul> * </ul>
* *
* <p>In case the client does not explicitly initialize the KeyGenerator * <p>In case the client does not explicitly initialize the {@code KeyGenerator}
* (via a call to an {@code init} method), each provider must * (via a call to an {@code init} method), each provider must
* supply (and document) a default initialization. * supply (and document) a default initialization.
* See the Keysize Restriction sections of the * See the Keysize Restriction sections of the
* {@extLink security_guide_jdk_providers JDK Providers} * {@extLink security_guide_jdk_providers JDK Providers}
* document for information on the KeyGenerator defaults used by * document for information on the {@code KeyGenerator} defaults used by
* JDK providers. * JDK providers.
* However, note that defaults may vary across different providers. * However, note that defaults may vary across different providers.
* Additionally, the default value for a provider may change in a future * Additionally, the default value for a provider may change in a future
* version. Therefore, it is recommended to explicitly initialize the * version. Therefore, it is recommended to explicitly initialize the
* KeyGenerator instead of relying on provider-specific defaults. * {@code KeyGenerator} instead of relying on provider-specific defaults.
* *
* <p> Every implementation of the Java platform is required to support the * <p> Every implementation of the Java platform is required to support the
* following standard {@code KeyGenerator} algorithms with the keysizes in * following standard {@code KeyGenerator} algorithms with the keysizes in
@ -147,7 +147,7 @@ public class KeyGenerator {
private SecureRandom initRandom; private SecureRandom initRandom;
/** /**
* Creates a KeyGenerator object. * Creates a {@code KeyGenerator} object.
* *
* @param keyGenSpi the delegate * @param keyGenSpi the delegate
* @param provider the provider * @param provider the provider
@ -204,11 +204,11 @@ public class KeyGenerator {
* Returns a {@code KeyGenerator} object that generates secret keys * Returns a {@code KeyGenerator} object that generates secret keys
* for the specified algorithm. * for the specified algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new KeyGenerator object encapsulating the * A new {@code KeyGenerator} object encapsulating the
* KeyGeneratorSpi implementation from the first * {@code KeyGeneratorSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -247,8 +247,8 @@ public class KeyGenerator {
* Returns a {@code KeyGenerator} object that generates secret keys * Returns a {@code KeyGenerator} object that generates secret keys
* for the specified algorithm. * for the specified algorithm.
* *
* <p> A new KeyGenerator object encapsulating the * <p> A new {@code KeyGenerator} object encapsulating the
* KeyGeneratorSpi implementation from the specified provider * {@code KeyGeneratorSpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -293,9 +293,9 @@ public class KeyGenerator {
* Returns a {@code KeyGenerator} object that generates secret keys * Returns a {@code KeyGenerator} object that generates secret keys
* for the specified algorithm. * for the specified algorithm.
* *
* <p> A new KeyGenerator object encapsulating the * <p> A new {@code KeyGenerator} object encapsulating the
* KeyGeneratorSpi implementation from the specified Provider * {@code KeyGeneratorSpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * object is returned. Note that the specified provider object
* does not have to be registered in the provider list. * does not have to be registered in the provider list.
* *
* @param algorithm the standard name of the requested key algorithm. * @param algorithm the standard name of the requested key algorithm.
@ -343,8 +343,8 @@ public class KeyGenerator {
/** /**
* Update the active spi of this class and return the next * Update the active spi of this class and return the next
* implementation for failover. If no more implementations are * implementation for failover. If no more implementations are
* available, this method returns null. However, the active spi of * available, this method returns {@code null}. However, the active spi of
* this class is never set to null. * this class is never set to {@code null}.
*/ */
private KeyGeneratorSpi nextSpi(KeyGeneratorSpi oldSpi, private KeyGeneratorSpi nextSpi(KeyGeneratorSpi oldSpi,
boolean reinit) { boolean reinit) {

4
src/java.base/share/classes/javax/crypto/KeyGeneratorSpi.java
View file

@ -30,7 +30,7 @@ import java.security.spec.*;
/** /**
* This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
* for the <code>KeyGenerator</code> class. * for the {@code KeyGenerator} class.
* All the abstract methods in this class must be implemented by each * All the abstract methods in this class must be implemented by each
* cryptographic service provider who wishes to supply the implementation * cryptographic service provider who wishes to supply the implementation
* of a key generator for a particular algorithm. * of a key generator for a particular algorithm.
@ -74,7 +74,7 @@ public abstract class KeyGeneratorSpi {
* @param params the key generation parameters * @param params the key generation parameters
* @param random the source of randomness for this key generator * @param random the source of randomness for this key generator
* *
* @exception InvalidAlgorithmParameterException if <code>params</code> is * @exception InvalidAlgorithmParameterException if {@code params} is
* inappropriate for this key generator * inappropriate for this key generator
*/ */
protected abstract void engineInit(AlgorithmParameterSpec params, protected abstract void engineInit(AlgorithmParameterSpec params,

20
src/java.base/share/classes/javax/crypto/Mac.java
View file

@ -142,11 +142,11 @@ public class Mac implements Cloneable {
* Returns a {@code Mac} object that implements the * Returns a {@code Mac} object that implements the
* specified MAC algorithm. * specified MAC algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new Mac object encapsulating the * A new {@code Mac} object encapsulating the
* MacSpi implementation from the first * {@code MacSpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -195,8 +195,8 @@ public class Mac implements Cloneable {
* Returns a {@code Mac} object that implements the * Returns a {@code Mac} object that implements the
* specified MAC algorithm. * specified MAC algorithm.
* *
* <p> A new Mac object encapsulating the * <p> A new {@code Mac} object encapsulating the
* MacSpi implementation from the specified provider * {@code MacSpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -239,9 +239,9 @@ public class Mac implements Cloneable {
* Returns a {@code Mac} object that implements the * Returns a {@code Mac} object that implements the
* specified MAC algorithm. * specified MAC algorithm.
* *
* <p> A new Mac object encapsulating the * <p> A new {@code Mac} object encapsulating the
* MacSpi implementation from the specified Provider * {@code MacSpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * is returned. Note that the specified provider
* does not have to be registered in the provider list. * does not have to be registered in the provider list.
* *
* @param algorithm the standard name of the requested MAC algorithm. * @param algorithm the standard name of the requested MAC algorithm.

14
src/java.base/share/classes/javax/crypto/MacSpi.java
View file

@ -32,7 +32,7 @@ import java.nio.ByteBuffer;
/** /**
* This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
* for the <code>Mac</code> class. * for the {@code Mac} class.
* All the abstract methods in this class must be implemented by each * All the abstract methods in this class must be implemented by each
* cryptographic service provider who wishes to supply the implementation * cryptographic service provider who wishes to supply the implementation
* of a particular MAC algorithm. * of a particular MAC algorithm.
@ -82,18 +82,18 @@ public abstract class MacSpi {
protected abstract void engineUpdate(byte input); protected abstract void engineUpdate(byte input);
/** /**
* Processes the first <code>len</code> bytes in <code>input</code>, * Processes the first {@code len} bytes in {@code input},
* starting at <code>offset</code> inclusive. * starting at {@code offset} inclusive.
* *
* @param input the input buffer. * @param input the input buffer.
* @param offset the offset in <code>input</code> where the input starts. * @param offset the offset in {@code input} where the input starts.
* @param len the number of bytes to process. * @param len the number of bytes to process.
*/ */
protected abstract void engineUpdate(byte[] input, int offset, int len); protected abstract void engineUpdate(byte[] input, int offset, int len);
/** /**
* Processes <code>input.remaining()</code> bytes in the ByteBuffer * Processes {@code input.remaining()} bytes in the ByteBuffer
* <code>input</code>, starting at <code>input.position()</code>. * {@code input}, starting at {@code input.position()}.
* Upon return, the buffer's position will be equal to its limit; * Upon return, the buffer's position will be equal to its limit;
* its limit will not have changed. * its limit will not have changed.
* *
@ -146,7 +146,7 @@ public abstract class MacSpi {
* @return a clone if the implementation is cloneable. * @return a clone if the implementation is cloneable.
* *
* @exception CloneNotSupportedException if this is called * @exception CloneNotSupportedException if this is called
* on an implementation that does not support <code>Cloneable</code>. * on an implementation that does not support {@code Cloneable}.
*/ */
public Object clone() throws CloneNotSupportedException { public Object clone() throws CloneNotSupportedException {
if (this instanceof Cloneable) { if (this instanceof Cloneable) {

8
src/java.base/share/classes/javax/crypto/NoSuchPaddingException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -42,8 +42,8 @@ public class NoSuchPaddingException extends GeneralSecurityException {
private static final long serialVersionUID = -4572885201200175466L; private static final long serialVersionUID = -4572885201200175466L;
/** /**
* Constructs a NoSuchPaddingException with no detail * Constructs a {@code NoSuchPaddingException} with no detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
*/ */
public NoSuchPaddingException() { public NoSuchPaddingException() {
@ -51,7 +51,7 @@ public class NoSuchPaddingException extends GeneralSecurityException {
} }
/** /**
* Constructs a NoSuchPaddingException with the specified * Constructs a {@code NoSuchPaddingException} with the specified
* detail message. * detail message.
* *
* @param msg the detail message. * @param msg the detail message.

6
src/java.base/share/classes/javax/crypto/NullCipher.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -26,7 +26,7 @@
package javax.crypto; package javax.crypto;
/** /**
* The NullCipher class is a class that provides an * The {@code NullCipher} class is a class that provides an
* "identity cipher" -- one that does not transform the plain text. As * "identity cipher" -- one that does not transform the plain text. As
* a consequence, the ciphertext is identical to the plaintext. All * a consequence, the ciphertext is identical to the plaintext. All
* initialization methods do nothing, while the blocksize is set to 1 * initialization methods do nothing, while the blocksize is set to 1
@ -39,7 +39,7 @@ package javax.crypto;
public class NullCipher extends Cipher { public class NullCipher extends Cipher {
/** /**
* Creates a NullCipher object. * Creates a {@code NullCipher} object.
*/ */
public NullCipher() { public NullCipher() {
super(new NullCipherSpi(), null); super(new NullCipherSpi(), null);

15
src/java.base/share/classes/javax/crypto/ProviderVerifier.java
View file

@ -51,10 +51,10 @@ final class ProviderVerifier {
private CryptoPermissions appPerms = null; private CryptoPermissions appPerms = null;
/** /**
* Creates a ProviderVerifier object to verify the given URL. * Creates a {@code ProviderVerifier} object to verify the given URL.
* *
* @param jarURL the JAR file to be verified. * @param jarURL the JAR file to be verified.
* @param savePerms if true, save the permissions allowed by the * @param savePerms if {@code true}, save the permissions allowed by the
* exemption mechanism * exemption mechanism
*/ */
ProviderVerifier(URL jarURL, boolean savePerms) { ProviderVerifier(URL jarURL, boolean savePerms) {
@ -62,11 +62,11 @@ final class ProviderVerifier {
} }
/** /**
* Creates a ProviderVerifier object to verify the given URL. * Creates a {@code ProviderVerifier} object to verify the given URL.
* *
* @param jarURL the JAR file to be verified * @param jarURL the JAR file to be verified
* @param provider the corresponding provider. * @param provider the corresponding provider.
* @param savePerms if true, save the permissions allowed by the * @param savePerms if {@code true}, save the permissions allowed by the
* exemption mechanism * exemption mechanism
*/ */
ProviderVerifier(URL jarURL, Provider provider, boolean savePerms) { ProviderVerifier(URL jarURL, Provider provider, boolean savePerms) {
@ -154,7 +154,7 @@ final class ProviderVerifier {
} }
/** /**
* Returns true if the given provider is JDK trusted crypto provider * Returns {@code true} if the given provider is JDK trusted crypto provider
* if the implementation supports fast-path verification. * if the implementation supports fast-path verification.
*/ */
static boolean isTrustedCryptoProvider(Provider provider) { static boolean isTrustedCryptoProvider(Provider provider) {
@ -165,8 +165,9 @@ final class ProviderVerifier {
* Returns the permissions which are bundled with the JAR file, * Returns the permissions which are bundled with the JAR file,
* aka the "cryptoperms" file. * aka the "cryptoperms" file.
* *
* NOTE: if this ProviderVerifier instance is constructed with "savePerms" * NOTE: if this {@code ProviderVerifier} instance is constructed
* equal to false, then this method would always return null. * with "savePerms" equal to {@code false}, then this method would always
* return {@code null}.
*/ */
CryptoPermissions getPermissions() { CryptoPermissions getPermissions() {
return appPerms; return appPerms;

75
src/java.base/share/classes/javax/crypto/SealedObject.java
View file

@ -40,17 +40,17 @@ import java.util.Arrays;
* This class enables a programmer to create an object and protect its * This class enables a programmer to create an object and protect its
* confidentiality with a cryptographic algorithm. * confidentiality with a cryptographic algorithm.
* *
* <p> Given any Serializable object, one can create a SealedObject * <p> Given any {@code Serializable} object, one can create a
* that encapsulates the original object, in serialized * {@code SealedObject} that encapsulates the original object, in serialized
* format (i.e., a "deep copy"), and seals (encrypts) its serialized contents, * format (i.e., a "deep copy"), and seals (encrypts) its serialized contents,
* using a cryptographic algorithm such as AES, to protect its * using a cryptographic algorithm such as AES, to protect its
* confidentiality. The encrypted content can later be decrypted (with * confidentiality. The encrypted content can later be decrypted (with
* the corresponding algorithm using the correct decryption key) and * the corresponding algorithm using the correct decryption key) and
* de-serialized, yielding the original object. * de-serialized, yielding the original object.
* *
* <p> Note that the Cipher object must be fully initialized with the * <p> Note that the {@code Cipher} object must be fully initialized with
* correct algorithm, key, padding scheme, etc., before being applied * the correct algorithm, key, padding scheme, etc., before being applied
* to a SealedObject. * to a {@code SealedObject}.
* *
* <p> The original object that was sealed can be recovered in two different * <p> The original object that was sealed can be recovered in two different
* ways: * ways:
@ -58,9 +58,9 @@ import java.util.Arrays;
* <ul> * <ul>
* *
* <li>by using the {@link #getObject(javax.crypto.Cipher) getObject} * <li>by using the {@link #getObject(javax.crypto.Cipher) getObject}
* method that takes a <code>Cipher</code> object. * method that takes a {@code Cipher} object.
* *
* <p> This method requires a fully initialized <code>Cipher</code> object, * <p> This method requires a fully initialized {@code Cipher} object,
* initialized with the * initialized with the
* exact same algorithm, key, padding scheme, etc., that were used to seal the * exact same algorithm, key, padding scheme, etc., that were used to seal the
* object. * object.
@ -73,9 +73,9 @@ import java.util.Arrays;
* *
* <li>by using one of the * <li>by using one of the
* {@link #getObject(java.security.Key) getObject} methods * {@link #getObject(java.security.Key) getObject} methods
* that take a <code>Key</code> object. * that take a {@code Key} object.
* *
* <p> In this approach, the <code>getObject</code> method creates a cipher * <p> In this approach, the {@code getObject} method creates a cipher
* object for the appropriate decryption algorithm and initializes it with the * object for the appropriate decryption algorithm and initializes it with the
* given decryption key and the algorithm parameters (if any) that were stored * given decryption key and the algorithm parameters (if any) that were stored
* in the sealed object. * in the sealed object.
@ -119,28 +119,29 @@ public class SealedObject implements Serializable {
private String paramsAlg = null; private String paramsAlg = null;
/** /**
* The cryptographic parameters used by the sealing Cipher, * The cryptographic parameters used by the sealing {@code Cipher} object,
* encoded in the default format. * encoded in the default format.
* <p> * <p>
* That is, <code>cipher.getParameters().getEncoded()</code>. * That is, {@code Cipher.getParameters().getEncoded()}.
* *
* @serial * @serial
*/ */
protected byte[] encodedParams = null; protected byte[] encodedParams = null;
/** /**
* Constructs a SealedObject from any Serializable object. * Constructs a {@code SealedObject} from any {@code Serializable} object.
* *
* <p>The given object is serialized, and its serialized contents are * <p>The given object is serialized, and its serialized contents are
* encrypted using the given Cipher, which must be fully initialized. * encrypted using the given {@code Cipher} object, which must be fully
* initialized.
* *
* <p>Any algorithm parameters that may be used in the encryption * <p>Any algorithm parameters that may be used in the encryption
* operation are stored inside the new <code>SealedObject</code>. * operation are stored inside the new {@code SealedObject}.
* *
* @param object the object to be sealed; can be null. * @param object the object to be sealed; can be {@code null}.
* @param c the cipher used to seal the object. * @param c the cipher used to seal the object.
* *
* @exception NullPointerException if the given cipher is null. * @exception NullPointerException if the given cipher is {@code null}.
* @exception IOException if an error occurs during serialization * @exception IOException if an error occurs during serialization
* @exception IllegalBlockSizeException if the given cipher is a block * @exception IllegalBlockSizeException if the given cipher is a block
* cipher, no padding has been requested, and the total input length * cipher, no padding has been requested, and the total input length
@ -190,10 +191,12 @@ public class SealedObject implements Serializable {
} }
/** /**
* Constructs a SealedObject object from the passed-in SealedObject. * Constructs a {@code SealedObject} object from the passed-in
* {@code SealedObject}.
* *
* @param so a SealedObject object * @param so a {@code SealedObject} object
* @exception NullPointerException if the given sealed object is null. * @exception NullPointerException if the given sealed object
* is {@code null}.
*/ */
protected SealedObject(SealedObject so) { protected SealedObject(SealedObject so) {
this.encryptedContent = so.encryptedContent.clone(); this.encryptedContent = so.encryptedContent.clone();
@ -221,11 +224,13 @@ public class SealedObject implements Serializable {
* <p>This method creates a cipher for the algorithm that had been used in * <p>This method creates a cipher for the algorithm that had been used in
* the sealing operation. * the sealing operation.
* If the default provider package provides an implementation of that * If the default provider package provides an implementation of that
* algorithm, an instance of Cipher containing that implementation is used. * algorithm, a {@code Cipher} object containing that
* implementation is used.
* If the algorithm is not available in the default package, other * If the algorithm is not available in the default package, other
* packages are searched. * packages are searched.
* The Cipher object is initialized for decryption, using the given * The {@code Cipher} object is initialized for decryption,
* <code>key</code> and the parameters (if any) that had been used in the * using the given
* {@code key} and the parameters (if any) that had been used in the
* sealing operation. * sealing operation.
* *
* <p>The encapsulated object is unsealed and de-serialized, before it is * <p>The encapsulated object is unsealed and de-serialized, before it is
@ -242,7 +247,7 @@ public class SealedObject implements Serializable {
* object is not available. * object is not available.
* @exception InvalidKeyException if the given key cannot be used to unseal * @exception InvalidKeyException if the given key cannot be used to unseal
* the object (e.g., it has the wrong algorithm). * the object (e.g., it has the wrong algorithm).
* @exception NullPointerException if <code>key</code> is null. * @exception NullPointerException if {@code key} is null.
*/ */
public final Object getObject(Key key) public final Object getObject(Key key)
throws IOException, ClassNotFoundException, NoSuchAlgorithmException, throws IOException, ClassNotFoundException, NoSuchAlgorithmException,
@ -267,15 +272,16 @@ public class SealedObject implements Serializable {
/** /**
* Retrieves the original (encapsulated) object. * Retrieves the original (encapsulated) object.
* *
* <p>The encapsulated object is unsealed (using the given Cipher, * <p>The encapsulated object is unsealed (using the given
* assuming that the Cipher is already properly initialized) and * {@code Cipher} object,
* de-serialized, before it is returned. * assuming that the {@code Cipher} object is already properly initialized)
* and de-serialized, before it is returned.
* *
* @param c the cipher used to unseal the object * @param c the cipher used to unseal the object
* *
* @return the original object. * @return the original object.
* *
* @exception NullPointerException if the given cipher is null. * @exception NullPointerException if the given cipher is {@code null}.
* @exception IOException if an error occurs during de-serialization * @exception IOException if an error occurs during de-serialization
* @exception ClassNotFoundException if an error occurs during * @exception ClassNotFoundException if an error occurs during
* de-serialization * de-serialization
@ -300,9 +306,10 @@ public class SealedObject implements Serializable {
* *
* <p>This method creates a cipher for the algorithm that had been used in * <p>This method creates a cipher for the algorithm that had been used in
* the sealing operation, using an implementation of that algorithm from * the sealing operation, using an implementation of that algorithm from
* the given <code>provider</code>. * the given {@code provider}.
* The Cipher object is initialized for decryption, using the given * The {@code Cipher} object is initialized for decryption,
* <code>key</code> and the parameters (if any) that had been used in the * using the given
* {@code key} and the parameters (if any) that had been used in the
* sealing operation. * sealing operation.
* *
* <p>The encapsulated object is unsealed and de-serialized, before it is * <p>The encapsulated object is unsealed and de-serialized, before it is
@ -314,7 +321,7 @@ public class SealedObject implements Serializable {
* *
* @return the original object. * @return the original object.
* *
* @exception IllegalArgumentException if the given provider is null * @exception IllegalArgumentException if the given provider is {@code null}
* or empty. * or empty.
* @exception IOException if an error occurs during de-serialization. * @exception IOException if an error occurs during de-serialization.
* @exception ClassNotFoundException if an error occurs during * @exception ClassNotFoundException if an error occurs during
@ -325,7 +332,7 @@ public class SealedObject implements Serializable {
* configured. * configured.
* @exception InvalidKeyException if the given key cannot be used to unseal * @exception InvalidKeyException if the given key cannot be used to unseal
* the object (e.g., it has the wrong algorithm). * the object (e.g., it has the wrong algorithm).
* @exception NullPointerException if <code>key</code> is null. * @exception NullPointerException if {@code key} is null.
*/ */
public final Object getObject(Key key, String provider) public final Object getObject(Key key, String provider)
throws IOException, ClassNotFoundException, NoSuchAlgorithmException, throws IOException, ClassNotFoundException, NoSuchAlgorithmException,
@ -412,12 +419,12 @@ public class SealedObject implements Serializable {
} }
/** /**
* Restores the state of the SealedObject from a stream. * Restores the state of the {@code SealedObject} from a stream.
* *
* @param s the object input stream. * @param s the object input stream.
* @throws IOException if an I/O error occurs * @throws IOException if an I/O error occurs
* @throws ClassNotFoundException if a serialized class cannot be loaded * @throws ClassNotFoundException if a serialized class cannot be loaded
* @throws NullPointerException if s is null * @throws NullPointerException if s is {@code null}
*/ */
@java.io.Serial @java.io.Serial
private void readObject(java.io.ObjectInputStream s) private void readObject(java.io.ObjectInputStream s)

26
src/java.base/share/classes/javax/crypto/SecretKeyFactory.java
View file

@ -95,7 +95,7 @@ public class SecretKeyFactory {
private Iterator<Service> serviceIterator; private Iterator<Service> serviceIterator;
/** /**
* Creates a SecretKeyFactory object. * Creates a {@code SecretKeyFactory} object.
* *
* @param keyFacSpi the delegate * @param keyFacSpi the delegate
* @param provider the provider * @param provider the provider
@ -124,11 +124,11 @@ public class SecretKeyFactory {
* Returns a {@code SecretKeyFactory} object that converts * Returns a {@code SecretKeyFactory} object that converts
* secret keys of the specified algorithm. * secret keys of the specified algorithm.
* *
* <p> This method traverses the list of registered security Providers, * <p> This method traverses the list of registered security providers,
* starting with the most preferred Provider. * starting with the most preferred provider.
* A new SecretKeyFactory object encapsulating the * A new {@code SecretKeyFactory} object encapsulating the
* SecretKeyFactorySpi implementation from the first * {@code SecretKeyFactorySpi} implementation from the first
* Provider that supports the specified algorithm is returned. * provider that supports the specified algorithm is returned.
* *
* <p> Note that the list of registered providers may be retrieved via * <p> Note that the list of registered providers may be retrieved via
* the {@link Security#getProviders() Security.getProviders()} method. * the {@link Security#getProviders() Security.getProviders()} method.
@ -168,8 +168,8 @@ public class SecretKeyFactory {
* Returns a {@code SecretKeyFactory} object that converts * Returns a {@code SecretKeyFactory} object that converts
* secret keys of the specified algorithm. * secret keys of the specified algorithm.
* *
* <p> A new SecretKeyFactory object encapsulating the * <p> A new {@code SecretKeyFactory} object encapsulating the
* SecretKeyFactorySpi implementation from the specified provider * {@code SecretKeyFactorySpi} implementation from the specified provider
* is returned. The specified provider must be registered * is returned. The specified provider must be registered
* in the security provider list. * in the security provider list.
* *
@ -215,9 +215,9 @@ public class SecretKeyFactory {
* Returns a {@code SecretKeyFactory} object that converts * Returns a {@code SecretKeyFactory} object that converts
* secret keys of the specified algorithm. * secret keys of the specified algorithm.
* *
* <p> A new SecretKeyFactory object encapsulating the * <p> A new {@code SecretKeyFactory} object encapsulating the
* SecretKeyFactorySpi implementation from the specified Provider * {@code SecretKeyFactorySpi} implementation from the specified provider
* object is returned. Note that the specified Provider object * object is returned. Note that the specified provider object
* does not have to be registered in the provider list. * does not have to be registered in the provider list.
* *
* @param algorithm the standard name of the requested secret-key * @param algorithm the standard name of the requested secret-key
@ -281,8 +281,8 @@ public class SecretKeyFactory {
/** /**
* Update the active spi of this class and return the next * Update the active spi of this class and return the next
* implementation for failover. If no more implementations are * implementation for failover. If no more implementations are
* available, this method returns null. However, the active spi of * available, this method returns {@code null}. However, the active spi of
* this class is never set to null. * this class is never set to {@code null}.
*/ */
private SecretKeyFactorySpi nextSpi(SecretKeyFactorySpi oldSpi) { private SecretKeyFactorySpi nextSpi(SecretKeyFactorySpi oldSpi) {
synchronized (lock) { synchronized (lock) {

14
src/java.base/share/classes/javax/crypto/SecretKeyFactorySpi.java
View file

@ -30,7 +30,7 @@ import java.security.spec.*;
/** /**
* This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
* for the <code>SecretKeyFactory</code> class. * for the {@code SecretKeyFactory} class.
* All the abstract methods in this class must be implemented by each * All the abstract methods in this class must be implemented by each
* cryptographic service provider who wishes to supply the implementation * cryptographic service provider who wishes to supply the implementation
* of a secret-key factory for a particular algorithm. * of a secret-key factory for a particular algorithm.
@ -38,9 +38,9 @@ import java.security.spec.*;
* <P> A provider should document all the key specifications supported by its * <P> A provider should document all the key specifications supported by its
* secret key factory. * secret key factory.
* For example, the DES secret-key factory supplied by the "SunJCE" provider * For example, the DES secret-key factory supplied by the "SunJCE" provider
* supports <code>DESKeySpec</code> as a transparent representation of DES * supports {@code DESKeySpec} as a transparent representation of DES
* keys, and that provider's secret-key factory for Triple DES keys supports * keys, and that provider's secret-key factory for Triple DES keys supports
* <code>DESedeKeySpec</code> as a transparent representation of Triple DES * {@code DESedeKeySpec} as a transparent representation of Triple DES
* keys. * keys.
* *
* @author Jan Luehe * @author Jan Luehe
@ -59,7 +59,7 @@ public abstract class SecretKeyFactorySpi {
public SecretKeyFactorySpi() {} public SecretKeyFactorySpi() {}
/** /**
* Generates a <code>SecretKey</code> object from the * Generates a {@code SecretKey} object from the
* provided key specification (key material). * provided key specification (key material).
* *
* @param keySpec the specification (key material) of the secret key * @param keySpec the specification (key material) of the secret key
@ -86,9 +86,9 @@ public abstract class SecretKeyFactorySpi {
* *
* @exception InvalidKeySpecException if the requested key specification is * @exception InvalidKeySpecException if the requested key specification is
* inappropriate for the given key (e.g., the algorithms associated with * inappropriate for the given key (e.g., the algorithms associated with
* <code>key</code> and <code>keySpec</code> do not match, or * {@code key} and {@code keySpec} do not match, or
* <code>key</code> references a key on a cryptographic hardware device * {@code key} references a key on a cryptographic hardware device
* whereas <code>keySpec</code> is the specification of a software-based * whereas {@code keySpec} is the specification of a software-based
* key), or the given key cannot be dealt with * key), or the given key cannot be dealt with
* (e.g., the given key has an algorithm or format not supported by this * (e.g., the given key has an algorithm or format not supported by this
* secret-key factory). * secret-key factory).

8
src/java.base/share/classes/javax/crypto/ShortBufferException.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -42,8 +42,8 @@ public class ShortBufferException extends GeneralSecurityException {
private static final long serialVersionUID = 8427718640832943747L; private static final long serialVersionUID = 8427718640832943747L;
/** /**
* Constructs a ShortBufferException with no detail * Constructs a {@code ShortBufferException} with no detail
* message. A detail message is a String that describes this * message. A detail message is a {@code String} that describes this
* particular exception. * particular exception.
*/ */
public ShortBufferException() { public ShortBufferException() {
@ -51,7 +51,7 @@ public class ShortBufferException extends GeneralSecurityException {
} }
/** /**
* Constructs a ShortBufferException with the specified * Constructs a {@code ShortBufferException} with the specified
* detail message. * detail message.
* *
* @param msg the detail message. * @param msg the detail message.