OpenJDK 24 · java.net.SocketPermission · APIdia, the JavaDoc alternative

This class represents access to a network via sockets. A SocketPermission consists of a host specification and a set of "actions" specifying ways to connect to that host. The host is specified as

    host = (hostname | IPv4address | iPv6reference) [:portrange]
    portrange = portnumber | -portnumber | portnumber-[portnumber]

The host is expressed as a DNS name, as a numerical IP address, or as "localhost" (for the local machine). The wildcard "*" may be included once in a DNS name host specification. If it is included, it must be in the leftmost position, as in "*.example.com".

The format of the IPv6reference should follow that specified in RFC 2732: Format for Literal IPv6 Addresses in URLs:

    ipv6reference = "[" IPv6address "]"

For example, you can construct a SocketPermission instance as the following:

    String hostAddress = inetaddress.getHostAddress();
    if (inetaddress instanceof Inet6Address) {
        sp = new SocketPermission("[" + hostAddress + "]:" + port, action);
    } else {
        sp = new SocketPermission(hostAddress + ":" + port, action);
    }

    String host = url.getHost();
    sp = new SocketPermission(host + ":" + port, action);

The full uncompressed form of an IPv6 literal address is also valid.

The port or portrange is optional. A port specification of the form "N-", where N is a port number, signifies all ports numbered N and above, while a specification of the form "-N" indicates all ports numbered N and below. The special port value 0 refers to the entire ephemeral port range. This is a fixed range of ports a system may use to allocate dynamic ports from. The actual range may be system dependent.

The possible ways to connect to the host are

 accept
 connect
 listen
 resolve

The "listen" action is only meaningful when used with "localhost" and means the ability to bind to a specified port. The "resolve" action is implied when any of the other actions are present. The action "resolve" refers to host/ip name service lookups.

The actions string is converted to lowercase before processing.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	SocketPermission.EphemeralRange

Field Summary

Modifier and Type	Field and Description
private static final int	ACCEPT Accept a connection from host:port
private String	actions the actions string.
private transient InetAddress[]	addresses
private static final int	ALL All actions
private transient String	cdomain
private transient String	cname
private static final int	CONNECT Connect to host:port
private static Debug	debug
private static boolean	debugInit
private transient boolean	defaultDeny
private transient String	hdomain
private transient String	hostname
private transient boolean	init_with_ip
private transient boolean	invalid
private static final int	LISTEN Listen on host:port
private transient int	mask
private static final int	NONE No actions
private static final int	PORT_MAX
private static final int	PORT_MIN
private transient int[]	portrange
private static final int	RESOLVE Resolve DNS queries
private static final long	serialVersionUID Hides java.security.Permission.serialVersionUID.
private transient boolean	trusted
private static final boolean	trustNameService
private transient boolean	untrusted
private transient boolean	wildcard

Constructor Summary

Access	Constructor and Description
public	SocketPermission(String the hostname or IP address of the computer, optionally including a colon followed by a port or port range. host, String the action string. action) Creates a new SocketPermission object with the specified actions.
pack-priv	SocketPermission(String host, int mask)

Method Summary

Modifier and Type	Method and Description
private boolean	authorized(byte[] addr)
private boolean	authorizedIPv4(byte[] addr)
private boolean	authorizedIPv6(byte[] addr)
private static String	checkForIDN(String name) previously we allowed domain names to be specified in IDN ACE form Need to check for that and convert to Unicode
private boolean	compareHostnames(SocketPermission that)
public boolean	Returns: true if obj is a SocketPermission, and has the same hostname, port range, and actions as this SocketPermission object. However, port range will be ignored in the comparison if obj only contains the action, 'resolve'. equals(Object the object to test for equality with this object. obj) Implements abstract java.security.Permission.equals. Checks two SocketPermission objects for equality.
private static String	Returns: the canonical string representation of the actions getActions(int a specific integer action mask to translate into a string mask) Returns the "canonical string representation" of the actions in the specified mask.
public String	Returns: the canonical string representation of the actions. getActions() Implements abstract java.security.Permission.getActions. Returns the canonical string representation of the actions.
pack-priv void	getCanonName() attempt to get the fully qualified domain name
private static synchronized Debug	getDebug()
private static String	getHost(String host)
pack-priv void	getIP() get IP addresses.
private static int	Returns: the action mask getMask(String the action string action) Convert an action string to an integer actions mask.
pack-priv int	Returns: the actions mask. getMask() Return the current action mask.
public int	Returns: a hash code value for this object. hashCode() Implements abstract java.security.Permission.hashCode. Returns the hash code value for this object.
public boolean	Returns: true if the specified permission is implied by this object, false if not. implies(Permission the permission to check against. p) Implements abstract java.security.Permission.implies. Checks if this socket permission object "implies" the specified permission.
pack-priv boolean	Returns: true if "permission" is a proper subset of the current object, false if not. impliesIgnoreMask(SocketPermission the incoming permission request that) Checks if the incoming Permission's action are a proper subset of this object's actions.
private boolean	includesEphemerals() Returns true if the permission has specified zero as its value (or lower bound) signifying the ephemeral range
private void	init(String host, int mask) Initialize the SocketPermission object.
private static int	initEphemeralPorts(String suffix) Check the system/security property for the ephemeral port range for this system.
private static boolean	inRange(int policyLow, int policyHigh, int targetLow, int targetHigh) Check if the target range is within the policy range together with the ephemeral range for this platform (if policy includes ephemeral range)
private boolean	isUntrusted()
private boolean	match(String cname, String hname)
public PermissionCollection	Returns: a new PermissionCollection object suitable for storing SocketPermissions. newPermissionCollection() Overrides java.security.Permission.newPermissionCollection. Returns a new PermissionCollection object for storing SocketPermission objects.
private int[]	parsePort(String port)
private synchronized void	readObject(ObjectInputStream the `ObjectInputStream` from which data is read s) `readObject` is called to restore the state of the `SocketPermission` from a stream.
private void	setDeny()
private synchronized void	writeObject(ObjectOutputStream the `ObjectOutputStream` to which data is written s) `writeObject` is called to save the state of the `SocketPermission` to a stream.

Inherited from java.security.Permission:: checkGuard getName toString

Field Detail

ACCEPT	back to summary
private static final int ACCEPT Accept a connection from host:port

actions	back to summary
private String actions the actions string.

addresses	back to summary
private transient InetAddress[] addresses

ALL	back to summary
private static final int ALL All actions

cdomain	back to summary
private transient String cdomain

cname	back to summary
private transient String cname

CONNECT	back to summary
private static final int CONNECT Connect to host:port

debug	back to summary
private static Debug debug

debugInit	back to summary
private static boolean debugInit

defaultDeny	back to summary
private transient boolean defaultDeny

hdomain	back to summary
private transient String hdomain

hostname	back to summary
private transient String hostname

init_with_ip	back to summary
private transient boolean init_with_ip

invalid	back to summary
private transient boolean invalid

LISTEN	back to summary
private static final int LISTEN Listen on host:port

mask	back to summary
private transient int mask

NONE	back to summary
private static final int NONE No actions

PORT_MAX	back to summary
private static final int PORT_MAX

PORT_MIN	back to summary
private static final int PORT_MIN

portrange	back to summary
private transient int[] portrange

RESOLVE	back to summary
private static final int RESOLVE Resolve DNS queries

serialVersionUID	back to summary
private static final long serialVersionUID Hides java.security.Permission.serialVersionUID. Annotations @Serial

trusted	back to summary
private transient boolean trusted

trustNameService	back to summary
private static final boolean trustNameService

untrusted	back to summary
private transient boolean untrusted

wildcard	back to summary
private transient boolean wildcard

Constructor Detail

SocketPermission back to summary

SocketPermission	back to summary
public SocketPermission(String host, String action) Creates a new SocketPermission object with the specified actions. The host is expressed as a DNS name, or as a numerical IP address. Optionally, a port or a portrange may be supplied (separated from the DNS name or IP address by a colon). To specify the local machine, use "localhost" as the host. Also note: An empty host String ("") is equivalent to "localhost". The actions parameter contains a comma-separated list of the actions granted for the specified host (and port(s)). Possible actions are "connect", "listen", "accept", "resolve", or any combination of those. "resolve" is automatically added when any of the other three are specified. Examples of SocketPermission instantiation are the following: nr = new SocketPermission("www.example.com", "connect"); nr = new SocketPermission("www.example.com:80", "connect"); nr = new SocketPermission(".example.com", "connect"); nr = new SocketPermission(".edu", "resolve"); nr = new SocketPermission("204.160.241.0", "connect"); nr = new SocketPermission("localhost:1024-65535", "listen"); nr = new SocketPermission("204.160.241.0:1024-65535", "connect"); Parameters host:String the hostname or IP address of the computer, optionally including a colon followed by a port or port range. action:String the action string. Exceptions NullPointerException: if any parameters are null IllegalArgumentException: if the format of `host` is invalid, or if the `action` string is empty, malformed, or contains an action other than the specified possible actions

public SocketPermission(String host, String action)

Creates a new SocketPermission object with the specified actions. The host is expressed as a DNS name, or as a numerical IP address. Optionally, a port or a portrange may be supplied (separated from the DNS name or IP address by a colon).

To specify the local machine, use "localhost" as the host. Also note: An empty host String ("") is equivalent to "localhost".

The actions parameter contains a comma-separated list of the actions granted for the specified host (and port(s)). Possible actions are "connect", "listen", "accept", "resolve", or any combination of those. "resolve" is automatically added when any of the other three are specified.

Examples of SocketPermission instantiation are the following:

   nr = new SocketPermission("www.example.com", "connect");
   nr = new SocketPermission("www.example.com:80", "connect");
   nr = new SocketPermission("*.example.com", "connect");
   nr = new SocketPermission("*.edu", "resolve");
   nr = new SocketPermission("204.160.241.0", "connect");
   nr = new SocketPermission("localhost:1024-65535", "listen");
   nr = new SocketPermission("204.160.241.0:1024-65535", "connect");

Parameters

host:String: the hostname or IP address of the computer, optionally including a colon followed by a port or port range.
action:String: the action string.

Exceptions

NullPointerException:: if any parameters are null
IllegalArgumentException:: if the format of host is invalid, or if the action string is empty, malformed, or contains an action other than the specified possible actions

SocketPermission	back to summary
pack-priv SocketPermission(String host, int mask)

Method Detail

authorized	back to summary
private boolean authorized(byte[] addr)

authorizedIPv4	back to summary
private boolean authorizedIPv4(byte[] addr)

authorizedIPv6	back to summary
private boolean authorizedIPv6(byte[] addr)

checkForIDN	back to summary
private static String checkForIDN(String name) previously we allowed domain names to be specified in IDN ACE form Need to check for that and convert to Unicode

compareHostnames	back to summary
private boolean compareHostnames(SocketPermission that)

equals	back to summary
public boolean equals(Object obj) Implements abstract java.security.Permission.equals. Checks two SocketPermission objects for equality. Parameters obj:Object the object to test for equality with this object. Returns:boolean true if obj is a SocketPermission, and has the same hostname, port range, and actions as this SocketPermission object. However, port range will be ignored in the comparison if obj only contains the action, 'resolve'. Annotations @Override

equals

back to summary

public boolean equals(Object obj)

Implements abstract java.security.Permission.equals.

Checks two SocketPermission objects for equality.

Parameters

obj:Object: the object to test for equality with this object.

Returns:boolean

true if obj is a SocketPermission, and has the same hostname, port range, and actions as this SocketPermission object. However, port range will be ignored in the comparison if obj only contains the action, 'resolve'.

Annotations

@Override

getActions	back to summary
private static String getActions(int mask) Returns the "canonical string representation" of the actions in the specified mask. Always returns present actions in the following order: connect, listen, accept, resolve. Parameters mask:int a specific integer action mask to translate into a string Returns:String the canonical string representation of the actions

getActions

back to summary

private static String getActions(int mask)

Returns the "canonical string representation" of the actions in the specified mask. Always returns present actions in the following order: connect, listen, accept, resolve.

Parameters

mask:int: a specific integer action mask to translate into a string

Returns:String

the canonical string representation of the actions

getActions	back to summary
public String getActions() Implements abstract java.security.Permission.getActions. Returns the canonical string representation of the actions. Always returns present actions in the following order: connect, listen, accept, resolve. Returns:String the canonical string representation of the actions. Annotations @Override

getActions

back to summary

public String getActions()

Implements abstract java.security.Permission.getActions.

Returns the canonical string representation of the actions. Always returns present actions in the following order: connect, listen, accept, resolve.

Returns:String

the canonical string representation of the actions.

Annotations

@Override

getCanonName	back to summary
pack-priv void getCanonName() throws UnknownHostException attempt to get the fully qualified domain name

getDebug	back to summary
private static synchronized Debug getDebug()

getHost	back to summary
private static String getHost(String host)

getIP	back to summary
pack-priv void getIP() throws UnknownHostException get IP addresses. Sets invalid to true if we can't get them.

getMask	back to summary
private static int getMask(String action) Convert an action string to an integer actions mask. Parameters action:String the action string Returns:int the action mask

getMask

back to summary

private static int getMask(String action)

Convert an action string to an integer actions mask.

Parameters

action:String: the action string

Returns:int

the action mask

getMask	back to summary
pack-priv int getMask() Return the current action mask. Returns:int the actions mask.

getMask

back to summary

pack-priv int getMask()

Return the current action mask.

Returns:int: the actions mask.

hashCode	back to summary
public int hashCode() Implements abstract java.security.Permission.hashCode. Returns the hash code value for this object. Returns:int a hash code value for this object. Annotations @Override

hashCode

back to summary

public int hashCode()

Implements abstract java.security.Permission.hashCode.

Returns the hash code value for this object.

Returns:int

a hash code value for this object.

Annotations

@Override

implies back to summary

implies	back to summary
public boolean implies(Permission p) Implements abstract java.security.Permission.implies. Checks if this socket permission object "implies" the specified permission. More specifically, this method first ensures that all of the following are true (and returns false if any of them are not): p is an instanceof SocketPermission, p's actions are a proper subset of this object's actions, and p's port range is included in this port range. Note: port range is ignored when p only contains the action, 'resolve'. Then `implies` checks each of the following, in order, and for each returns true if the stated condition is true: If this object was initialized with a single IP address and one of p's IP addresses is equal to this object's IP address. If this object is a wildcard domain (such as .example.com), and p's canonical name (the name without any preceding ) ends with this object's canonical host name. For example, .example.com implies .foo.example.com. If this object was not initialized with a single IP address, and one of this object's IP addresses equals one of p's IP addresses. If this canonical name equals p's canonical name. If none of the above are true, `implies` returns false. Parameters p:Permission the permission to check against. Returns:boolean true if the specified permission is implied by this object, false if not. Annotations @Override

public boolean implies(Permission p)

Implements abstract java.security.Permission.implies.

Checks if this socket permission object "implies" the specified permission.

More specifically, this method first ensures that all of the following are true (and returns false if any of them are not):

p is an instanceof SocketPermission,
p's actions are a proper subset of this object's actions, and
p's port range is included in this port range. Note: port range is ignored when p only contains the action, 'resolve'.

Then implies checks each of the following, in order, and for each returns true if the stated condition is true:

If this object was initialized with a single IP address and one of p's IP addresses is equal to this object's IP address.
If this object is a wildcard domain (such as *.example.com), and p's canonical name (the name without any preceding *) ends with this object's canonical host name. For example, *.example.com implies *.foo.example.com.
If this object was not initialized with a single IP address, and one of this object's IP addresses equals one of p's IP addresses.
If this canonical name equals p's canonical name.

If none of the above are true, implies returns false.

Parameters

p:Permission: the permission to check against.

Returns:boolean

true if the specified permission is implied by this object, false if not.

Annotations

@Override

impliesIgnoreMask	back to summary
pack-priv boolean impliesIgnoreMask(SocketPermission that) Checks if the incoming Permission's action are a proper subset of this object's actions. Check, in the following order: Checks that "p" is an instanceof a SocketPermission Checks that "p"'s actions are a proper subset of the current object's actions. Checks that "p"'s port range is included in this port range If this object was initialized with an IP address, checks that one of "p"'s IP addresses is equal to this object's IP address. If either object is a wildcard domain (i.e., "*.example.com"), attempt to match based on the wildcard. If this object was not initialized with an IP address, attempt to find a match based on the IP addresses in both objects. Attempt to match on the canonical hostnames of both objects. Parameters that:SocketPermission the incoming permission request Returns:boolean true if "permission" is a proper subset of the current object, false if not.

impliesIgnoreMask

back to summary

pack-priv boolean impliesIgnoreMask(SocketPermission that)

Checks if the incoming Permission's action are a proper subset of this object's actions.

Check, in the following order:

Checks that "p" is an instanceof a SocketPermission
Checks that "p"'s actions are a proper subset of the current object's actions.
Checks that "p"'s port range is included in this port range
If this object was initialized with an IP address, checks that one of "p"'s IP addresses is equal to this object's IP address.
If either object is a wildcard domain (i.e., "*.example.com"), attempt to match based on the wildcard.
If this object was not initialized with an IP address, attempt to find a match based on the IP addresses in both objects.
Attempt to match on the canonical hostnames of both objects.

Parameters

that:SocketPermission: the incoming permission request

Returns:boolean

true if "permission" is a proper subset of the current object, false if not.

includesEphemerals	back to summary
private boolean includesEphemerals() Returns true if the permission has specified zero as its value (or lower bound) signifying the ephemeral range

init	back to summary
private void init(String host, int mask) Initialize the SocketPermission object. We don't do any DNS lookups as this point, instead we hold off until the implies method is called.

initEphemeralPorts	back to summary
private static int initEphemeralPorts(String suffix) Check the system/security property for the ephemeral port range for this system. The suffix is either "high" or "low"

inRange	back to summary
private static boolean inRange(int policyLow, int policyHigh, int targetLow, int targetHigh) Check if the target range is within the policy range together with the ephemeral range for this platform (if policy includes ephemeral range)

isUntrusted	back to summary
private boolean isUntrusted() throws UnknownHostException

match	back to summary
private boolean match(String cname, String hname)

newPermissionCollection back to summary

public PermissionCollection newPermissionCollection()

Overrides java.security.Permission.newPermissionCollection.

Returns a new PermissionCollection object for storing SocketPermission objects.

SocketPermission objects must be stored in a manner that allows them to be inserted into the collection in any order, but that also enables the PermissionCollection implies method to be implemented in an efficient (and consistent) manner.

Returns:PermissionCollection

a new PermissionCollection object suitable for storing SocketPermissions.

Annotations

@Override

parsePort	back to summary
private int[] parsePort(String port)

readObject back to summary

private synchronized void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

readObject is called to restore the state of the SocketPermission from a stream.

Parameters

s:ObjectInputStream: the ObjectInputStream from which data is read

Annotations

@Serial

Exceptions

IOException:: if an I/O error occurs
ClassNotFoundException:: if a serialized class cannot be loaded

setDeny	back to summary
private void setDeny()

writeObject back to summary

private synchronized void writeObject(ObjectOutputStream s) throws IOException

writeObject is called to save the state of the SocketPermission to a stream. The actions are serialized, and the superclass takes care of the name.

Parameters

s:ObjectOutputStream: the ObjectOutputStream to which data is written

Annotations

@Serial

Exceptions

IOException:: if an I/O error occurs

public final Class SocketPermission

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class SocketPermission.EphemeralRange

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail