Package org.jitsi.impl.neomedia.transform.zrtp

Class ZRTPTransformEngine

  • All Implemented Interfaces:
    gnu.java.zrtp.ZrtpCallback, PacketTransformer, TransformEngine, SrtpControl.TransformEngine
    public class ZRTPTransformEngine
extends SinglePacketTransformer
implements SrtpControl.TransformEngine, gnu.java.zrtp.ZrtpCallback
    JMF extension/connector to support GNU ZRTP4J. ZRTP was developed by Phil Zimmermann and provides functions to negotiate keys and other necessary data (crypto data) to set-up the Secure RTP (SRTP) crypto context. Refer to Phil's ZRTP specification at his Zfone project site to get more detailed information about the capabilities of ZRTP.

    Short overview of the ZRTP4J implementation

    ZRTP is a specific protocol to negotiate encryption algorithms and the required key material. ZRTP uses a RTP session to exchange its protocol messages. A complete GNU ZRTP4J implementation consists of two parts, the GNU ZRTP4J core and specific code that binds the GNU ZRTP core to the underlying RTP/SRTP stack and the operating system:
    • The GNU ZRTP core is independent of a specific RTP/SRTP stack and the operating system and consists of the ZRTP protocol state engine, the ZRTP protocol messages, and the GNU ZRTP4J engine. The GNU ZRTP4J engine provides methods to setup ZRTP message and to analyze received ZRTP messages, to compute the crypto data required for SRTP, and to maintain the required hashes and HMAC.
    • The second part of an implementation is specific glue code the binds the GNU ZRTP core to the actual RTP/SRTP implementation and other operating system specific services such as timers.
    The GNU ZRTP4J core uses a callback interface class (refer to ZrtpCallback) to access RTP/SRTP or operating specific methods, for example to send data via the RTP/SRTP stack, to access timers, provide mutex handling, and to report events to the application.

    The ZRTPTransformEngine

    ZRTPTransformEngine implements code that is specific to the JMF implementation. To perform its tasks ZRTPTransformEngine
    • extends specific classes to hook into the JMF RTP methods and the RTP/SRTP send and receive queues
    • implements the ZrtpCallback interface to provide to enable data send and receive other specific services (timer to GNU ZRTP4J
    • provides ZRTP specific methods that applications may use to control and setup GNU ZRTP
    • can register and use an application specific callback class (refer to ZrtpUserCallback)
    After instantiating a GNU ZRTP4J session (see below for a short example) applications may use the ZRTP specific methods of ZRTPTransformEngine to control and setup GNU ZRTP, for example enable or disable ZRTP processing or getting ZRTP status information. GNU ZRTP4J provides a ZrtpUserCallback class that an application may extend and register with ZRTPTransformEngine. GNU ZRTP4J and ZRTPTransformEngine use the ZrtpUserCallback methods to report ZRTP events to the application. The application may display this information to the user or act otherwise. The following figure depicts the relationships between ZRTPTransformEngine, JMF implementation, the GNU ZRTP4J core, and an application that provides an ZrtpUserCallback class. 
    
                  +---------------------------+
                  |  ZrtpTransformConnector   |
                  | extends TransformConnector|
                  | implements RTPConnector   |
                  +---------------------------+
                                |
                                | uses
                                |
  +----------------+      +-----+---------------+
  |  Application   |      |                     |      +----------------+
  |  instantiates  | uses | ZRTPTransformEngine | uses |                |
  | a ZRTP Session +------+    implements       +------+   GNU ZRTP4J   |
  |  and provides  |      |   ZrtpCallback      |      |      core      |
  |ZrtpUserCallback|      |                     |      | implementation |
  +----------------+      +---------------------+      |  (ZRtp et al)  |
                                                       |                |
                                                       +----------------+
    The following short code snippets show how an application could instantiate a ZrtpTransformConnector, get the ZRTP4J engine and initialize it. Then the code get a RTP manager instance and initializes it with the ZRTPTransformConnector. Please note: setting the target must be done with the connector, not with the RTP manager. 
     ...
   transConnector = (ZrtpTransformConnector)TransformManager
                                                  .createZRTPConnector(sa);
   zrtpEngine = transConnector.getEngine();
   zrtpEngine.setUserCallback(new MyCallback());
   if (!zrtpEngine.initialize("test_t.zid"))
       System.out.println("initialize failed");

   // initialize the RTPManager using the ZRTP connector

   mgr = RTPManager.newInstance();
   mgr.initialize(transConnector);

   mgr.addSessionListener(this);
   mgr.addReceiveStreamListener(this);

   transConnector.addTarget(target);
   zrtpEngine.startZrtp();

   ...
    The demo folder contains a small example that shows how to use GNU ZRTP4J. This ZRTPTransformEngine documentation shows the ZRTP specific extensions and describes overloaded methods and a possible different behaviour.
    Author:
    Werner Dittmann <Werner.Dittmann@t-online.de>

    • Field Detail

      • ZRTP_PACKET_HEADER

        protected static final int ZRTP_PACKET_HEADER
        Each ZRTP packet has a fixed header of 12 bytes.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ZRTPTransformEngine

        public ZRTPTransformEngine()
        Construct a ZRTPTransformEngine.

    • Method Detail

      • initialize

        public boolean initialize​(String zidFilename,
                          gnu.java.zrtp.ZrtpConfigure config)
        Engine initialization method. Calling this for engine initialization and start it with auto-sensing and a given configuration setting.
        Parameters:
        zidFilename - The ZID file name
        config - The configuration data
        Returns:
        true if initialization fails, false if succeeds

      • initialize

        public boolean initialize​(String zidFilename,
                          boolean autoEnable)
        Engine initialization method. Calling this for engine initialization and start it with defined auto-sensing and a default configuration setting.
        Parameters:
        zidFilename - The ZID file name
        autoEnable - If true start with auto-sensing mode.
        Returns:
        true if initialization fails, false if succeeds

      • initialize

        public boolean initialize​(String zidFilename)
        Default engine initialization method. Calling this for engine initialization and start it with auto-sensing and default configuration setting.
        Parameters:
        zidFilename - The ZID file name
        Returns:
        true if initialization fails, false if succeeds

      • initialize

        public boolean initialize​(String zidFilename,
                          boolean autoEnable,
                          gnu.java.zrtp.ZrtpConfigure config)
        Custom engine initialization method. This allows to explicit specify if the engine starts with auto-sensing or not.
        Parameters:
        zidFilename - The ZID file name
        autoEnable - Set this true to start with auto-sensing and false to disable it.
        config - the zrtp config to use
        Returns:
        true if initialization fails, false if succeeds

      • setStartMuted

        public void setStartMuted​(boolean startMuted)
        Parameters:
        startMuted - whether to be started as muted if no secure communication is established

      • getSecureCommunicationStatus

        public boolean getSecureCommunicationStatus()
        Method for getting the default secure status value for communication
        Returns:
        the default enabled/disabled status value for secure communication

      • startZrtp

        public void startZrtp()
        Start the ZRTP stack immediately, not autosensing mode.

      • close

        public void close()
        Close the transformer and underlying transform engine. The close functions closes all stored crypto contexts. This deletes key data and forces a cleanup of the crypto contexts.
        Specified by:
        close in interface PacketTransformer
        Overrides:
        close in class SinglePacketTransformer

      • stopZrtp

        public void stopZrtp()
        Stop ZRTP engine. The ZRTP stack stores RS2 without the valid flag. If we close the ZRTP stream then check if we need to set RS2 to vaild. This is the case if we received less than 10 good SRTP packets. In this case we enable RS2 to make sure the ZRTP self-synchronization is active. This handling is needed to comply to an upcoming newer ZRTP RFC.

      • setOwnSSRC

        public void setOwnSSRC​(long ssrc)
        Set the SSRC of the RTP transmitter stream. ZRTP fills the SSRC in the ZRTP messages.
        Parameters:
        ssrc - SSRC to set

      • sendDataZRTP

        public boolean sendDataZRTP​(byte[] data)
        The callback method required by the ZRTP implementation. First allocate space to hold the complete ZRTP packet, copy the message part in its place, the initialize the header, counter, SSRC and crc.
        Specified by:
        sendDataZRTP in interface gnu.java.zrtp.ZrtpCallback
        Parameters:
        data - The ZRTP packet data
        Returns:
        true if sending succeeds, false if it fails

      • srtpSecretsReady

        public boolean srtpSecretsReady​(gnu.java.zrtp.ZrtpSrtpSecrets secrets,
                                gnu.java.zrtp.ZrtpCallback.EnableSecurity part)
        Switch on the security for the defined part.
        Specified by:
        srtpSecretsReady in interface gnu.java.zrtp.ZrtpCallback
        Parameters:
        secrets - The secret keys and salt negotiated by ZRTP
        part - An enum that defines sender, receiver, or both.
        Returns:
        always return true.

      • srtpSecretsOn

        public void srtpSecretsOn​(String c,
                          String s,
                          boolean verified)
        Switch on the security. ZRTP calls this method after it has computed the SAS and check if it is verified or not.
        Specified by:
        srtpSecretsOn in interface gnu.java.zrtp.ZrtpCallback
        Parameters:
        c - The name of the used cipher algorithm and mode, or NULL.
        s - The SAS string.
        verified - if verified is true then SAS was verified by both parties during a previous call.
        See Also:
        ZrtpCallback.srtpSecretsOn(java.lang.String, java.lang.String, boolean)

      • srtpSecretsOff

        public void srtpSecretsOff​(gnu.java.zrtp.ZrtpCallback.EnableSecurity part)
        This method shall clear the ZRTP secrets.
        Specified by:
        srtpSecretsOff in interface gnu.java.zrtp.ZrtpCallback
        Parameters:
        part - Defines for which part (sender or receiver) to switch on security

      • activateTimer

        public int activateTimer​(int time)
        Activate timer.
        Specified by:
        activateTimer in interface gnu.java.zrtp.ZrtpCallback
        Parameters:
        time - The time in ms for the timer.
        Returns:
        always return 1.

      • cancelTimer

        public int cancelTimer()
        Cancel the active timer.
        Specified by:
        cancelTimer in interface gnu.java.zrtp.ZrtpCallback
        Returns:
        always return 1.

      • handleTimeout

        public void handleTimeout()
        Timeout handling function. Delegates the handling to the ZRTP engine.

      • sendInfo

        public void sendInfo​(gnu.java.zrtp.ZrtpCodes.MessageSeverity severity,
                     EnumSet<?> subCode)
        Send information messages to the hosting environment.
        Specified by:
        sendInfo in interface gnu.java.zrtp.ZrtpCallback
        Parameters:
        severity - This defines the message's severity
        subCode - The message code.

      • zrtpNegotiationFailed

        public void zrtpNegotiationFailed​(gnu.java.zrtp.ZrtpCodes.MessageSeverity severity,
                                  EnumSet<?> subCode)
        Comes a message that zrtp negotiation has failed.
        Specified by:
        zrtpNegotiationFailed in interface gnu.java.zrtp.ZrtpCallback
        Parameters:
        severity - This defines the message's severity
        subCode - The message code.

      • zrtpNotSuppOther

        public void zrtpNotSuppOther()
        The other part doesn't support zrtp.
        Specified by:
        zrtpNotSuppOther in interface gnu.java.zrtp.ZrtpCallback

      • zrtpAskEnrollment

        public void zrtpAskEnrollment​(gnu.java.zrtp.ZrtpCodes.InfoEnrollment info)
        Zrtp ask for Enrollment.
        Specified by:
        zrtpAskEnrollment in interface gnu.java.zrtp.ZrtpCallback
        Parameters:
        info - supplied info.

      • zrtpInformEnrollment

        public void zrtpInformEnrollment​(gnu.java.zrtp.ZrtpCodes.InfoEnrollment info)
        Specified by:
        zrtpInformEnrollment in interface gnu.java.zrtp.ZrtpCallback
        See Also:
        ZrtpCallback.zrtpInformEnrollment( gnu.java.zrtp.ZrtpCodes.InfoEnrollment)

      • signSAS

        public void signSAS​(byte[] sasHash)
        Specified by:
        signSAS in interface gnu.java.zrtp.ZrtpCallback
        See Also:
        ZrtpCallback.signSAS(byte[])

      • checkSASSignature

        public boolean checkSASSignature​(byte[] sasHash)
        Specified by:
        checkSASSignature in interface gnu.java.zrtp.ZrtpCallback
        Returns:
        false if signature check fails, true otherwise
        See Also:
        ZrtpCallback.checkSASSignature(byte[])

      • setEnableZrtp

        public void setEnableZrtp​(boolean onOff)
        Sets the enableZrtp flag.
        Parameters:
        onOff - The value for the enableZrtp flag.

      • isEnableZrtp

        public boolean isEnableZrtp()
        Returns the enableZrtp flag.
        Returns:
        the enableZrtp flag.

      • SASVerified

        public void SASVerified()
        Set the SAS as verified internally if the user confirms it

      • resetSASVerified

        public void resetSASVerified()
        Resets the internal engine SAS verified flag

      • requestGoClear

        public void requestGoClear()
        Method called when the user requests through GUI to switch a secured call to unsecure mode. Just forwards the request to the Zrtp class.

      • requestGoSecure

        public void requestGoSecure()
        Method called when the user requests through GUI to switch a previously unsecured call back to secure mode. Just forwards the request to the Zrtp class.

      • setAuxSecret

        public void setAuxSecret​(byte[] data)
        Sets the auxilliary secret data
        Parameters:
        data - The auxilliary secret data

      • setClientId

        public void setClientId​(String id)
        Sets the client ID
        Parameters:
        id - The client ID

      • getHelloHash

        public String getHelloHash​(int index)
        Gets the Hello packet Hash
        Parameters:
        index - Hello hash of the Hello packet identified by index. Index must be 0 <= index < SUPPORTED_ZRTP_VERSIONS.
        Returns:
        the Hello packet hash

      • getHelloHashSep

        public String[] getHelloHashSep​(int index)
        Get the ZRTP Hello Hash data - separate strings.
        Parameters:
        index - Hello hash of the Hello packet identfied by index. Index must be 0 <= index < SUPPORTED_ZRTP_VERSIONS.
        Returns:
        String array containing the version string at offset 0, the Hello hash value as hex-digits at offset 1. Hello hash is available immediately after class instantiation. Returns null if ZRTP is not available.

      • getPeerHelloHash

        public String getPeerHelloHash()
        Get the peer's Hello Hash data. Use this method to get the peer's Hello Hash data. The method returns the data as a string.
        Returns:
        a String containing the Hello hash value as hex-digits. Peer Hello hash is available after we received a Hello packet from our peer. If peer's hello hash is not available return null.

      • getMultiStrParams

        public byte[] getMultiStrParams()
        Gets the multistream params
        Returns:
        the multistream params

      • setMultiStrParams

        public void setMultiStrParams​(byte[] parameters)
        Sets the multistream params (The multistream part needs further development)
        Parameters:
        parameters - the multistream params

      • isMultiStream

        public boolean isMultiStream()
        Gets the multistream flag (The multistream part needs further development)
        Returns:
        the multistream flag

      • acceptEnrollment

        public void acceptEnrollment​(boolean accepted)
        Used to accept a PBX enrollment request (The PBX part needs further development)
        Parameters:
        accepted - The boolean value indicating if the request is accepted

      • getSasType

        public gnu.java.zrtp.ZrtpConstants.SupportedSASTypes getSasType()
        Get the commited SAS rendering algorithm for this ZRTP session.
        Returns:
        the commited SAS rendering algorithm

      • getSasHash

        public byte[] getSasHash()
        Get the computed SAS hash for this ZRTP session.
        Returns:
        a refernce to the byte array that contains the full SAS hash.

      • sendSASRelayPacket

        public boolean sendSASRelayPacket​(byte[] sh,
                                  gnu.java.zrtp.ZrtpConstants.SupportedSASTypes render)
        Send the SAS relay packet. The method creates and sends a SAS relay packet according to the ZRTP specifications. Usually only a MitM capable user agent (PBX) uses this function.
        Parameters:
        sh - the full SAS hash value
        render - the SAS rendering algorithm
        Returns:
        true if the SASReplay packet has been correctly sent, false otherwise

      • isMitmMode

        public boolean isMitmMode()
        Check the state of the MitM mode flag. If true then this ZRTP session acts as MitM, usually enabled by a PBX based client (user agent)
        Returns:
        state of mitmMode

      • setMitmMode

        public void setMitmMode​(boolean mitmMode)
        Set the state of the MitM mode flag. If MitM mode is set to true this ZRTP session acts as MitM, usually enabled by a PBX based client (user agent).
        Parameters:
        mitmMode - defines the new state of the mitmMode flag

      • setParanoidMode

        public void setParanoidMode​(boolean yesNo)
        Enables or disables paranoid mode. For further explanation of paranoid mode refer to the documentation of ZRtp class.
        Parameters:
        yesNo - If set to true then paranoid mode is enabled.

      • isParanoidMode

        public boolean isParanoidMode()
        Check status of paranoid mode.
        Returns:
        Returns true if paranoid mode is enabled.

      • isEnrollmentMode

        public boolean isEnrollmentMode()
        Check the state of the enrollment mode. If true then we will set the enrollment flag (E) in the confirm packets and performs the enrollment actions. A MitM (PBX) enrollment service sets this flag.
        Returns:
        status of the enrollmentMode flag.

      • setEnrollmentMode

        public void setEnrollmentMode​(boolean enrollmentMode)
        Set the state of the enrollment mode. If true then we will set the enrollment flag (E) in the confirm packets and perform the enrollment actions. A MitM (PBX) enrollment service must set this mode to true. Can be set to true only if mitmMode is also true.
        Parameters:
        enrollmentMode - defines the new state of the enrollmentMode flag

      • setSignatureData

        public boolean setSignatureData​(byte[] data)
        Sets signature data for the Confirm packets
        Parameters:
        data - the signature data
        Returns:
        true if signature data was successfully set

      • getSignatureData

        public byte[] getSignatureData()
        Gets signature data
        Returns:
        the signature data

      • getSignatureLength

        public int getSignatureLength()
        Gets signature length
        Returns:
        the signature length

      • handleGoClear

        public void handleGoClear()
        Method called by the Zrtp class as result of a GoClear request from the other peer. An explicit user confirmation is needed before switching to unsecured mode. This is asked through the user callback.
        Specified by:
        handleGoClear in interface gnu.java.zrtp.ZrtpCallback

      • setConnector

        public void setConnector​(AbstractRTPConnector connector)
        Sets the RTP connector using this ZRTP engine
        Parameters:
        connector - the connector to set

      • setUserCallback

        public void setUserCallback​(SecurityEventManager ub)
        Sets the user callback class used to maintain the GUI ZRTP part
        Parameters:
        ub - The user callback class

      • isStarted

        public boolean isStarted()
        Returns the current status of the ZRTP engine
        Returns:
        the current status of the ZRTP engine

      • getUserCallback

        public SecurityEventManager getUserCallback()
        Gets the user callback used to manage the GUI part of ZRTP
        Returns:
        the user callback

      • getPeerZid

        public byte[] getPeerZid()
        Get other party's ZID (ZRTP Identifier) data This functions returns the other party's ZID that was receivied during ZRTP processing. The ZID data can be retrieved after ZRTP receive the first Hello packet from the other party. The application may call this method for example during SAS processing in showSAS(...) user callback method.
        Returns:
        the ZID data as byte array.

      • getNumberSupportedVersions

        public int getNumberSupportedVersions()
        Get number of supported ZRTP protocol versions.
        Returns:
        the number of supported ZRTP protocol versions.

      • getCurrentProtocolVersion

        public int getCurrentProtocolVersion()
        Get negotiated ZRTP protocol version.
        Returns:
        the integer representation of the negotiated ZRTP protocol version.