The ZRTP implementation issues information messages to inform the user about ongoing processing, unusual behavior, or alerts in case of severe problems. Each main severity code has a number of sub-codes that specify the exact nature of the problem.

An application gets message severity codes and the associated sub-codes via ZrtpUserCallback methods, for example the ‘showMessage(…)’ method.

After the description of the severity codes and the sub-codes a short description of relevant ZrtpUserCallback methods follow.

Main severity levels

Info

    keeps the user or client informed about ongoing processing and
    security setup. The enumeration InfoCodes defines the subcodes.

Warning

    is an information about some security issues, e.g. if
    a retained shared secret is corrupted. ZRTP will establish a secure 
    session (SRTP) but the user shall always check the SAS with its the
    other party.

Severe

    is used if an error occured during ZRTP protocol usage.
    In case of *Severe* ZRTP will *not* establish a secure session.

ZrtpError

    shows a ZRTP security problem. GNU ZRTP of course will *not* 
    establish a secure session.

Sub codes for the severity level ‘Info’

InfoHelloReceived

    A Hello packet was received. This show that the other party
    (client) also supports ZRTP. The ZRTP implementation continues
    with ZRTP handshake. No special action required. The client may
    use this subcode to signal the start of the ZRTP handshake to the
    user, for example via the UI

InfoCommitDHGenerated

    Generated a public DH key during preparation of the Commit
    packet. Pure information, no action required, may be included
    into log files.

InfoRespCommitReceived

    The ZRTP Responder received a Commit packet and prepares the
    DHPart1 packet. Pure information, no action required, may be included
    into log files.

InfoDH1DHGenerated

    The ZRTP Responder generated a public DH key during preparation
    of its DH1Part packet. Pure information, no action required, may
    be included into log files.

InfoInitDH1Received

    The ZRTP Initiator received a DHPart1 packet and prepares the
    DHPart2 packet. Pure information, no action required, may
    be included into log files.

InfoRespDH2Received

    The ZRTP Responder received a DHPart2 packet and prepares the
    Confirm1 packet. Pure information, no action required, may
    be included into log files.

InfoInitConf1Received

    The ZRTP Initiator received a Confirm1 packet and prepares the
    Confirm2 packet. Pure information, no action required, may
    be included into log files.

InfoRespConf2Received

    The ZRTP Responder received a Confirm2 packet and prepares the
    Conf2Ack packet. Pure information, no action required, may
    be included into log files.

InfoRSMatchFound

    This informs the client/user that one of the retained secrets
    matches and key continuity is ok. See warning code
    ‘WarningNoExpectedRSMatch’ in case of problems. Pure
    information, no action required, may be included into log
    files.

InfoSecureStateOn

    ZRTP entered secure state. Only after the client receives this
    subcode the ZRTP state engine has entered secure state. Other
    information send before (see the methods ‘secureOn(…)’ ans
    showSAS(…)) inform the client about the used cipher for SRTP
    or the SAS. The client may now switch on the “secure call” flags
    if not already done before. After the client got this subcode
    the client may create a new ZRTP session using multi-stream mode.

InfoSecureStateOff

    No more security for this session and ZRTP left secure state. The
    client must switch off all security indicators.

Sub-codes for severity level ‘Warning’

WarningDHAESmismatch

    Not used. May be used later if new algorithms a introduced.

WarningGoClearReceived

    Not yet used because ‘goClear’ handling is not implemented.

WarningDHShort

    Not used. May be used later if new algorithms a introduced.

WarningNoRSMatch

    No retained shared secrets available. The user shall must
    verify SAS with the other party. The UI shall display this
    information.

WarningCRCmismatch

    Internal ZRTP packet checksum mismatch. The packet was
    dropped. If this happens often this may indicate a bad
    connection that corrupts data during transmisson. In rare cases
    and if it happens regularly this could also signal a
    denial-of-serice attack. The UI may display this
    information, must be included in log file. Maybe the UI
    implements a counter for this subcode and displays a warning
    after the counter reaches a specific threshold.

WarningSRTPauthError

    Dropping packet because SRTP authentication failed. The packet
    was dropped. This may happen if the data was corrupted during
    transmission or during the very first packets after switching to
    secure mode. In rare cases and if this happens later during a
    secure session this could also signal a denial-of-serice
    attack. The UI may display this information, must be included in
    log file. Maybe the UI implements a counter for this subcode and
    displays a warning after the counter reaches a specific
    threshold.

WarningSRTPreplayError

    Dropping packet because SRTP replay check failed. The packet was
    dropped. A duplicate SRTP packet was detected. This may happen if
    the data was corrupted during transmission. In rare cases and if
    this happens later during a secure session this could also signal
    a denial-of-serice attack. The UI may display this information,
    must be included in log file. Maybe the UI implements a counter
    for this subcode and displays a warning after the counter reaches
    a specific threshold.

WarningNoExpectedRSMatch

    During previous sessions with the other party’s client ZRTP
    stored some data as ‘retained shared secret’ to enable key
    continuity. During this session the other party’s client did not
    offer valid identifiers for the stored retained shared
    secrets. This can happen if the other party uses another client
    software or lost its stored shared secrets. In rare case this
    could also signal a Man-In-The-Middle (MITM) attack. Therefore
    the user shall must verify the SAS with the other party to prove
    the correct exchange ZRTP data. 

    ATTENTION: In case the SAS of both parties do not match the user
    shall drop the call immediately.

Sub-codes for severity level ‘Severe’

The ‘Severe’ subcode always signals a severe problem, in most cases problems that lead to wrong security data (SRTP keys). The ZRTP implementation stops further actions and does not negotiate SRTP keys and does not start a SRTP session. The communication continues using standard, insecure RTP. The UI must inform the user.

The following four subcodes signal that HMAC checks failed. Thus the data in the ZRTP packets are incorrect or inconsistent. This may be due to a Denial-of-Service attack.

SevereHelloHMACFailed

   Hash HMAC check of Hello failed

SevereCommitHMACFailed

   Hash HMAC check of Commit failed

SevereDH1HMACFailed

   Hash HMAC check of DHPart1 failed

SevereDH2HMACFailed

   Hash HMAC check of DHPart2 failed

The next codes usually signal software problems or lack of resources.

SevereCannotSend

   Cannot send data - Internet data connection or peer is down.

SevereProtocolError

   Internal protocol error occured. Usually some sort of software
   problem. Shall not happen :-) .

SevereNoTimer

   Cannot start a timer - some internal timer resources exhausted

SevereTooMuchRetries

   Too much retries during ZRTP negotiation. This may happen if the
   other party stops to proceed the ZRTP handshake. Usually if
   Internet connection is lost or the peer has some problems.

SevereSecurityException

   Java throwed a security exception. This is an internal Java
   security problem. Shall not happen.

ZRTP error subcodes according to the ZRTP specification chapter 6.9

This error codes signal incompatibilities or problems during ZRTP handshake. Similar to the handling of ‘Severe’ sub-code the ZRTP implementation stops further actions and does not negotiate SRTP keys and does not start a SRTP session. The communication continues using standard, insecure RTP. The UI must inform the user.

The next nine codes show compatibility or software problems. The user should be informed, the message shall go into a log file.

MalformedPacket

   Malformed packet (CRC OK, but wrong structure), usually a
   compatibility problem.

CriticalSWError

   Critical software error

UnsuppZRTPVersion

   Unsupported ZRTP version, a compatibility problem.

HelloCompMismatch

   Hello components mismatch. Hello packet does not contain all
   necessary components.

UnsuppHashType

   Hash type not supported, a compatibility problem.

UnsuppCiphertype

   Cipher type not supported, a compatibility problem.

UnsuppPKExchange

   Public key exchange not supported, a compatibility problem.

UnsuppSRTPAuthTag

   SRTP auth. tag not supported, a compatibility problem.

UnsuppSASScheme

   SAS scheme not supported, a compatibility problem.

The next error code may occur if ZRTP preshared mode is implemented and used. GNU ZRTP and GNU ZRTP4J do not implement this mode.

NoSharedSecret

   No shared secret available, DH mode required. Pre-shared mode can
   be used only it at least one retained shared secret is
   available. Only Diffie-Helman mode generates and stores retained
   shared secrets.

   The next two error codes indicate wrong or modified data during
   Diffie-Helman key exchange. In rare case this may indicate a
   MITM. 

DHErrorWrongPV

   Diffie-Helman error: bad public DH value, not usable to compute
   the shared key.

DHErrorWrongHVI

   Diffie-Helman exchange error: the internally computed hash-values
   do not match the received values. Indicates data inconsistency in
   the exchange of ZRTP messages

The next error code may occur if the ZRTP PBX trusted MiTM relay feature is used. GNU ZRTP and GNU ZRTP4J do not implement this feature.

SASuntrustedMiTM

   Received relayed SAS from untrusted MiTM.

The next two error codes indicate some problems during SRTP key validation or key generation.

ConfirmHMACWrong

   Key Authentication Error: The Confirm packet has a wrong HMAC. The
   HMAC uses a specific negotiated datum as key to validate SRTP key
   negotiation. If this check fails the SRTP keys of both parties do
   not match.

NonceReused

   To generate the SRTP keys in multi-stream mode ZRTP exchanges some
   ‘Nonce’ data. Multi-stream session that use data of the same DH
   session must not be use the same nonce.

EqualZIDHello

   Equal ZIDs in Hello - this can happen if two clients generated the
   same ZID (ZRTP Identifier). This is an extremly rare case thus
   this error may indicate a sort of replay attack.

GoClearNotAllowed

   GoClear packet received, but not allowed

Callback methods

secureOn(String cipher)

   ZRTP calls this method to inform the client which cipher algorithm
   it will use for SRTP. This call indicates that most of the
   handshake is done and SRTP is engaged, at least in parts. Which
   parts of SRTP is ready depends if the client is ZRTP Initiator or
   ZRTP Responder.

   Full secure state is indicated by the information sub-code
   ‘InfoSecureStateOn’.

secureOff()

   ZRTP calls this method to inform the client that it switched off
   SRTP secure mode and returned to normal RTP mode. The information
   subcode ‘InfoSecureStateOff’ shows that ZRTP left secure state.

showSAS(String sas, boolean verified)

   ZRTP calls this method to enable the UI to display the SAS (Short
   Authentication String). Currently GNU ZRTP and GNU ZRTP4J
   implement oly one SAS method that generates 4 characters. The
   users shall verify these charaters, for example the caller spells
   the first two characters, the called party the last two
   characters. Only if all chacaters match on both sides the users
   can be sure to have a secure session.

   The ‘verified’ parameter is set to true if both users verified and
   acknowledged the SAS during a previous session using the same
   client software or hardware. In this case the UI shall indicate
   that both users did this, for example adding a checkmark to the
   text. If not other error messages were shown (see Warning
   sub-codes above) ZRTP ensures key continuity and the users may
   omit SAS verification.

   If verified is set to ‘false’ the users shall verify the SAS.

   In multi-stream mode the SAS is not shown because multi-stream
   sessions depend on previous DH session.

zrtpNegotiationFailed(severity, subCode)

   The ZRTP negotiation failed, usually because of some severe
   problem. The parameters ‘severity’ and ‘subCode’ contain the
   detailed codes of the problem that caused the failure.

zrtpNotSuppOther()

   ZRTP calls this method if the other party did not respond to the
   ZRTP ‘Hello’ packets. This could happen if the other party does
   not support ZRTP at all or the user did not enable ZRTP. After
   ZRTP called this method it stays in a ZRTP ‘Hello’ detection state
   and will respond to ZRTP ‘Hello’ packets, for example if the other
   party enables ZRTP during the session. In this case normal ZRTP
   processing takes place and ZRTP establishes a secure session.