gnu.java.zrtp

Class ZrtpUserCallback

java.lang.Object

gnu.java.zrtp.ZrtpUserCallback

public class ZrtpUserCallback
extends Object

Application callback methods. The RTP specific part of GNU ZRTP uses these callback methods to report ZRTP events to the application. This class implements a default behaviour for each callback method, usually just a return. An application may extend this class and overload methods to implement its own behaviour. The application must register its callback class using ZrtpQueue#setUserCallback(). CAVEAT
All methods of the user callback class and classes that extend this class run in the context of the RTP thread. Thus it is of paramount importance to keep the execution time of the methods as short as possible.

Author:

Werner Dittmann <Werner.Dittmann@t-online.de>

Constructor Summary

Constructors

Constructor and Description
ZrtpUserCallback()

Method Summary

Modifier and Type	Method and Description
boolean	checkSASSignature(byte[] sasHash) ZRTP core calls this method to request a SAS signature check.
void	confirmGoClear() Inform the user that ZRTP received "go clear" message from its peer.
void	secureOff() Inform user interface that security is not active any more.
void	secureOn(String cipher) Inform user interface that security is active now.
void	showMessage(ZrtpCodes.MessageSeverity sev, EnumSet<?> subCode) Show some information to user.
void	showSAS(String sas, boolean verified) Show the Short Authentication String (SAS) on user interface.
void	signSAS(byte[] sasHash) ZRTP core calls this method to request a SAS signature.
void	zrtpAskEnrollment(ZrtpCodes.InfoEnrollment info) ZRTP core calls this method to inform about a PBX enrollment request.
void	zrtpInformEnrollment(ZrtpCodes.InfoEnrollment info) ZRTP core calls this method to inform about PBX enrollment result.
void	zrtpNegotiationFailed(ZrtpCodes.MessageSeverity severity, EnumSet<?> subCode) ZRTP core calls this if the negotiation failed.
void	zrtpNotSuppOther() ZRTP core calls this method if the other side does not support ZRTP.

Methods inherited from class java.lang.Object

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

Constructor Detail

ZrtpUserCallback

public ZrtpUserCallback()

Method Detail

secureOn

public void secureOn(String cipher)

Inform user interface that security is active now. ZRTP calls this method if the sender and the receiver are in secure mode now.

Parameters:

cipher - Name and mode of cipher used to encrypt the SRTP stream

secureOff

public void secureOff()

Inform user interface that security is not active any more. ZRTP calls this method if either the sender or the receiver left secure mode.

showSAS

public void showSAS(String sas,
                    boolean verified)

Show the Short Authentication String (SAS) on user interface. ZRTP calls this method to display the SAS and inform about the SAS verification status. The user interface shall enable a SAS verfication button (or similar UI element). The user shall click on this UI element after he/she confirmed the SAS code with the partner.

Parameters:

sas - The string containing the SAS.

verified - If verified is true then SAS was verified by both parties during a previous call, otherwise it is set to false.

confirmGoClear

public void confirmGoClear()

Inform the user that ZRTP received "go clear" message from its peer. On receipt of a go clear message the user is requested to confirm a switch to unsecure (clear) modus. Until the user confirms ZRTP (and the underlying RTP) does not send any data.

showMessage

public void showMessage(ZrtpCodes.MessageSeverity sev,
                        EnumSet<?> subCode)

Show some information to user. ZRTP calls this method to display some information to the user. Along with the message ZRTP provides a severity indicator that defines: Info, Warning, Error, and Alert. Refer to the ZrtpCodes#MessageSeverity. The UI may use this indicator to highlight messages or alike. Depending on the severity code the EnumSet subcode parameter contains one enumeration of either ZrtpCodes#InfoCodes, ZrtpCodes#WarningCodes, ZrtpCodes#SevereCodes, or ZrtpCodes#ZrtpErrorCodes. The ZrtpCodes#ZrtpErrorCodes enumeration has a public value field that contains the ZRTP error code as defined in the ZRTP specification.

Parameters:

sev - Severity of the message.

subCode - The subcode identifying the reason.

See Also:

ZrtpCodes.MessageSeverity

zrtpNegotiationFailed

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

ZRTP core calls this if the negotiation failed. ZRTP core calls this method in case ZRTP negotiation failed. The parameters show the severity as well as some explanatory text. For the subcode refer to ZrtpUserCallback#showMessage() above.

Parameters:

severity - This defines the message's severity

subCode - The subcode identifying the reason.

zrtpNotSuppOther

public void zrtpNotSuppOther()

ZRTP core calls this method if the other side does not support ZRTP. If the other side does not answer the ZRTP Hello packets then ZRTP calls this method.

zrtpAskEnrollment

public void zrtpAskEnrollment(ZrtpCodes.InfoEnrollment info)

ZRTP core calls this method to inform about a PBX enrollment request. Please refer to chapter 7.3 ff to get more details about PBX enrollment and SAS relay.

Parameters:

info - Give some information to the user about the PBX requesting an enrollment.

zrtpInformEnrollment

public void zrtpInformEnrollment(ZrtpCodes.InfoEnrollment info)

ZRTP core calls this method to inform about PBX enrollment result. Informs the use about the acceptance or denial of a PBX enrollment request

Parameters:

info - Give some information to the user about the result of an enrollment.

signSAS

public void signSAS(byte[] sasHash)

ZRTP core calls this method to request a SAS signature. After ZRTP was able to compute the Short Authentication String (SAS) it calls this method. The client may now use an approriate method to sign the SAS hash. NOTE
: The application must use the first 32 bytes of the SAS hash array only, even if the array is longer (sasHash.length >32). Refer to chapter 4.5.3 of RFC 6189 (ZRTP specification). The client calls setSignatureData() to set the resulting signature in the ZRTP protocol. Refer to chapter 7.2 of RFC 6189.

Parameters:

sasHash - The SAS hash to sign.

checkSASSignature

public boolean checkSASSignature(byte[] sasHash)

ZRTP core calls this method to request a SAS signature check. After ZRTP received a SAS signature in one of the Confirm packets it call this method. The client uses getSignatureData()of ZrtpQueue to get the signature data and to perform the signature check. Refer to chapter 7.2 of RFC 6189 (ZRTP specification). NOTE
: The application must use the first 32 bytes of the SAS hash array only, even if the array is longer (sasHash.length >32). Refer to chapter 4.5.3 of RFC 6189 (ZRTP specification). If the signature check fails the client returns false. In this case ZRTP signals an error to the other peer and terminates the ZRTP handshake.

Parameters:

sasHash - The sasHash that was signed by the other peer.

Returns:

true if the signature was ok, false otherwise.