Package gnu.java.zrtp

Interface ZrtpCallback

public interface ZrtpCallback

This interface class defines the callback functions required by GNU ZRTP. This interface class defines the callback interface that the specific part of a GNU ZRTP must implement. The generic part of GNU ZRTP uses these mehtods to communicate with the specific part, for example to send data via the RTP/SRTP stack, to set timers and cancel timer and so on. The generiy part of GNU ZRTP needs only a few callback methods to be implemented by the specific part.

Author:

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

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ZrtpCallback.EnableSecurity
static class	ZrtpCallback.Role	This enum defines which role a ZRTP peer has.

Method Summary

Modifier and Type	Method	Description
int	activateTimer(int time)	Activate timer.
int	cancelTimer()	Cancel the active timer.
boolean	checkSASSignature(byte[] sasHash)	ZRTP calls this method to request a SAS signature check.
void	handleGoClear()	This method handles GoClear requests.
boolean	sendDataZRTP(byte[] data)	Send a ZRTP packet via RTP.
void	sendInfo(ZrtpCodes.MessageSeverity severity, EnumSet<?> subCode)	Send information messages to the hosting environment.
void	signSAS(byte[] sasHash)	Request a SAS signature.
void	srtpSecretsOff(ZrtpCallback.EnableSecurity part)	Switch off the security for the defined part.
void	srtpSecretsOn(String c, String s, boolean verified)	Switch on the security.
boolean	srtpSecretsReady(ZrtpSrtpSecrets secrets, ZrtpCallback.EnableSecurity part)	SRTP crypto data ready for the sender or receiver.
void	zrtpAskEnrollment(ZrtpCodes.InfoEnrollment info)	Inform about a PBX enrollment request.
void	zrtpInformEnrollment(ZrtpCodes.InfoEnrollment info)	Inform about PBX enrollment result.
void	zrtpNegotiationFailed(ZrtpCodes.MessageSeverity severity, EnumSet<?> subCode)	Handle ZRTP negotiation failed.
void	zrtpNotSuppOther()	ZRTP calls this method if the other side does not support ZRTP.

Method Detail

sendDataZRTP

boolean sendDataZRTP(byte[] data)

Send a ZRTP packet via RTP. ZRTP calls this method to send a ZRTP packet via the RTP session.

Parameters:

data - Points to ZRTP packet to send.

Returns:

false if sending failed, true if packet was send

activateTimer

int activateTimer(int time)

Activate timer.

Parameters:

time - The time in ms for the timer

Returns:

zero if activation failed, one if timer was activated

cancelTimer

int cancelTimer()

Cancel the active timer.

Returns:

zero if cancel action failed, one if timer was canceled

sendInfo

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

Send information messages to the hosting environment. The ZRTP implementation uses this method to send information messages to the host. Along with the message ZRTP provides a severity indicator that defines: Info, Warning, Severe, Error. Alert.

Parameters:

severity - This defines the message's severity

subCode - The subcode identifying the reason.

See Also:

ZrtpCodes.MessageSeverity

srtpSecretsReady

boolean srtpSecretsReady(ZrtpSrtpSecrets secrets,
                         ZrtpCallback.EnableSecurity part)

SRTP crypto data ready for the sender or receiver. The ZRTP implementation calls this method right after all SRTP secrets are computed and ready to be used. The parameter points to a structure that contains pointers to the SRTP secrets and a enum Role. The called method (the implementation of this abstract method) must either copy the pointers to the SRTP data or the SRTP data itself to a save place. The SrtpSecret_t structure is destroyed after the callback method returns to the ZRTP implementation. The SRTP data themselfs are ontained in the ZRtp object and are valid as long as the ZRtp object is active. TheZRtp's destructor clears the secrets. Thus the called method needs to save the pointers only, ZRtp takes care of the data. The implementing class may enable SRTP processing in this method or delay it to srtpSecertsOn().

Parameters:

secrets - A pointer to a SrtpSecret_t structure that contains all necessary data.

part - for which part (Sender or Receiver) this data is valid.

Returns:

true if secrets could be set and crypto contexts created.

srtpSecretsOff

void srtpSecretsOff(ZrtpCallback.EnableSecurity part)

Switch off the security for the defined part.

Parameters:

part - Defines for which part (sender or receiver) to switch on security

srtpSecretsOn

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. In addition ZRTP provides information about the cipher algorithm and key length for the SRTP session. This method must enable SRTP processing if it was not enabled during sertSecretsReady().

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.

handleGoClear

void handleGoClear()

This method handles GoClear requests. According to the ZRTP specification the user must be informed about a GoClear request because the ZRTP implementation switches off security if it could authenticate the GoClear packet. Note: GoClear is not yet implemented in GNU ZRTP.

zrtpNegotiationFailed

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

Handle ZRTP negotiation failed. ZRTP calls this method in case ZRTP negotiation failed. The parameters show the severity as well as the reason.

Parameters:

severity - This defines the message's severity

subCode - The subcode identifying the reason.

See Also:

ZrtpCodes.MessageSeverity

zrtpNotSuppOther

void zrtpNotSuppOther()

ZRTP 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

void zrtpAskEnrollment(ZrtpCodes.InfoEnrollment info)

Inform about a PBX enrollment request. Please refer to chapter 8.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

void zrtpInformEnrollment(ZrtpCodes.InfoEnrollment info)

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

void signSAS(byte[] sasHash)

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

boolean checkSASSignature(byte[] sasHash)

ZRTP 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 SAS hash that was signed by the other peer.

Returns:

true if the signature was ok, false otherwise.