[sip-comm-dev] Documentation and description of ZRTP Info, Warning, and Error codes


#1

Emil,

as discussed here a more elaborate description of the
codes that ZRTP uses.

Based on this IMHO we can decide which messages the SC UI
shall display.

Regarding your note about my question:
"Also some layout of a message window or message area inside
the call window may be required?" - well, it was late yesterday :slight_smile:
What I meant: we need a nice layout and a nice way
to display the messages in the call window.

Also attached the sound files, in wav format and PCM uLaw.

Regards,
Werner

codesDoc.txt (14.1 KB)

sounds.tar (60 KB)


#2

Hi Werner,

Sorry for the delay, I was off during a few weeks. In order to be able to access it easily, I've added your documentation to the SIP Communicator website:
http://www.sip-communicator.org/index.php/Documentation/ZRTP4JMessageCodes

And linked it from the developer documentation:
http://www.sip-communicator.org/index.php/Documentation/DeveloperDocumentation

Cheers,
romain

路路路

On 2008/10/21, at 17:22, Werner Dittmann wrote:

/**
* Copyright (C) 2006-2008 Werner Dittmann
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Authors: Werner Dittmann <Werner.Dittmann@t-online.de>
*/

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, vor example the
'showMessage(...)' method.

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

The main severity levels and their meaning are:

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 follwing 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 :slight_smile: .

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.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net


#3

Hi Romain,

no problem at all :slight_smile: . I'm just preparing a new release of ZRTP4J
which will become version 1.4.0 . This version is compliant to the
latest draft of ZRTP. This draft version (it's version 10) is proposed
to become the IETF RFC. If all goes well then this will be the "official"
release of ZRTP4J because it implements the RFC (modulo programming
errors).

Regards,
Werner

Romain KUNTZ schrieb:

路路路

Hi Werner,

Sorry for the delay, I was off during a few weeks. In order to be able to access it easily, I've added your documentation to the SIP Communicator website:
http://www.sip-communicator.org/index.php/Documentation/ZRTP4JMessageCodes

And linked it from the developer documentation:
http://www.sip-communicator.org/index.php/Documentation/DeveloperDocumentation

Cheers,
romain

On 2008/10/21, at 17:22, Werner Dittmann wrote:

/**
* Copyright (C) 2006-2008 Werner Dittmann
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Authors: Werner Dittmann <Werner.Dittmann@t-online.de>
*/

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, vor example the
'showMessage(...)' method.

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

The main severity levels and their meaning are:

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 follwing 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 :slight_smile: .

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.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net


#4

Hi Werner,

no problem at all :slight_smile: . I'm just preparing a new release of ZRTP4J
which will become version 1.4.0 . This version is compliant to the
latest draft of ZRTP. This draft version (it's version 10) is proposed
to become the IETF RFC. If all goes well then this will be the "official"
release of ZRTP4J because it implements the RFC (modulo programming
errors).

That's a great news! Looking forward to integrate it :slight_smile:

romain

路路路

On 2008/11/16, at 8:58, Werner Dittmann wrote:

Romain KUNTZ schrieb:

Hi Werner,
Sorry for the delay, I was off during a few weeks. In order to be able to access it easily, I've added your documentation to the SIP Communicator website:
http://www.sip-communicator.org/index.php/Documentation/ZRTP4JMessageCodes
And linked it from the developer documentation:
http://www.sip-communicator.org/index.php/Documentation/DeveloperDocumentation Cheers,
romain
On 2008/10/21, at 17:22, Werner Dittmann wrote:

/**
* Copyright (C) 2006-2008 Werner Dittmann
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Authors: Werner Dittmann <Werner.Dittmann@t-online.de>
*/

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, vor example the
'showMessage(...)' method.

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

The main severity levels and their meaning are:

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 follwing 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 :slight_smile: .

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.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net