net.java.sip.communicator.impl.media.transform.zrtp
Class ZRTPTransformEngine

java.lang.Object
  net.java.sip.communicator.impl.media.transform.zrtp.ZRTPTransformEngine

All Implemented Interfaces:

gnu.java.zrtp.ZrtpCallback, PacketTransformer, TransformEngine

public class ZRTPTransformEngine
extends Object
implements TransformEngine, PacketTransformer, 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 operationg 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. Plase 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("iniatlize 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>

Nested Class Summary

Nested classes/interfaces inherited from interface gnu.java.zrtp.ZrtpCallback

gnu.java.zrtp.ZrtpCallback.EnableSecurity, gnu.java.zrtp.ZrtpCallback.Role

Field Summary

protected static int

ZRTP_PACKET_HEADER Each ZRTP packet has a fixed header of 12 bytes.

Constructor Summary

ZRTPTransformEngine()
Construct a ZRTPTransformEngine.

Method Summary

void	acceptEnrollment(boolean accepted) Used to accept a PBX enrollment request (The PBX part needs further development)
int	activateTimer(int time)
int	cancelTimer()
boolean	checkSASSignature(String sas)
void	cleanup() Cleanup function for any remaining timers
String	getHelloHash() Gets the Hello packet Hash
byte[]	getMultiStrParams() Gets the multistream params
PacketTransformer	getRTCPTransformer() Returns an instance of ZRTPCTransformer.
PacketTransformer	getRTPTransformer() Returns this RTPTransformer.
byte[]	getSignatureData() Gets signature data
int	getSignatureLength() Gets signature length
SecurityEventManager	getUserCallback() Gets the user callback used to manage the GUI part of ZRTP
byte[]	getZid() Get other party's ZID (ZRTP Identifier) data This functions returns the other party's ZID that was receivied during ZRTP processing.
void	handleGoClear() Method called by the Zrtp class as result of a GoClear request from the other peer.
void	handleTimeout() Timeout handling function.
boolean	initialize(String zidFilename) Default engine initialization method.
boolean	initialize(String zidFilename, boolean autoEnable) Engine initialization method.
boolean	initialize(String zidFilename, boolean autoEnable, gnu.java.zrtp.ZrtpConfigure config) Custom engine initialization method.
boolean	initialize(String zidFilename, gnu.java.zrtp.ZrtpConfigure config) Engine initialization method.
boolean	isEnableZrtp() Returns the enableZrtp flag.
boolean	isMultiStream() Gets the multistream flag (The multistream part needs further development)
boolean	isStarted() Returns the current status of the ZRTP engine
void	requestGoClear() Method called when the user requests through GUI to switch a secured call to unsecure mode.
void	requestGoSecure() Method called when the user requests through GUI to switch a previously unsecured call back to secure mode.
void	resetSASVerified() Resets the internal engine SAS verified flag
RawPacket	reverseTransform(RawPacket pkt) The input data stream calls this method to transform incoming packets.
void	SASVerified() Set the SAS as verified internally if the user confirms it
boolean	sendDataZRTP(byte[] data) The callback method required by the ZRTP implementation.
void	sendInfo(gnu.java.zrtp.ZrtpCodes.MessageSeverity severity, EnumSet<?> subCode)
void	setAuxSecret(byte[] data) Sets the auxilliary secret data
void	setClientId(String id) Sets the client ID
void	setConnector(TransformConnector connector) Sets the RTP connector using this ZRTP engine (This method should be changed to an addConnector to a connector array managed by the engine for implementing multistream mode)
void	setEnableZrtp(boolean onOff) Sets the enableZrtp flag.
void	setMultiStrParams(byte[] parameters) Sets the multistream params (The multistream part needs further development)
void	setOwnSSRC(long ssrc) Set the SSRC of the RTP transmitter stream.
void	setPBXEnrollment(boolean yesNo) Sets the PBX enrollment flag (see chapter 8.3 of ZRTP standards) (The PBX part needs further development)
void	setPbxSecret(byte[] data) Sets the PBX secret data
boolean	setSignatureData(byte[] data) Sets signature data for the Confirm packets
void	setUserCallback(SecurityEventManager ub) Sets the user callback class used to maintain the GUI ZRTP part
void	signSAS(String sas)
void	srtpSecretsOff(gnu.java.zrtp.ZrtpCallback.EnableSecurity part)
void	srtpSecretsOn(String c, String s, boolean verified)
boolean	srtpSecretsReady(gnu.java.zrtp.ZrtpSrtpSecrets secrets, gnu.java.zrtp.ZrtpCallback.EnableSecurity part)
void	startZrtp() Start the ZRTP stack immediately, not autosensing mode.
void	stopZrtp() Stop ZRTP engine.
RawPacket	transform(RawPacket pkt) The data output stream calls this method to transform outgoing packets.
void	zrtpAskEnrollment(String info)
void	zrtpInformEnrollment(String info)
void	zrtpNegotiationFailed(gnu.java.zrtp.ZrtpCodes.MessageSeverity severity, EnumSet<?> subCode)
void	zrtpNotSuppOther()

Methods inherited from class java.lang.Object

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

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

getRTCPTransformer

public PacketTransformer getRTCPTransformer()

Returns an instance of ZRTPCTransformer.

Specified by:

getRTCPTransformer in interface TransformEngine

Returns:

the PacketTransformer for RTCP packets

See Also:

TransformEngine.getRTCPTransformer()

getRTPTransformer

public PacketTransformer getRTPTransformer()

Returns this RTPTransformer.

Specified by:

getRTPTransformer in interface TransformEngine

Returns:

the PacketTransformer for RTP packets

See Also:

TransformEngine.getRTPTransformer()

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.

Returns:

true if initialization fails, false if succeeds

startZrtp

public void startZrtp()

Start the ZRTP stack immediately, not autosensing mode.

stopZrtp

public void stopZrtp()

Stop ZRTP engine.

cleanup

public void cleanup()

Cleanup function for any remaining timers

setOwnSSRC

public void setOwnSSRC(long ssrc)

Set the SSRC of the RTP transmitter stream. ZRTP fills the SSRC in the ZRTP messages.

Parameters:

ssrc -

transform

public RawPacket transform(RawPacket pkt)

The data output stream calls this method to transform outgoing packets.

Specified by:

transform in interface PacketTransformer

Parameters:

pkt - The packet to be transformed

Returns:

Transformed packet

See Also:

PacketTransformer.transform(RawPacket)

reverseTransform

public RawPacket reverseTransform(RawPacket pkt)

The input data stream calls this method to transform incoming packets.

Specified by:

reverseTransform in interface PacketTransformer

Parameters:

pkt - The transformed packet to be restored

Returns:

Restored packet

See Also:

PacketTransformer.reverseTransform(RawPacket)

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 initalize 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)

Specified by:

srtpSecretsReady in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.srtpSecretsReady( gnu.java.zrtp.ZrtpSrtpSecrets, gnu.java.zrtp.ZrtpCallback.EnableSecurity)

srtpSecretsOn

public void srtpSecretsOn(String c,
                          String s,
                          boolean verified)

Specified by:

srtpSecretsOn in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.srtpSecretsOn(java.lang.String, java.lang.String, boolean)

srtpSecretsOff

public void srtpSecretsOff(gnu.java.zrtp.ZrtpCallback.EnableSecurity part)

Specified by:

srtpSecretsOff in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.srtpSecretsOff( gnu.java.zrtp.ZrtpCallback.EnableSecurity)

activateTimer

public int activateTimer(int time)

Specified by:

activateTimer in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.activateTimer(int)

cancelTimer

public int cancelTimer()

Specified by:

cancelTimer in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.cancelTimer()

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)

Specified by:

sendInfo in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.sendInfo( gnu.java.zrtp.ZrtpCodes.MessageSeverity, java.util.EnumSet)

zrtpNegotiationFailed

public void zrtpNegotiationFailed(gnu.java.zrtp.ZrtpCodes.MessageSeverity severity,
                                  EnumSet<?> subCode)

Specified by:

zrtpNegotiationFailed in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.zrtpNegotiationFailed( gnu.java.zrtp.ZrtpCodes.MessageSeverity, java.util.EnumSet)

zrtpNotSuppOther

public void zrtpNotSuppOther()

Specified by:

zrtpNotSuppOther in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.zrtpNotSuppOther()

zrtpAskEnrollment

public void zrtpAskEnrollment(String info)

Specified by:

zrtpAskEnrollment in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.zrtpAskEnrollment(java.lang.String)

zrtpInformEnrollment

public void zrtpInformEnrollment(String info)

Specified by:

zrtpInformEnrollment in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.zrtpInformEnrollment(java.lang.String)

signSAS

public void signSAS(String sas)

Specified by:

signSAS in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.signSAS(java.lang.String)

checkSASSignature

public boolean checkSASSignature(String sas)

Specified by:

checkSASSignature in interface gnu.java.zrtp.ZrtpCallback

See Also:

ZrtpCallback.checkSASSignature(java.lang.String)

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

setPbxSecret

public void setPbxSecret(byte[] data)

Sets the PBX secret data

Parameters:

data - The PBX secret data

setClientId

public void setClientId(String id)

Sets the client ID

Parameters:

id - The client ID

getHelloHash

public String getHelloHash()

Gets the Hello packet Hash

Returns:

the Hello packet hash

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

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

setPBXEnrollment

public void setPBXEnrollment(boolean yesNo)

Sets the PBX enrollment flag (see chapter 8.3 of ZRTP standards) (The PBX part needs further development)

Parameters:

yesNo - The PBX enrollment flag

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(TransformConnector connector)

Sets the RTP connector using this ZRTP engine (This method should be changed to an addConnector to a connector array managed by the engine for implementing multistream mode)

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

getZid

public byte[] getZid()

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.