org.ocap.hn.security

Class NetSecurityManager

java.lang.Object

org.ocap.hn.security.NetSecurityManager

public abstract class NetSecurityManager
extends Object

This class provides access to home network security capabilities including password handling. The passwords that can be handled are specific to each home network interface at the link layer. Upper layer (e.g. TLS) and Administrator passwords cannot be accessed using this class. When the network interface type returned by NetworkInterface.getType() is MOCA the implementation SHALL associate the getNetworkPassword and setNetworkPassword methods in this interface to the MoCA link layer password used for the network interface. When the network interface type returned by NetworkInterface.getType() is WIRELESS_ETHERNET the implementation SHALL associate the getNetworkPassword and setNetworkPassword in this interface to the link layer password, e.g. WEP, used for the network interface.

This class also permits privileged applications to register a handler to authorize home network activity.

See Also:

NetAuthorizationHandler, NetAuthorizationHandler2

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	NetSecurityManager() Protected constructor; not for application use.

Method Summary

Methods

Modifier and Type	Method and Description
void	disableMocaPrivacy(NetworkInterface networkInterface) Disables MoCA privacy.
void	enableMocaPrivacy(NetworkInterface networkInterface) Enables MoCa privacy.
static NetSecurityManager	getInstance() Get the network security manager.
String	getNetworkPassword(NetworkInterface networkInterface) Gets a network interface password.
boolean	queryTransaction(String actionName, InetAddress inetAddress, String macAddress, URL url, int activityID) Queries the implementation to determine if it has sent a transaction matching the parameters.
void	revokeAuthorization(int activityID) Revokes a session authorization granted by the authorization handler.
void	setAuthorizationHandler(NetAuthorizationHandler nah) Registers an authorization handler.
void	setAuthorizationHandler(NetAuthorizationHandler2 nah, String[] actionNames, boolean notifyTransportRequests) Registers an authorization handler.
void	setAuthorizationHandler(NetAuthorizationHandler nah, String[] actionNames, boolean notifyTransportRequests) Registers an authorization handler.
void	setNetworkPassword(NetworkInterface networkInterface, String password) Sets a network interface password.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NetSecurityManager

protected NetSecurityManager()

Protected constructor; not for application use.

Method Detail

getInstance

public static NetSecurityManager getInstance()

Get the network security manager.

getNetworkPassword

public String getNetworkPassword(NetworkInterface networkInterface)

Gets a network interface password.

Parameters:

networkInterface - The interface to get the password for.

Returns:

The value of the password requested, or 0 length String if no password is set for the interface. If the interface type is MoCA this method returns a string value equal to the corresponding mocaIfPassword MIB. In this case the password MAY have been set using means other than the setNetworkPassword method.

Throws:

UnsupportedOperationException - if a password cannot be retrieved for the network interface.

SecurityException - if the caller has not been granted MonitorAppPermission("handler.homenetwork").

setNetworkPassword

public void setNetworkPassword(NetworkInterface networkInterface,
                      String password)

Sets a network interface password. If the network interface type is MoCA then privacy must also be enabled for the password to have affect. See the enableMocaPrivacy method. If the interface type is MoCA and the parameter is acceptable this method writes the corresponding mocaIfPassword MIB.

Parameters:

networkInterface - The home network interface the password is to be set for.

password - The value of the password to set.

Throws:

IllegalArgumentException - if the password format is invalid for the interface type. A password for a MoCA interface that is less than 12 characters or greater than 17 characters or has any non-numerical characters is invalid.

UnsupportedOperationException - if a password cannot be set for the network interface.

SecurityException - if the caller has not been granted MonitorAppPermission("handler.homenetwork").

setAuthorizationHandler

public void setAuthorizationHandler(NetAuthorizationHandler nah)

Registers an authorization handler. If a handler is already registered (whether a NetAuthorizationHandler or NetAuthorizationHandler2) this method SHALL replace it. If the nah parameter is null, any previously registered handler is removed.

A call to this method is equivalent to calling setAuthorizationHandler(nah, actionNames, true), where actionNames is an empty array.

Parameters:

nah - The network authorization handler to register.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("handler.homenetwork").

See Also:

setAuthorizationHandler(NetAuthorizationHandler, String[], boolean)

setAuthorizationHandler

public void setAuthorizationHandler(NetAuthorizationHandler nah,
                           String[] actionNames,
                           boolean notifyTransportRequests)

Registers an authorization handler. If a handler is already registered (whether a NetAuthorizationHandler or NetAuthorizationHandler2) this method SHALL replace it. If the nah parameter is null, any previously registered handler is removed.

The actionNames parameter permits the caller to specify an array of names indicating the actions that the handler wishes to authorize; an empty array indicates that NetAuthorizationHandler.notifyAction(java.lang.String, java.net.InetAddress, java.lang.String, int) will not be called.

The notifyTransportRequests parameter permits the caller to control whether NetAuthorizationHandler.notifyActivityStart(java.net.InetAddress, java.lang.String, java.net.URL, int) is called for every transport protocol (e.g., HTTP, RTP/RTSP) request in the session or only the initial one.

Parameters:

nah - The network authorization handler to register.

actionNames - An array of action names the hander is interested in authorizing. The format of the names is out-of-scope for this definition.

notifyTransportRequests - If true, NetAuthorizationHandler.notifyActivityStart(java.net.InetAddress, java.lang.String, java.net.URL, int) is always called when a transport protocol message is received; if false, NetAuthorizationHandler.notifyActivityStart(java.net.InetAddress, java.lang.String, java.net.URL, int) is only called for the first message in a session.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("handler.homenetwork").

IllegalArgumentException - if the actionNames parameter contains a name that cannot be matched to a known action.

setAuthorizationHandler

public void setAuthorizationHandler(NetAuthorizationHandler2 nah,
                           String[] actionNames,
                           boolean notifyTransportRequests)

Registers an authorization handler. This method takes a NetAuthorizationHander2 parameter which provides additional information about the activity to the notify methods. If a handler is already registered (whether a NetAuthorizationHandler or NetAuthorizationHandler2) this method SHALL replace it. If the nah parameter is null, any previously registered handler is removed.

The actionNames parameter permits the caller to specify an array of names indicating the actions that the handler wishes to authorize; an empty array indicates that NetAuthorizationHandler2.notifyAction(java.lang.String, java.net.InetAddress, int, java.lang.String[], org.ocap.hn.NetworkInterface) will not be called.

The notifyTransportRequests parameter permits the caller to control whether NetAuthorizationHandler2.notifyActivityStart(java.net.InetAddress, java.net.URL, int, org.ocap.hn.content.ContentEntry, java.lang.String[], org.ocap.hn.NetworkInterface) is called for every transport protocol (e.g., HTTP, RTP/RTSP) request in the session or only the initial one.

Parameters:

nah - The network authorization handler to register.

actionNames - An array of action names the hander is interested in authorizing. The format of the names is out-of-scope for this definition.

notifyTransportRequests - If true, NetAuthorizationHandler2.notifyActivityStart(java.net.InetAddress, java.net.URL, int, org.ocap.hn.content.ContentEntry, java.lang.String[], org.ocap.hn.NetworkInterface) is always called when a transport protocol message is received; if false, NetAuthorizationHandler2.notifyActivityStart(java.net.InetAddress, java.net.URL, int, org.ocap.hn.content.ContentEntry, java.lang.String[], org.ocap.hn.NetworkInterface) is only called for the first message in a session.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("handler.homenetwork").

IllegalArgumentException - if the actionNames parameter contains a name that cannot be matched to a known action.

revokeAuthorization

public void revokeAuthorization(int activityID)

Revokes a session authorization granted by the authorization handler.

Parameters:

activityID - The activity identifier that was passed to the authorization handler's notifyActivityStart method.

Throws:

SecurityException - if the caller does not have MonitorAppPermission("handler.homenetwork").

queryTransaction

public boolean queryTransaction(String actionName,
                       InetAddress inetAddress,
                       String macAddress,
                       URL url,
                       int activityID)

Queries the implementation to determine if it has sent a transaction matching the parameters.

Parameters:

actionName - Name of the request type if known. If not known an empty string MAY be used. The format of the name is out-of-scope of this definition.

inetAddress - IP address the transaction was sent to.

macAddress - MAC address the transaction was sent from if known. Can be empty String if not known. The format is EUI-48 with 6 colon separated 2 digit bytes in hexadecimal notation with no leading "0x", e.g. "00:11:22:AA:BB:CC".

url - The URL requested by the transaction if known. If not known an empty string may be used.

activityID - The activity identifier this device set for the connection. A value of -1 indicates the parameter will not be used for transaction matching purposes.

Returns:

True if activityID and other known parameters can be matched to a transaction sent by the implementation. If activityID match cannot be found, or if activityID match is found but any of the other known parameters do not match the transaction then this method returns false.

Throws:

IllegalArgumentException - if the MAC address is malformed.

SecurityException - if the caller does not have MonitorAppPermission("handler.homenetwork").

enableMocaPrivacy

public void enableMocaPrivacy(NetworkInterface networkInterface)

Enables MoCa privacy. For MoCA interface types this method enables privacy and writes the corresponding mocaIfPrivacyEnable MIB with a value of 'true'.

Parameters:

networkInterface - Interface to enable privacy on.

Throws:

UnsupportedOperationException - if the parameter interface is not a MoCA interface type.

SecurityException - if the caller has not been granted MonitorAppPermission("handler.homenetwork").

disableMocaPrivacy

public void disableMocaPrivacy(NetworkInterface networkInterface)

Disables MoCA privacy. For MoCA interface types this method disables privacy and writes the corresponding mocaIfPrivacyEnable MIB with a value of'false'.

Parameters:

networkInterface - Interface to disable privacy on.

Throws:

UnsupportedOperationException - if the parameter interface is not a MoCA interface type.

SecurityException - if the caller has not been granted MonitorAppPermission("handler.homenetwork").