From 995122b3207442290e2c081ea020ca1fd718a592 Mon Sep 17 00:00:00 2001 From: "lubomir.marinov" Date: Fri, 26 Feb 2010 12:39:15 +0000 Subject: [PATCH] Extracts abstract STUN-related CandidateHarvester and DatagramPacketFilter for the purposes of TURN. --- .../AbstractStunCandidateHarvester.java | 376 ++++++++++++++++++ .../ice/harvest/StunCandidateHarvester.java | 262 ++---------- .../AbstractStunDatagramPacketFilter.java | 73 ++++ .../socket/StunDatagramPacketFilter.java | 48 +-- 4 files changed, 511 insertions(+), 248 deletions(-) create mode 100644 src/org/ice4j/ice/harvest/AbstractStunCandidateHarvester.java create mode 100644 src/org/ice4j/socket/AbstractStunDatagramPacketFilter.java diff --git a/src/org/ice4j/ice/harvest/AbstractStunCandidateHarvester.java b/src/org/ice4j/ice/harvest/AbstractStunCandidateHarvester.java new file mode 100644 index 0000000..788010e --- /dev/null +++ b/src/org/ice4j/ice/harvest/AbstractStunCandidateHarvester.java @@ -0,0 +1,376 @@ +/* + * 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.harvest; + +import java.net.*; +import java.util.*; +import java.util.logging.*; + +import org.ice4j.*; +import org.ice4j.attribute.*; +import org.ice4j.ice.*; +import org.ice4j.message.*; +import org.ice4j.socket.*; +import org.ice4j.stack.*; + +/** + * Implements a CandidateHarvester which gathers Candidates + * for a specified {@link Component} using STUN and/or its extensions. + * + * @author Emil Ivov + * @author Lubomir Marinov + */ +public abstract class AbstractStunCandidateHarvester + implements CandidateHarvester, + ResponseCollector +{ + + /** + * The Logger used by the AbstractStunCandidateHarvester + * class and its instances for logging output. + */ + private static final Logger logger + = Logger.getLogger(AbstractStunCandidateHarvester.class.getName()); + + /** + * The list of candidates that we are currently resolving. + */ + private final Map resolveMap + = new Hashtable(); + + /** + * The address of the STUN server that we will be sending our requests to. + */ + protected final TransportAddress stunServer; + + /** + * The stack to use for STUN communication. + */ + private final StunStack stunStack = StunStack.getInstance(); + + /** + * Creates a new STUN harvester that will be running against the specified + * stunServer. + * + * @param stunServer the address of the STUN server that we will be querying + * for our public bindings + */ + public AbstractStunCandidateHarvester(TransportAddress stunServer) + { + this.stunServer = stunServer; + + //these should be configurable. + System.setProperty("org.ice4j.MAX_WAIT_INTERVAL", "400"); + System.setProperty("org.ice4j.MAX_RETRANSMISSIONS", "2"); + } + + /** + * Creates a new Candidate determined by a specific STUN response + * and with a specific HostCandidate base. + * + * @param responseEvent a StunMessageEvent which represents the + * STUN response which has been received + * @param localCand the HostCandidate for which harvesting is + * executing, the STUN response is associated with and which is to be the + * base of the newly created Candidate + */ + protected void createCandidate( + StunMessageEvent responseEvent, + HostCandidate localCand) + { + createServerReflexiveCandidate(responseEvent.getMessage(), localCand); + } + + /** + * Creates a new Request which is to be sent to {@link #stunServer} + * in order to start resolving a specific HostCandidate. + * + * @param hostCand the HostCandidate for which a Request + * to start resolving is to be created + * @return a new Request which is to be sent to {@link #stunServer} + * in order to start resolving the specified HostCandidate + */ + protected abstract Request createRequestToStartResolvingCandidate( + HostCandidate hostCand); + + /** + * Creates a ServerReflexiveCandidate using base as its + * and the XOR-MAPPED-ADDRESS attributes in response for + * the actual TransportAddress of the new candidate. If the message + * is somehow malformed and does not contain the corresponding attribute + * this method simply has no effect. + * + * @param response the Message that is supposed to contain the + * address we should use for this candidate. + * @param base the HostCandidate that we should use as a base + * for the new ServerReflexiveCandidate. + */ + protected void createServerReflexiveCandidate(Message response, + HostCandidate base) + { + Attribute attribute + = response.getAttribute(Attribute.XOR_MAPPED_ADDRESS); + + if(attribute instanceof XorMappedAddressAttribute) + { + TransportAddress addr + = ((XorMappedAddressAttribute) attribute) + .getAddress(response.getTransactionID()); + ServerReflexiveCandidate srvrRflxCand + = createServerReflexiveCandidate(addr, base); + + if (srvrRflxCand != null) + base.getParentComponent().addLocalCandidate(srvrRflxCand); + } + } + + /** + * Creates a new ServerReflexiveCandidate instance which is to + * represent a specific TransportAddress harvested through a + * specific HostCandidate and the STUN server associated with this + * instance. + * + * @param transportAddress the TransportAddress to be represented + * by the new ServerReflexiveCandidate instance + * @param base the HostCandidate through which the specified + * TransportAddress has been harvested + * @return a new ServerReflexiveCandidate instance which represents + * the specified TransportAddress harvested through the specified + * HostCandidate and the STUN server associated with this instance + */ + protected ServerReflexiveCandidate createServerReflexiveCandidate( + TransportAddress transportAddress, + HostCandidate base) + { + return new ServerReflexiveCandidate(transportAddress, base, stunServer); + } + + /** + * Gets the DatagramPacketFilter which is to be associated with the + * DatagramSocket to be used for communication with + * {@link #stunServer} when gathering Candidates for a specific + * HostCandidate. + * + * @param hostCand the HostCandidate for which STUN + * Candidates are to be harvested by this CandidateHarvester + * @return the DatagramPacketFilter which is to be associated with + * the DatagramSocket to be used for communication with + * {@link #stunServer} when gathering Candidates for the specified + * HostCandidate + */ + protected abstract DatagramPacketFilter getStunDatagramPacketFilter( + HostCandidate hostCand); + + /** + * Gets the DatagramSocket to be used by this + * CandidateHarvester for STUN communication for the purposes of + * harvesting STUN Candidates for a specific + * HostCandidate. + * + * @param hostCand the HostCandidate for which STUN + * Candidates are to be harvested by this + * CandidateHarvester + * @return the DatagramSocket to be used by this + * CandidateHarvester for STUN communication for the purposes of + * harvesting STUN Candidates for the specified + * HostCandidate + */ + private DatagramSocket getStunSocket(HostCandidate hostCand) + { + DatagramSocket hostSocket = hostCand.getSocket(); + DatagramSocket stunSocket = null; + Throwable exception = null; + + if (hostSocket instanceof MultiplexingDatagramSocket) + try + { + stunSocket + = ((MultiplexingDatagramSocket) hostSocket) + .getSocket(getStunDatagramPacketFilter(hostCand)); + } + catch (SocketException sex) + { + logger.log( + Level.SEVERE, + "Failed to acquire DatagramSocket" + + " specific to STUN communication.", + sex); + exception = sex; + } + if (stunSocket == null) + throw new IllegalArgumentException("hostCand", exception); + else + return stunSocket; + } + + /** + * Gathers STUN candidates for all host Candidates that are already + * present in the specified component. This method relies on the + * specified component to already contain all its host candidates + * so that it would resolve them. + * + * @param component the {@link Component} that we'd like to gather candidate + * STUN Candidates for. + */ + public void harvest(Component component) + { + for (Candidate cand : component.getLocalCandidates()) + if (cand instanceof HostCandidate) + { + HostCandidate hostCand = (HostCandidate) cand; + + startResolvingCandidate(hostCand); + } + + waitForResolutionEnd(); + } + + /** + * Removes the corresponding local candidate from the list of candidates + * that we are waiting on in order to complete the harvest. + * + * @param transactionID the ID of the transaction that has just ended. + */ + private void processFailure(TransactionID transactionID) + { + synchronized (resolveMap) + { + Candidate localCand = resolveMap.remove(transactionID); + + //if this was the last candidate, we are done with the STUN + //resolution and need to notify the waiters. + if(resolveMap.isEmpty()) + resolveMap.notify(); + + logger.finest("a tran expired tranid=" + transactionID); + logger.finest("localAddr=" + localCand); + } + } + + /** + * Matches the response to one of the local candidates and creates a + * ServerReflexiveCandidate using it as a base. + * + * @param response the response that we've just received from a StunServer. + */ + public void processResponse(StunMessageEvent response) + { + synchronized (resolveMap) + { + TransactionID tranID = response.getTransactionID(); + HostCandidate localCand = resolveMap.remove(tranID); + + if (localCand != null) + createCandidate(response, localCand); + + //if this was the last candidate, we are done with the STUN + //resolution and need to notify the waiters. + if (resolveMap.isEmpty()) + resolveMap.notify(); + + logger.finest("received a message tranid=" + tranID); + logger.finest("localCand=" + localCand); + } + } + + /** + * Notifies the collector that no response had been received + * after repeated retransmissions of the original request (as described + * by rfc3489) and that the request should be considered unanswered. + * + * @param event the StunTimeoutEvent that contains the transaction + * which has just expired. + */ + public void processTimeout(StunTimeoutEvent event) + { + processFailure(event.getTransactionID()); + } + + /** + * Called when one of our requests results in a + * PortUnreachableException ... which is actually quite rare + * because of the oddities of the BSD and Java socket implementations, which + * is why we currently ignore this method. + * + * @param event the StunFailureEvent containing the + * PortUnreachableException which signaled that the destination of + * the request was found to be unreachable. + */ + public void processUnreachable(StunFailureEvent event) + { + processFailure(event.getTransactionID()); + } + + /** + * Sends a binding request to our stun server through the specified + * hostCand candidate and adds it to the list of addresses still + * waiting for resolution. + * + * @param hostCand the HostCandidate that we'd like to resolve. + */ + private void startResolvingCandidate(HostCandidate hostCand) + { + //first of all, make sure that the STUN server and the Candidate + //address are of the same type and that they can communicate. + if (!hostCand.getTransportAddress().canReach(stunServer)) + return; + + DatagramSocket socket = getStunSocket(hostCand); + + stunStack.addSocket(socket); + + synchronized(resolveMap) + { + Request request = createRequestToStartResolvingCandidate(hostCand); + TransactionID tran; + + try + { + tran = stunStack.sendRequest(request, stunServer, socket, this); + } + catch (Exception exception) + { + logger.log( + Level.INFO, + "Failed to send " + + request + + " through " + socket.getLocalSocketAddress(), + exception); + return; + } + + resolveMap.put(tran, hostCand); + } + } + + /** + * Blocks the current thread until all resolutions in this harvester + * have terminated one way or another. + */ + private void waitForResolutionEnd() + { + synchronized(resolveMap) + { + boolean interrupted = false; + + // Handle spurious wakeups. + while (!resolveMap.isEmpty()) + try + { + resolveMap.wait(); + } + catch (InterruptedException iex) + { + interrupted = true; + } + // Restore the interrupted status. + if (interrupted) + Thread.currentThread().interrupt(); + } + } +} diff --git a/src/org/ice4j/ice/harvest/StunCandidateHarvester.java b/src/org/ice4j/ice/harvest/StunCandidateHarvester.java index 5f6c829..120e6e1 100644 --- a/src/org/ice4j/ice/harvest/StunCandidateHarvester.java +++ b/src/org/ice4j/ice/harvest/StunCandidateHarvester.java @@ -7,47 +7,30 @@ */ package org.ice4j.ice.harvest; -import java.net.*; -import java.util.*; -import java.util.logging.*; - import org.ice4j.*; -import org.ice4j.attribute.*; import org.ice4j.ice.*; import org.ice4j.message.*; -import org.ice4j.stack.*; +import org.ice4j.socket.*; /** - * A StunCandidateHarvester gathers STUN Candidates for a - * specified {@link Component}. + * Implements a CandidateHarvester which gathers Candidates + * for a specified {@link Component} using STUN as defined in RFC 5389 "Session + * Traversal Utilities for NAT (STUN)" only. * * @author Emil Ivov + * @author Lubomir Marinov */ public class StunCandidateHarvester - implements CandidateHarvester, - ResponseCollector + extends AbstractStunCandidateHarvester { - /** - * Our class logger. - */ - private final Logger logger - = Logger.getLogger(StunCandidateHarvester.class.getName()); /** - * The stack to use for STUN communication. + * The DatagramPacketFilter which accepts only STUN messages + * defined in RFC 5389 "Session Traversal Utilities for NAT (STUN)" i.e. the + * STUN messages of interest to StunCandidateHarvester. */ - private final StunStack stunStack; - - /** - * The address of the STUN server that we will be sending our requests to. - */ - private final TransportAddress stunServer; - - /** - * The list of candidates that we are currently resolving. - */ - private final Map resolveMap - = new Hashtable(); + private static final StunDatagramPacketFilter stunDatagramPacketFilter + = new StunDatagramPacketFilter(); /** * Creates a new STUN harvester that will be running against the specified @@ -58,213 +41,44 @@ public class StunCandidateHarvester */ public StunCandidateHarvester(TransportAddress stunServer) { - stunStack = StunStack.getInstance(); - this.stunServer = stunServer; - - //these should be configurable. - System.setProperty("org.ice4j.MAX_WAIT_INTERVAL", "400"); - System.setProperty("org.ice4j.MAX_RETRANSMISSIONS", "2"); + super(stunServer); } /** - * Gathers STUN candidates for all host Candidates that are already - * present in the specified component. This method relies on the - * specified component to already contain all its host candidates - * so that it would resolve them. + * Creates a new Request which is to be sent to {@link #stunServer} + * in order to start resolving a specific HostCandidate. * - * @param component the {@link Component} that we'd like to gather candidate - * STUN Candidates for. + * @param hostCand the HostCandidate for which a Request + * to start resolving is to be created + * @return a new Request which is to be sent to {@link #stunServer} + * in order to start resolving the specified HostCandidate + * @see AbstractStunCandidateHarvester + * #createRequestToStartResolvingCandidate(HostCandidate) */ - public void harvest(Component component) + protected Request createRequestToStartResolvingCandidate( + HostCandidate hostCand) { - List localCandidates = component.getLocalCandidates(); - - for(Candidate cand : localCandidates) - { - if ( !(cand instanceof HostCandidate) ) - continue; - - HostCandidate hostCand = (HostCandidate)cand; - - startResolvingCandidate(hostCand); - } - - waitForResolutionEnd(); + return MessageFactory.createBindingRequest(); } /** - * Sends a binding request to our stun server through the specified - * hostCand candidate and adds it to the list of addresses still - * waiting for resolution. + * Gets the DatagramPacketFilter which is to be associated with the + * DatagramSocket to be used for communication with + * {@link #stunServer} when gathering Candidates for a specific + * HostCandidate. * - * @param hostCand the HostCandidate that we'd like to resolve. + * @param hostCand the HostCandidate for which STUN + * Candidates are to be harvested by this CandidateHarvester + * @return the DatagramPacketFilter which is to be associated with + * the DatagramSocket to be used for communication with + * {@link #stunServer} when gathering Candidates for the specified + * HostCandidate + * @see AbstractStunCandidateHarvester#getStunDatagramPacketFilter( + * HostCandidate) */ - private void startResolvingCandidate(HostCandidate hostCand) + protected DatagramPacketFilter getStunDatagramPacketFilter( + HostCandidate hostCand) { - //first of all, make sure that the STUN server and the Candidate - //address are of the same type and that they can communicate. - if(!hostCand.getTransportAddress().canReach(stunServer)) - return; - - DatagramSocket sock = hostCand.getSocket(); - stunStack.addSocket(sock); - - synchronized(resolveMap) - { - TransactionID tran; - try - { - tran = stunStack.sendRequest( - MessageFactory.createBindingRequest(), stunServer, sock, - this); - - } - catch (Exception exception) - { - logger.log(Level.INFO, "Failed to send a STUN Binding Request", - exception); - return; - } - - resolveMap.put(tran, hostCand); - } + return stunDatagramPacketFilter; } - - /** - * Blocks the current thread until all resolutions in this harvester - * have terminated one way or another. - */ - private void waitForResolutionEnd() - { - synchronized(resolveMap) - { - boolean interrupted = false; - - // Handle spurious wakeups. - while (!resolveMap.isEmpty()) - try - { - resolveMap.wait(); - } - catch (InterruptedException iex) - { - interrupted = true; - } - // Restore the interrupted status. - if (interrupted) - Thread.currentThread().interrupt(); - } - } - - /** - * Matches the response to one of the local candidates and creates a - * ServerReflexiveCandidate using it as a base. - * - * @param response the response that we've just received from a StunServer. - */ - public void processResponse(StunMessageEvent response) - { - synchronized (resolveMap) - { - TransactionID tranID = response.getTransactionID(); - - HostCandidate localCand = resolveMap.remove(tranID); - - if ( localCand != null) - { - createServerReflexiveCandidate(response.getMessage(), - localCand); - } - - //if this was the last candidate, we are done with the STUN - //resolution and need to notify the waiters. - if(resolveMap.isEmpty()) - resolveMap.notify(); - - logger.finest("received a message tranid=" + tranID); - logger.finest("localCand=" + localCand); - } - } - - /** - * Notifies the collector that no response had been received - * after repeated retransmissions of the original request (as described - * by rfc3489) and that the request should be considered unanswered. - * - * @param event the StunTimeoutEvent that contains the transaction - * which has just expired. - */ - public void processTimeout(StunTimeoutEvent event) - { - processFailure(event.getTransactionID()); - } - - /** - * Called when one of our requests results in a - * PortUnreachableException ... which is actually quite rare - * because of the oddities of the BSD and Java socket implementations, which - * is why we currently ignore this method. - * - * @param event the StunFailureEvent containg the - * PortUnreachableException which signaled that the destination of - * the request was found to be unreachable. - */ - public void processUnreachable(StunFailureEvent event) - { - processFailure(event.getTransactionID()); - } - - /** - * Removes the corresponding local candidate from the list of candidates - * that we are waiting on in order to complete the harvest. - * - * @param transactionID the ID of the transaction that has just ended. - */ - private void processFailure(TransactionID transactionID) - { - synchronized (resolveMap) - { - Candidate localCand = resolveMap.remove(transactionID); - - //if this was the last candidate, we are done with the STUN - //resolution and need to notify the waiters. - if(resolveMap.isEmpty()) - resolveMap.notify(); - - logger.finest("a tran expired tranid=" + transactionID); - logger.finest("localAddr=" + localCand); - } - } - - /** - * Creates a ServerReflexiveCandidate using base as its - * and the XOR-MAPPED-ADDRESS attributes in response for - * the actual TransportAddress of the new candidate. If the message - * is somehow malformed and does not contain the corresponding attribute - * this method simply has no effect. - * - * @param response the Message that is supposed to contain the - * address we should use for this candidate. - * @param base the HostCandidate that we should use as a base - * for the new ServerReflexiveCandidate. - */ - private void createServerReflexiveCandidate(Message response, - HostCandidate base) - { - Attribute attribute - = response.getAttribute(Attribute.XOR_MAPPED_ADDRESS); - - if(!(attribute instanceof XorMappedAddressAttribute)) - return; - - TransportAddress addr = ((XorMappedAddressAttribute)attribute) - .getAddress(response.getTransactionID()); - - ServerReflexiveCandidate srvrRflxCand - = new ServerReflexiveCandidate(addr, base, stunServer); - - base.getParentComponent().addLocalCandidate(srvrRflxCand); - } - - } diff --git a/src/org/ice4j/socket/AbstractStunDatagramPacketFilter.java b/src/org/ice4j/socket/AbstractStunDatagramPacketFilter.java new file mode 100644 index 0000000..30b9403 --- /dev/null +++ b/src/org/ice4j/socket/AbstractStunDatagramPacketFilter.java @@ -0,0 +1,73 @@ +/* + * 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.socket; + +import java.net.*; + +/** + * Implements a DatagramPacketFilter which only accepts + * DatagramPackets which represent STUN messages. + * + * @author Lubomir Marinov + */ +public abstract class AbstractStunDatagramPacketFilter + implements DatagramPacketFilter +{ + + /** + * Determines whether a specific DatagramPacket represents a STUN + * message. + * + * @param p the DatagramPacket which is to be checked whether it is + * a STUN message + * @return true if p represents a STUN message; otherwise, + * false + */ + public boolean accept(DatagramPacket p) + { + /* + * All STUN messages MUST start with a 20-byte header followed by zero + * or more Attributes. + */ + if (p.getLength() >= 20) + { + /* + * The most significant 2 bits of every STUN message MUST be zeroes. + * This can be used to differentiate STUN packets from other + * protocols when STUN is multiplexed with other protocols on the + * same port. + */ + byte[] data = p.getData(); + int offset = p.getOffset(); + byte b0 = data[offset]; + + if ((b0 & 0xC0) == 0) + { + byte b1 = data[offset + 1]; + char method = (char) ((b0 & 0xFE) | (b1 & 0xEF)); + + return acceptMethod(method); + } + } + return false; + } + + /** + * Determines whether this DatagramPacketFilter accepts a + * DatagramPacket which represents a STUN message with a specific + * STUN method. + * + * @param method the STUN method of a STUN message represented by a + * DatagramPacket to be checked whether it is accepted by this + * DatagramPacketFilter + * @return true if this DatagramPacketFilter accepts the + * DatagramPacket which represents a STUN message with the + * specified STUN method; otherwise, false + */ + protected abstract boolean acceptMethod(char method); +} diff --git a/src/org/ice4j/socket/StunDatagramPacketFilter.java b/src/org/ice4j/socket/StunDatagramPacketFilter.java index fac69fc..8d62ab5 100644 --- a/src/org/ice4j/socket/StunDatagramPacketFilter.java +++ b/src/org/ice4j/socket/StunDatagramPacketFilter.java @@ -7,44 +7,44 @@ */ package org.ice4j.socket; -import java.net.*; +import org.ice4j.message.*; /** * Implements a DatagramPacketFilter which only accepts - * DatagramPackets which represent STUN messages. + * DatagramPackets which represent STUN messages defined in RFC 5389 + * "Session Traversal Utilities for NAT (STUN)" i.e. with method Binding or the + * reserved method 0x000 and 0x002/SharedSecret. * * @author Lubomir Marinov */ public class StunDatagramPacketFilter - implements DatagramPacketFilter + extends AbstractStunDatagramPacketFilter { /** - * Determines whether a specific DatagramPacket represents a STUN - * message. + * Determines whether this DatagramPacketFilter accepts a + * DatagramPacket which represents a STUN message with a specific + * STUN method. StunDatagramPacketFilter only accepts the method + * Binding and the reserved methods 0x000 and 0x002/SharedSecret. * - * @param p the DatagramPacket which is to be checked whether it is - * a STUN message - * @return true if p represents a STUN message + * @param method the STUN method of a STUN message represented by a + * DatagramPacket to be checked whether it is accepted by this + * DatagramPacketFilter + * @return true if this DatagramPacketFilter accepts the + * DatagramPacket which represents a STUN message with the + * specified STUN method; otherwise, false + * @see BaseStunDatagramPacketFilter#acceptMethod(char) */ - public boolean accept(DatagramPacket p) + public boolean acceptMethod(char method) { - /* - * All STUN messages MUST start with a 20-byte header followed by zero - * or more Attributes. - */ - if (p.getLength() >= 20) + switch (method) { - /* - * The most significant 2 bits of every STUN message MUST be zeroes. - * This can be used to differentiate STUN packets from other - * protocols when STUN is multiplexed with other protocols on the - * same port. - */ - byte b0 = p.getData()[p.getOffset()]; - - return ((b0 & 0xC0) == 0); + case Message.STUN_METHOD_BINDING: + case 0x0000: + case 0x0002: + return true; + default: + return false; } - return false; } }