ice4j/src/org/ice4j/ice/Agent.java

570 lines
19 KiB
Java

/*
* ice4j, the OpenSource Java Solution for NAT and Firewall Traversal.
* Maintained by the SIP Communicator community (http://sip-communicator.org).
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package org.ice4j.ice;
import java.io.*;
import java.math.*;
import java.net.*;
import java.security.*;
import java.util.*;
import java.util.logging.*;
import org.ice4j.*;
import org.ice4j.ice.harvest.*;
/**
* An IceAgent could be described as the main class (i.e. the chef d'orchestre)
* of an ICE implementation.
* <p>
* As defined in RFC 3264, an agent is the protocol implementation involved in
* the offer/answer exchange. There are two agents involved in an offer/answer
* exchange.
* <p>
*
* @author Emil Ivov
* @author Namal Senarathne
*/
public class Agent
{
/**
* Our class logger.
*/
private static final Logger logger
= Logger.getLogger(Agent.class.getName());
/**
* The default maximum size for check lists.
*/
public static final int DEFAULT_MAX_CHECK_LIST_SIZE = 100;
/**
* The LinkedHashMap used to store the media streams
* This map preserves the insertion order of the media streams.
*/
private Map<String, IceMediaStream> mediaStreams
= new LinkedHashMap<String, IceMediaStream>();
/**
* The candidate harvester that we use to gather candidate on the local
* machine.
*/
private final HostCandidateHarvester hostCandidateHarvester
= new HostCandidateHarvester();
/**
* The list of harvesters (i.e. STUN, TURN, and others) that the agent
* should use when gathering candidates for components.
*/
private final List<CandidateHarvester> harvesters
= new ArrayList<CandidateHarvester>();
/**
* We use the <tt>FoundationsRegistry</tt> to keep track of the foundations
* we assign within a session (i.e. the entire life time of an
* <tt>Agent</tt>)
*/
private FoundationsRegistry foundationsRegistry = new FoundationsRegistry();
/**
* The user fragment that we should use for the ice-ufrag attribute.
*/
private final String ufrag;
/**
* The password that we should use for the ice-pwd attribute.
*/
private final String password;
/**
* The user fragment that we received from the remote party.
*/
private String remoteUfrag;
/**
* The password that we received from the remote party.
*/
private String remotePassword;
/**
* The tie-breaker number is used in connectivity checks to detect and
* repair the case where both agents believe to have the controlling or the
* controlled role.
*/
private final long tieBreaker;
/**
* Determines whether this is the controlling agent in a an ICE interaction.
*/
private boolean isControlling = true;
/**
* Creates an empty <tt>Agent</tt> with no streams, and no address
*/
public Agent()
{
SecureRandom random = new SecureRandom();
ufrag = new BigInteger(24, random).toString(32);
password = new BigInteger(128, random).toString(32);
tieBreaker = Math.abs(random.nextLong());
System.setProperty(StackProperties.SOFTWARE, "ice4j.org");
System.setProperty(StackProperties.ALWAYS_SIGN, "true");
}
/**
* Creates a new media stream and stores it
*
* @param mediaStreamName the name of the media stream
*
* @return a reference to the newly created <tt>IceMediaStream</tt>.
*/
public IceMediaStream createMediaStream(String mediaStreamName)
{
IceMediaStream mediaStream
= new IceMediaStream(Agent.this, mediaStreamName);
mediaStreams.put(mediaStreamName, mediaStream);
return mediaStream;
}
/**
* Creates a new {@link Component} for the specified <tt>stream</tt> and
* allocates all local candidates that should belong to it.
*
* @param stream the {@link IceMediaStream} that the new {@link Component}
* should belong to.
* @param transport the transport protocol used by the component
* @param preferredPort the port number that should be tried first when
* binding local <tt>Candidate</tt> sockets for this <tt>Component</tt>.
* @param minPort the port number where we should first try to bind before
* moving to the next one (i.e. <tt>minPort + 1</tt>)
* @param maxPort the maximum port number where we should try binding
* before giving up and throwinG an exception.
*
* @return the newly created {@link Component} and with a list containing
* all and only local candidates.
*
* @throws IllegalArgumentException if either <tt>minPort</tt> or
* <tt>maxPort</tt> is not a valid port number or if <tt>minPort >
* maxPort</tt>, or if <tt>transport</tt> is not currently supported.
* @throws IOException if an error occurs while the underlying resolver lib
* is using sockets.
* @throws BindException if we couldn't find a free port between
* <tt>minPort</tt> and <tt>maxPort</tt> before reaching the maximum allowed
* number of retries.
*/
public Component createComponent( IceMediaStream stream,
Transport transport,
int preferredPort,
int minPort,
int maxPort)
throws IllegalArgumentException,
IOException,
BindException
{
if(transport != Transport.UDP)
throw new IllegalArgumentException("This implementation does not "
+" currently support transport: " + transport);
Component component = stream.createComponent(transport);
gatherCandidates(component, preferredPort, minPort, maxPort );
return component;
}
/**
* Uses all <tt>CandidateHarvester</tt>s currently registered with this
* <tt>Agent</tt> to obtain whatever addresses they can discover.
* <p>
* Not that the method would only use existing harvesters so make sure
* you've registered all harvesters that you would want to use before
* calling it.
* </p>
* @param component the <tt>Component</tt> that we'd like to gather
* candidates for.
* @param preferredPort the port number that should be tried first when
* binding local <tt>Candidate</tt> sockets for this <tt>Component</tt>.
* @param minPort the port number where we should first try to bind before
* moving to the next one (i.e. <tt>minPort + 1</tt>)
* @param maxPort the maximum port number where we should try binding
* before giving up and throwinG an exception.
*
* @throws IllegalArgumentException if either <tt>minPort</tt> or
* <tt>maxPort</tt> is not a valid port number or if <tt>minPort >
* maxPort</tt>.
* @throws IOException if an error occurs while the underlying resolver lib
* is gathering candidates and we end up without even a single one.
*/
private void gatherCandidates( Component component,
int preferredPort,
int minPort,
int maxPort)
throws IllegalArgumentException,
IOException
{
hostCandidateHarvester.harvest(
component, preferredPort, minPort, maxPort);
//apply other harvesters here:
//todo: run harvesters in a parallel manner
synchronized(harvesters)
{
for (CandidateHarvester h : harvesters )
{
h.harvest(component);
}
}
computeFoundations(component);
//make sure we compute priorities only after we have all candidates
component.prioritizeCandidates();
//eliminate redundant candidates
component.eliminateRedundantCandidates();
//select the candidate to put in the media line.
component.selectDefaultCandidate();
}
/**
* Initializes all stream check lists and begins the checks.
*/
public void startChecks()
{
initCheckLists();
List<IceMediaStream> streams = getStreams();
ConnectivityCheckDispatcher client
= new ConnectivityCheckDispatcher(this);
for(IceMediaStream stream : streams)
{
CheckList list = stream.getCheckList();
client.startChecks(list);
}
}
/**
* Creates, initializes and orders the list of candidate pairs that would
* be used for the connectivity checks for all components in this stream.
*/
protected void initCheckLists()
{
//first init the check list.
List<IceMediaStream> streams = getStreams();
//init the maximum number of check list entries per stream.
int maxCheckListSize = Integer.getInteger(
StackProperties.MAX_CHECK_LIST_SIZE,
DEFAULT_MAX_CHECK_LIST_SIZE);
int maxPerStreamSize = maxCheckListSize / streams.size();
for(IceMediaStream stream : streams)
{
stream.setMaxCheckListSize(maxPerStreamSize);
stream.initCheckList();
}
}
/**
* Computes and sets the foundations foundation for all <tt>Candidate</tt>s
* currently found in <tt>component</tt>.
*
* @param component the component whose candidate foundations we'd like to
* compute and assign.
*/
private void computeFoundations(Component component)
{
List<LocalCandidate> candidates = component.getLocalCandidates();
for (Candidate cand : candidates)
{
foundationsRegistry.assignFoundation(cand);
}
}
/**
* Adds <tt>harvester</tt> to the list of harvesters that this agent will
* use when gathering <tt>Candidate</tt>s.
*
* @param harvester a <tt>CandidateHarvester</tt> that this agent should use
* when gathering candidates.
*/
public void addCandidateHarvester(CandidateHarvester harvester)
{
synchronized(harvesters)
{
harvesters.add(harvester);
}
}
/**
* Returns that user name that should be advertised in session descriptions
* containing ICE data from this agent.
*
* @return that user name that should be advertised in session descriptions
* containing ICE data from this agent.
*/
public String getLocalUfrag()
{
return ufrag;
}
/**
* Returns that password that should be advertised in session descriptions
* containing ICE data from this agent.
*
* @return that password that should be advertised in session descriptions
* containing ICE data from this agent.
*/
public String getPassword()
{
return password;
}
/**
* Returns the user name that we received from the remote peer or
* <tt>null</tt> if we haven't received a user name from them yet.
*
* @return the user name that we received from the remote peer or
* <tt>null</tt> if we haven't received a user name from them yet.
*/
public String getRemoteUfrag()
{
return remoteUfrag;
}
/**
* Returns the password that we received from the remote peer or
* <tt>null</tt> if we haven't received a password from them yet.
*
* @return the password that we received from the remote peer or
* <tt>null</tt> if we haven't received a password from them yet.
*/
public String getRemotePassword()
{
return remotePassword;
}
/**
* Specifies the user name that we received from the remote peer.
*
* @param remoteUfrag the user name that we received from the remote peer.
*/
public void setRemoteUfrag(String remoteUfrag)
{
this.remoteUfrag = remoteUfrag;
}
/**
* Returns the user name that this <tt>Agent</tt> should use in connectivity
* checks for outgoing Binding Requests. According to RFC 5245, a Binding
* Request serving as a connectivity check MUST utilize the STUN short term
* credential mechanism. The username for the credential is formed by
* concatenating the username fragment provided by the peer with the
* username fragment of the agent sending the request, separated by a
* colon (":"). The password is equal to the password provided by the peer.
* For example, consider the case where agent L is the offerer, and agent R
* is the answerer. Agent L included a username fragment of LFRAG for its
* candidates, and a password of LPASS. Agent R provided a username
* fragment of RFRAG and a password of RPASS. A connectivity check from L
* to R (and its response of course) utilize the username RFRAG:LFRAG and a
* password of RPASS. A connectivity check from R to L (and its response)
* utilize the username LFRAG:RFRAG and a password of LPASS.
*
* @return a user name that this <tt>Agent</tt> can use in connectivity
* check for outgoing Binding Requests.
*/
public String generateLocalUserName()
{
return getRemoteUfrag() + ":" + getLocalUfrag();
}
/**
* Returns the user name that we should respect a peer <tt>Agent</tt> to use
* in connectivity checks for outgoing Binding Requests. According to RFC
* 5245, a Binding Request serving as a connectivity check MUST utilize the
* STUN short term credential mechanism. The username for the credential is
* formed by concatenating the username fragment provided by the peer with
* the username fragment of the agent sending the request, separated by a
* colon (":"). The password is equal to the password provided by the peer.
* For example, consider the case where agent L is the offerer, and agent R
* is the answerer. Agent L included a username fragment of LFRAG for its
* candidates, and a password of LPASS. Agent R provided a username
* fragment of RFRAG and a password of RPASS. A connectivity check from L
* to R (and its response of course) utilize the username RFRAG:LFRAG and a
* password of RPASS. A connectivity check from R to L (and its response)
* utilize the username LFRAG:RFRAG and a password of LPASS.
*
* @return a user name that a peer <tt>Agent</tt> would use in connectivity
* check for outgoing Binding Requests.
*/
public String generateRemoteUserName()
{
return getLocalUfrag() + ":" + getRemoteUfrag();
}
/**
* Specifies the password that we received from the remote peer.
*
* @param remotePassword the user name that we received from the remote
* peer.
*/
public void setRemotePassword(String remotePassword)
{
this.remotePassword = remotePassword;
}
/**
* Returns the <tt>IceMediaStream</tt> with the specified <tt>name</tt> or
* <tt>null</tt> if no such stream has been registered with this
* <tt>Agent</tt> yet.
*
* @param name the name of the stream that we'd like to obtain a reference
* to.
*
* @return the <tt>IceMediaStream</tt> with the specified <tt>name</tt> or
* <tt>null</tt> if no such stream has been registered with this
* <tt>Agent</tt> yet.
*/
public IceMediaStream getStream(String name)
{
synchronized(mediaStreams)
{
return mediaStreams.get(name);
}
}
/**
* Returns a <tt>List</tt> containing the names of all currently registered
* media streams.
*
* @return a <tt>List</tt> containing the names of all currently registered
* media streams.
*/
public List<String> getStreamNames()
{
synchronized(mediaStreams)
{
return new LinkedList<String>(mediaStreams.keySet());
}
}
/**
* Returns a <tt>List</tt> containing all <tt>IceMediaStream</tt>s currently
* registered with this agent.
*
* @return a <tt>List</tt> containing all <tt>IceMediaStream</tt>s currently
* registered with this agent.
*/
public List<IceMediaStream> getStreams()
{
synchronized(mediaStreams)
{
return new LinkedList<IceMediaStream>(mediaStreams.values());
}
}
/**
* Returns the number of <tt>IceMediaStream</tt>s currently registered with
* this agent.
*
* @return the number of <tt>IceMediaStream</tt>s currently registered with
* this agent.
*
*/
public int getStreamCount()
{
synchronized(mediaStreams)
{
return mediaStreams.size();
}
}
/**
* Returns a <tt>String</tt> representation of this agent.
*
* @return a <tt>String</tt> representation of this agent.
*/
@Override
public String toString()
{
StringBuffer buff = new StringBuffer("ICE Agent (stream-count=");
buff.append(getStreamCount()).append(" ice-pwd:").append(getPassword());
buff.append(getStreamCount()).append(" ice-ufrag:")
.append(getLocalUfrag());
buff.append(getStreamCount()).append(" tie-breaker:" + getTieBreaker());
buff.append("):\n");
List<IceMediaStream> streams = getStreams();
for(IceMediaStream stream : streams)
{
buff.append(stream.toString()).append("\n");
}
return buff.toString();
}
/**
* Returns this agent's tie-breaker number. The tie-breaker number is used
* in connectivity checks to detect and repair the case where both agents
* believe to have the controlling or the controlled role.
*
* @return this agent's tie-breaker number
*/
public long getTieBreaker()
{
return tieBreaker;
}
/**
* Specifies whether this agent has the controlling role in an ICE exchange.
*
* @param isControlling <tt>true</tt> if this is to be the controlling
* <tt>Agent</tt> and <tt>false</tt> otherwise.
*/
public void setControlling(boolean isControlling)
{
this.isControlling = isControlling;
}
/**
* Removes <tt>stream</tt> and all its child <tt>Component</tt>s and
* <tt>Candidate</tt>s from the this agent and releases all resources that
* they had allocated (like sockets for example)
*
* @param stream the <tt>Component</tt> we'd like to remove and free.
*/
public void removeStream(IceMediaStream stream)
{
synchronized (mediaStreams)
{
mediaStreams.remove(stream.getName());
stream.free();
}
}
/**
* Determines whether this agent has the controlling role in an ICE
* exchange.
*
* @return <tt>true</tt> if this is to be the controlling <tt>Agent</tt>
* and <tt>false</tt> otherwise.
*/
public boolean isControlling()
{
return isControlling;
}
}