[asterisk-scf-commits] asterisk-scf/release/slice.git branch "master" updated.
Commits to the Asterisk SCF project code repositories
asterisk-scf-commits at lists.digium.com
Wed Jul 20 12:47:41 CDT 2011
branch "master" has been updated
via 05556bf8836d212589eebf250ff253f86a1c52da (commit)
from 94ad9deef3e73d3dc1562e60d65e0ab6983a1338 (commit)
Summary of changes:
slice/AsteriskSCF/Media/RTP/MediaRTPIf.ice | 148 ++++++++--
slice/AsteriskSCF/System/ExceptionsIf.ice | 5 +
slice/AsteriskSCF/System/NAT/NATTraversalIf.ice | 391 +++++++++++++++++++++++
3 files changed, 524 insertions(+), 20 deletions(-)
create mode 100644 slice/AsteriskSCF/System/NAT/NATTraversalIf.ice
- Log -----------------------------------------------------------------
commit 05556bf8836d212589eebf250ff253f86a1c52da
Author: Brent Eagles <beagles at digium.com>
Date: Wed Jul 20 15:10:03 2011 -0230
Merges support for SRTP and NAT traversal.
diff --git a/slice/AsteriskSCF/Media/RTP/MediaRTPIf.ice b/slice/AsteriskSCF/Media/RTP/MediaRTPIf.ice
index 8687f30..d231637 100644
--- a/slice/AsteriskSCF/Media/RTP/MediaRTPIf.ice
+++ b/slice/AsteriskSCF/Media/RTP/MediaRTPIf.ice
@@ -29,26 +29,54 @@ module RTP
["suppress"]
module V1
{
- /**
- * String representation of the version of this interface
- */
- const string Version = "V1";
+ /**
+ * String representation of the version of this interface
+ */
+ const string Version = "V1";
- /**
- * Extended discovery class for RTP media services.
- */
- unsliceable class RTPServiceLocatorParams extends AsteriskSCF::Core::Discovery::V1::ServiceLocatorParams
- {
- /**
- * A sequence of formats that the RTP media service is expected to transport.
- */
- AsteriskSCF::Media::V1::FormatSeq formats;
+ /**
+ * Extended discovery class for RTP media services.
+ */
+ unsliceable class RTPServiceLocatorParams extends AsteriskSCF::Core::Discovery::V1::ServiceLocatorParams
+ {
+ /**
+ * A sequence of formats that the RTP media service is expected to transport.
+ */
+ AsteriskSCF::Media::V1::FormatSeq formats;
- /**
- * Whether IPv6 is to be used or not.
- */
- bool ipv6 = false;
- };
+ /**
+ * Whether IPv6 is to be used or not.
+ */
+ bool ipv6 = false;
+
+ /**
+ * Flag to indicate whether the service is SRTP capable or not.
+ *
+ * TODO: If a service potentially has a lot of variation in capabilities, a dictionary or similar may be
+ * more appropriate here. Subclassing does not necessarily work because a service may support one type
+ * of feature set and not another.
+ */
+ bool srtpCapable = false;
+ };
+
+ /**
+ * Extend discovery class to enable RTP over ICE negotiated media flows.
+ */
+ unsliceable class RTPOverICEServiceLocatorParams extends RTPServiceLocatorParams
+ {
+ /**
+ * Enable ICE negotiated RTP media flows. We set a default of true mostly because
+ * we assume if you looking for a component that understands this type then
+ * it probably has this feature enabled.
+ */
+ bool enableRTPOverICE = true;
+
+ /**
+ * Enable TURN server access/usage if configured. NOTE: Has no effect if enableRTPOverICE
+ * is NOT enabled.
+ */
+ bool enableTURN = true;
+ };
/**
* Interface to an RTP stream source.
@@ -153,18 +181,98 @@ module V1
};
/**
+ * Indicates that the SRTP functionality is not available at the moment.
+ */
+ exception SRTPUnavailable
+ {
+ };
+
+ /**
+ * General exception to indicate that attempts to establish an SRTP enabled flow have failed.
+ */
+ exception SRTPFailure
+ {
+ };
+
+ /**
+ * Exception indicating the session has already started.
+ */
+ exception SRTPAlreadyStarted
+ {
+ };
+
+ /**
+ * Interface to an SRTP enabled RTP session.
+ */
+ interface SRTPSession extends RTPSession
+ {
+
+ /**
+ *
+ * Set the key information for the local endpoint.
+ *
+ * @param suiteName The type of crypto suite to be used.
+ *
+ * @param keyInfo The key for the specified crypto suite (may be empty).
+ *
+ * @param enableAuthentication Specify that the connection should be authenticated.
+ *
+ * @param enableEncryption Specify that the RTP flows should be encrypted.
+ *
+ * @throws SRTPUnavailable if the SRTP functionality is unavailable at the moment, really should not happen.
+ *
+ */
+ void setOptions(string suiteName, string keyInfo, bool enableAuthentication, bool enableEncryption)
+ throws SRTPUnavailable;
+
+ /**
+ * Set the key information and initiates communication with peer.
+ *
+ * @param suiteName The type of crypto suite to be used.
+ *
+ * @param keyInfo The key for the specified crypto suite (may be empty).
+ *
+ * @param enableAuthentication Specify that the connection should be authenticated.
+ *
+ * @param enableEncryption Specify that the RTP flows should be encrypted.
+ *
+ * @throws SRTPUnavailable if the SRTP functionality is unavailable at the moment, really should not happen.
+ *
+ * @throws SRTPFailure if authentication/encryption with the peer has failed.
+ *
+ * @throws SRTPAlreadyStarted if this is a duplicate call to start.
+ *
+ */
+ void start(string suiteName, string keyInfo, bool enableAuthentication, bool enableEncryption) throws
+ SRTPUnavailable, SRTPFailure, SRTPAlreadyStarted;
+ };
+
+ /**
+ * This exception will be thrown by the media service if the session cannot be allocated for some
+ * reason. It shall include a descriptive message as to why the request failed.
+ */
+ exception SessionAllocationFailure
+ {
+ string message;
+ };
+
+
+ /**
* Interface to an RTP media service.
*/
interface RTPMediaService
{
/**
* Method which creates a new RTP session and returns a proxy to it.
- *
+ *
* @param params Parameters to configure the RTP session with.
*
* @return RTPSession* A proxy to the new RTP session.
+ *
+ * @throws SessionAllocationFailure if the media service is unable to allocate a session
+ * to match the provided parameters.
*/
- RTPSession* allocate(RTPServiceLocatorParams params);
+ RTPSession* allocate(RTPServiceLocatorParams params) throws SessionAllocationFailure;
};
}; /* end module V1 */
diff --git a/slice/AsteriskSCF/System/ExceptionsIf.ice b/slice/AsteriskSCF/System/ExceptionsIf.ice
index fc57441..f18a941 100644
--- a/slice/AsteriskSCF/System/ExceptionsIf.ice
+++ b/slice/AsteriskSCF/System/ExceptionsIf.ice
@@ -31,6 +31,11 @@ module V1
{
};
+ exception InternalInitializationException
+ {
+ string message;
+ };
+
}; /* End of V1 */
}; /* End of System */
diff --git a/slice/AsteriskSCF/System/NAT/NATTraversalIf.ice b/slice/AsteriskSCF/System/NAT/NATTraversalIf.ice
new file mode 100644
index 0000000..46a206b
--- /dev/null
+++ b/slice/AsteriskSCF/System/NAT/NATTraversalIf.ice
@@ -0,0 +1,391 @@
+/*
+ * Asterisk SCF -- An open-source communications framework.
+ *
+ * Copyright (C) 2010, Digium, Inc.
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk SCF project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE.txt file
+ * at the top of the source tree.
+ */
+
+#pragma once
+
+module AsteriskSCF
+{
+module System
+{
+module NAT
+{
+module V1
+{
+/**
+ * If NAT detection is in use, this enum provides values for classifications of the different types.
+ **/
+enum DetectedNATType
+{
+ /**
+ *
+ * A placeholder value indicating that detection has not been attempted or
+ * is not yet complete.
+ *
+ **/
+ Unknown,
+
+ /**
+ *
+ * Indicates that the current detection mechanisms were unable to determine
+ * the type of NAT.
+ *
+ **/
+ ErrUnknown,
+
+ /**
+ *
+ * The firewall/NAT is effectively open with no translation.
+ *
+ **/
+ Open,
+
+ /**
+ *
+ * The NAT is blocking the communication scheme being tested/tried.
+ *
+ **/
+ Blocked,
+
+ /**
+ *
+ * UDP can reach external networks, but replies have to come back to the
+ * actual request source (no translation).
+ *
+ **/
+ SymmetricUDP,
+
+ /**
+ *
+ * All outgoing requests from the same internal IP address + port are mapped to
+ * the same external address + port and incoming requests the mapped external
+ * address will be translated and sent to it.
+ *
+ **/
+ FullCone,
+
+ /**
+ *
+ * All outgoing requests form the same internal IP address + port destined
+ * for a single external IP address + port are mapped to the same external
+ * IP address and port. If a request from the aformentioned internal
+ * address + port is sent to a different destination, it will be mapped to
+ * a different external IP address + port. Only external ip addr+ports can
+ * send a reply/request back through the mapping created to communicate
+ * with it.
+ *
+ **/
+ Symmetric,
+
+ /**
+ *
+ * All outgoing requests from an internal IP address + port are mapped to
+ * the same external IP address + port. Packets from external sources can
+ * only be sent if they received a request through that mapping.
+ *
+ **/
+ Restricted,
+
+ /**
+ *
+ * Same as restricted, but external sources can only send to the internal
+ * host if the packets are sent from an IP address *and* port that had
+ * previously received a packet from the mapped address.
+ *
+ **/
+ PortRestricted
+};
+
+/**
+ *
+ * Candidate types qualify ICE candidates according to what kinds of means would be required to access them.
+ *
+ **/
+enum CandidateType
+{
+ /**
+ *
+ * A host candidate is accessible directly.
+ *
+ **/
+ Host,
+
+ /**
+ *
+ * A server reflexive candidate represents a publically mapped address of a
+ * local host address. These are obtained by establishing a binding on a
+ * NAT with STUN.
+ *
+ **/
+ ServerReflexive,
+
+ /**
+ *
+ * A peer reflexive candidate is the apparent address seen by a peer when
+ * performing connectivity checks.
+ *
+ **/
+ PeerReflexive,
+
+ /**
+ *
+ * A relayed address indicates a candidate allocated on a TURN server.
+ *
+ **/
+ Relayed
+};
+
+/**
+ *
+ * ICE "agents" may be in a controlling or controlled role (or unknown!). The
+ * agent with the controlling role gets the final word on which candidate pair
+ * will be used.
+ *
+ **/
+enum Role
+{
+ UndefinedRole,
+ Controlling,
+ Controlled
+};
+
+/**
+ *
+ * Agent implementation type.
+ *
+ **/
+enum AgentType
+{
+ /**
+ *
+ * Lite agents respond to connectivity checks, but they only generate
+ * host candidates and can be directly accessed. Basically they can
+ * participate in ICE negotiation sessions but don't require NAT candidate
+ * mappings. Lite agents are never controlling agents.
+ *
+ **/
+ Lite,
+
+ /**
+ *
+ * Full ICE implementations can be controlling agents but may also simply
+ * be the controlled agent depending on circumstances.
+ *
+ **/
+ Full
+};
+
+/**
+ *
+ * A candidate may use different transport types.
+ *
+ **/
+enum TransportType
+{
+ UDP,
+ TCP
+ /* Others? */
+};
+
+/**
+ *
+ * Candidate class describes a candidate along with its ICE related descriptors.
+ *
+ **/
+class Candidate
+{
+ /**
+ *
+ * The candidate includes a key that can be used to identify the ICE
+ * session to ensure that it can be easily mapped/referred to when being
+ * passed among services.
+ *
+ **/
+ string sessionId;
+
+ /**
+ *
+ * Candidate's in an ICE session are further distinguished from each other by
+ * a component identifier.
+ *
+ **/
+ long componentId;
+
+ /**
+ *
+ * Each candidate has priority!
+ *
+ **/
+ int priority;
+
+ /**
+ *
+ * The CandidateType helps identify the mechanism that can be used
+ * to access a host through the associated address information.
+ *
+ */
+ CandidateType type;
+
+ /**
+ *
+ * The base or local address. For non-turn based candidates, this is the local IP address. For TURN based
+ * candidates, its the address of the TURN server.
+ *
+ **/
+ string baseAddress;
+
+
+ /**
+ *
+ * The base or local port.
+ *
+ **/
+ int basePort;
+
+ /**
+ *
+ * The mapped address (note that this will be empty for host candidates.
+ *
+ **/
+ string mappedAddress;
+
+ /**
+ *
+ * The mapped port (note that this is only relevant if the mappedAddress is not empty.
+ *
+ **/
+ int mappedPort;
+
+ /**
+ *
+ * The type of transport that this candidate
+ *
+ **/
+ TransportType transport;
+
+ /**
+ *
+ * The candidate's foundation is a non-unique hash value where similar
+ * candidates should result in similar hash values. This field could be blank, and if
+ * so, must be generated if required.
+ *
+ **/
+ string foundation;
+};
+
+sequence<Candidate> CandidateSeq;
+
+exception UnsupportedCandidate
+{
+ string message;
+};
+
+exception NegotiationNotSupported
+{
+};
+
+exception NegotiationInterrupted
+{
+ string reason;
+};
+
+exception NegotiationError
+{
+ string errorMessage;
+};
+
+exception NoValidCandidates
+{
+};
+
+const string InteractiveConnectionAgentFacetName = "ICE_AGENT";
+
+/**
+ *
+ * The InteractiveConnectionAgent defines an interface for components that implement the ICE protocol or
+ * similar to negotiate connections between agents that cannot directly connect to each other. This is
+ * meant to be a fairly lightweight facility, usually added to an existing object as facet, multiple
+ * inheritance, etc.
+ *
+ * Note: the typical details of ICE, TURN, STUN etc are omitted from this interface for the moment as
+ * existing mechanism have been incorporated elsewhere, usually as a component specific detail.
+ *
+ **/
+interface InteractiveConnectionAgent
+{
+ /**
+ *
+ * Return the agent's type.
+ *
+ */
+ idempotent AgentType getAgentType();
+
+ /**
+ *
+ * Return the detected NAT type. This NAT will be the one closest to a
+ * configured STUN server. Information about intermediate NATs will not be
+ * evident.
+ *
+ **/
+ idempotent DetectedNATType getNATType();
+
+ /**
+ *
+ * Retrieves the current role of the agent... this can change over time.
+ *
+ **/
+ idempotent Role getRole();
+
+ /**
+ *
+ * When provided a sequence of candidates from a remote agent, select the best Candidate for communicating
+ * with this agent.
+ *
+ * @param proposedCandidates The sequence of candidates from the remote agent.
+ *
+ * @param hostname The target host
+ *
+ * @param port The intended port (may be 0 if defaults are to be used)
+ *
+ * @throws UnsupportedCandidate if there something about the provided Candidates that is not supported
+ * by this agent.
+ *
+ * @throws NegotiationNotSupported if the is agent type is ice-lite or not controlling.
+ *
+ * @throws NoValidCandidates if all connection check fail.
+ *
+ * @throws NegotiationInterrupted if the negotiation is interrupted for some reason.
+ *
+ * @throws NegotiationError if the negotation fails (includes error message).
+ *
+ **/
+ ["amd"] Candidate negotiate(string hostname, int port, CandidateSeq proposedCandidates) throws
+ UnsupportedCandidate,
+ NegotiationNotSupported,
+ NegotiationInterrupted,
+ NegotiationError,
+ NoValidCandidates;
+ /**
+ *
+ * Return a list of Candidates for the current agent.
+ *
+ **/
+ CandidateSeq getCandidates();
+};
+
+}; /* End of module V1 */
+}; /* End of module NAT */
+}; /* End of module System */
+}; /* End of module AsteriskSCF */
-----------------------------------------------------------------------
--
asterisk-scf/release/slice.git
More information about the asterisk-scf-commits
mailing list