Package gnu.java.zrtp

Class ZRtp

  • public class ZRtp
extends Object
    The main ZRTP class. This is the main class of the RTP/SRTP independent part of the GNU ZRTP. It handles the ZRTP HMAC, DH, and other data management. The user of this class needs to know only a few methods and needs to provide only a few external functions to connect to a Timer mechanism and to send data via RTP and SRTP. Refer to the ZrtpCallback class to get detailed information regarding the callback methods required by GNU RTP. The class ZRTPTransformEngine is the Java JMF specific implementation that extends standard Java JMF and the related RTP transport. Refer to the documentation of ZRTPTransformEngine to get more information about the usage of ZRtp and associated classes. The main entry into the ZRTP class is the processExtensionHeader() method. This class does not directly handle the protocol states, timers, and packet resend. The protocol state engine is responsible for these actions. Example how to use ZRtp: 
       transConnector = (ZrtpTransformConnector)TransformManager.createZRTPConnector(sa);
   zrtpEngine = transConnector.getEngine();
   zrtpEngine.setUserCallback(new MyCallback());
   if (!zrtpEngine.initialize("test_t.zid"))
       System.out.println("initialize failed");
 
    zrtpEngine.startZrtpEngine();
    Author:
    Werner Dittmann <Werner.Dittmann@t-online.de>
    See Also:
    ZrtpCallback

    • Method Detail

      • startZrtpEngine

        public void startZrtpEngine()
        Kick off the ZRTP protocol engine. This method calls the ZrtpStateClass#evInitial() state of the state engine. After this call we are able to process ZRTP packets from our peer and to process them.

      • stopZrtp

        public void stopZrtp()
        Stop ZRTP security.

      • processZrtpMessage

        public void processZrtpMessage​(byte[] extHeader,
                               int ssrc)
        Process RTP extension header. This method expects to get a pointer to the extension header of a RTP packet. The method checks if this is really a ZRTP packet. If this check fails the method returns 0 (false) in case this is not a ZRTP packet. We return a 1 if we processed the ZRTP extension header and the caller may process RTP data after the extension header as usual. The method return -1 the call shall dismiss the packet and shall not forward it to further RTP processing.
        Parameters:
        extHeader - A pointer to the first byte of the extension header. Refer to RFC3550.

      • processTimeout

        public void processTimeout()
        Process a timeout event. We got a timeout from the timeout provider. Forward it to the protocol state engine.

      • setAuxSecret

        public void setAuxSecret​(byte[] data)
        Set the auxiliary secret. Use this method to set the auxiliary secret data. Refer to ZRTP specification, chapter 4.3 ff
        Parameters:
        data - Points to the secret data.

      • isEnrollmentMode

        public boolean isEnrollmentMode()
        Check the state of the enrollment mode. If true then we will set the enrollment flag (E) in the confirm packets and performs the enrollment actions. A MitM (PBX) enrollment service started this ZRTP session. Can be set to true only if mitmMode is also true.
        Returns:
        status of the enrollmentMode flag.

      • setEnrollmentMode

        public void setEnrollmentMode​(boolean enrollmentMode)
        Check the state of the enrollment mode. If true then we will set the enrollment flag (E) in the confirm packets and perform the enrollment actions. A MitM (PBX) enrollment service must sets this mode to true. Can be set to true only if mitmMode is also true.
        Parameters:
        enrollmentMode - defines the new state of the enrollmentMode flag

      • isPeerEnrolled

        public boolean isPeerEnrolled()
        Check if a peer's cache entry has a vaild MitM key. If true then the other peer ha a valid MtiM key, i.e. the peer has performed the enrollment procedure. A PBX ZRTP Back-2-Back application can use this function to check which of the peers is enrolled.
        Returns:
        True if the other peer has a valid Mitm key (is enrolled).

      • sendSASRelayPacket

        public boolean sendSASRelayPacket​(byte[] sh,
                                  ZrtpConstants.SupportedSASTypes render)
        Send the SAS relay packet. The method creates and sends a SAS relay packet according to the ZRTP specifications. Usually only a MitM capable user agent (PBX) uses this function.
        Parameters:
        sh - the full SAS hash value
        render - the SAS rendering algorithm

      • getSasType

        public ZrtpConstants.SupportedSASTypes getSasType()
        Get the commited SAS rendering algorithm for this ZRTP session.
        Returns:
        the commited SAS rendering algorithm

      • getSasHash

        public byte[] getSasHash()
        Get the computed SAS hash for this ZRTP session.
        Returns:
        a refernce to the byte array that contains the full SAS hash.

      • inState

        public boolean inState​(ZrtpStateClass.ZrtpStates state)
        Check current state of the ZRTP state engine
        Parameters:
        state - The state to check.
        Returns:
        Returns true id ZRTP engine is in the given state, false otherwise.

      • SASVerified

        public void SASVerified()
        Set SAS as verified. Call this method if the user confirmed (verfied) the SAS. ZRTP remembers this together with the retained secrets data.

      • resetSASVerified

        public void resetSASVerified()
        Reset the SAS verfied flag for the current active user's retained secrets.

      • setRs2Valid

        public void setRs2Valid()

      • getHelloHash

        public String getHelloHash​(int index)
        Get the ZRTP Hello Hash data. Use this method to get the ZRTP Hello Hash data. The method returns the data as a string.
        Parameters:
        index - Hello hash of the Hello packet identified by index. Index must be 0 <= index < SUPPORTED_ZRTP_VERSIONS.
        Returns:
        a string containing the Hello hash value as hex-digits. The hello hash is available immediately after class instantiation.

      • getHelloHashSep

        public String[] getHelloHashSep​(int index)
        Get the ZRTP Hello Hash data - separate strings. Use this method to get the ZRTP Hello Hash data. The method returns the data as separate strings.
        Parameters:
        index - Hello hash of the Hello packet identified by index. Index must be 0 <= index < SUPPORTED_ZRTP_VERSIONS.
        Returns:
        String array containing the version string at offset 0, the Hello hash value as hex-digits at offset 1. Hello hash is available immediately after class instantiation.

      • getPeerHelloHash

        public String getPeerHelloHash()
        Get the peer's Hello Hash data. Use this method to get the peer's Hello Hash data. The method returns the data as a string.
        Returns:
        a String containing the Hello hash value as hex-digits. Peer Hello hash is available after we received a Hello packet from our peer. If peer's hello hash is not available return null.

      • getPeerHelloHashSep

        public String[] getPeerHelloHashSep()
        Get the peer's Hello Hash data - separate strings. Use this method to get the peer's Hello Hash data. The method returns the data as separate strings.
        Returns:
        String array containing the version string at offset 0, the Hello hash value as hex-digits at offset 1. Peer Hello hash is available after we received a Hello packet from our peer. If peer's hello hash is not available return null.

      • getMultiStrParams

        public byte[] getMultiStrParams()
        Get Multi-stream parameters. Use this method to get the Multi-stream that were computed during the ZRTP handshake. An application may use these parameters to enable multi-stream processing for an associated SRTP session. Refer to chapter 5.4.2 in the ZRTP specification for further details and restriction how and when to use multi-stream mode.
        Returns:
        a string that contains the multi-stream parameters. The application must not modify the contents of this string, it is opaque data. The application may hand over this string to a new ZrtpQueue instance to enable multi-stream processing for this ZrtpQueue. If ZRTP was not started or ZRTP is not yet in secure state the method returns an empty string.

      • setMultiStrParams

        public void setMultiStrParams​(byte[] parameters)
        Set Multi-stream parameters. Use this method to set the parameters required to enable Multi-stream processing of ZRTP. The multi-stream parameters must be set before the application starts the ZRTP protocol engine. Refer to chapter 5.4.2 in the ZRTP specification for further details of multi-stream mode.
        Parameters:
        parameters - A byte array that contains the multi-stream parameters. See also getMultiStrParams()

      • isMultiStream

        public boolean isMultiStream()
        Check if this ZRTP use Multi-stream. Use this method to check if this ZRTP instance uses multi-stream. Even if the application provided multi-stram parameters it may happen that full DH mode was used. Refer to chapters 5.2 and 5.4.2 in the ZRTP # when this may happen.
        Returns:
        True if multi-stream is used, false otherwise.

      • isMultiStreamAvailable

        public boolean isMultiStreamAvailable()
        Check if the other ZRTP client supports Multi-stream. Use this method to check if the other ZRTP client supports Multi-stream mode.
        Returns:
        True if multi-stream is available, false otherwise.

      • acceptEnrollment

        public void acceptEnrollment​(boolean accepted)
        Accept a PBX enrollment request. If a PBX service asks to enroll the MiTM key and the user accepts this request, for example by pressing an OK button, the client application shall call this method and set the parameter accepted to true. If the user does not accept the request set the parameter to false.
        Parameters:
        accepted - True if the enrollment request is accepted, false otherwise.

      • setSignatureData

        public boolean setSignatureData​(byte[] data)
        Set signature data This functions stores signature data and transmitts it during ZRTP processing to the other party as part of the Confirm packets. Refer to chapters 7.2ff.
        Parameters:
        data - The signature data including the signature type block. The method copies this data into the Confirm packet at signature type block. The length of the signature data must be multiple of 4 bytes.
        Returns:
        True if the method stored the data, false otherwise.

      • getSignatureData

        public byte[] getSignatureData()
        Get signature data This functions returns signature data that was receivied during ZRTP processing. Refer to chapters 7.2ff.
        Returns:
        Signature data in a byte array.

      • getSignatureLength

        public int getSignatureLength()
        Get length of signature data This functions returns the length of signature data that was receivied during ZRTP processing. Refer to chapters 6.7 and 8.2.
        Returns:
        Length in bytes of the received signature data. The method returns zero if no signature data avilable.

      • conf2AckSecure

        public void conf2AckSecure()
        Emulate a Conf2Ack packet. This method emulates a Conf2Ack packet. According to ZRTP specification the first valid SRTP packet that the Initiator receives must switch on secure mode. Refer to chapter 5.6 in the specificaton

      • getPeerZid

        public byte[] getPeerZid()
        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.

      • getTimeoutValue

        public long getTimeoutValue()
        Get remaining time before a "ZRTP not supported by other party" is reported. This function calls the protocol state engine to determine how many time is left in ZRTP's discovery phase (Hello phase).
        Returns:
        Time left in milliseconds.

      • getNumberSupportedVersions

        public int getNumberSupportedVersions()
        Get number of supported ZRTP protocol versions.
        Returns:
        the number of supported ZRTP protocol versions.

      • getCurrentProtocolVersion

        public int getCurrentProtocolVersion()
        Get negotiated ZRTP protocol version.
        Returns:
        the integer representation of the negotiated ZRTP protocol version.

      • sendPacketZRTP

        protected boolean sendPacketZRTP​(ZrtpPacketBase packet)
        Send a ZRTP packet. The state engines calls this method to send a packet via the RTP stack.
        Parameters:
        packet - Points to the ZRTP packet.
        Returns:
        false if sending failed, true if packet was send

      • activateTimer

        protected int activateTimer​(int tm)
        Activate a Timer using the host callback.
        Parameters:
        tm - The time in milliseconds.
        Returns:
        zero if activation failed, one if timer was activated

      • cancelTimer

        protected int cancelTimer()
        Cancel the active Timer using the host callback.
        Returns:
        zero if activation failed, one if timer was activated

      • prepareHello

        protected ZrtpPacketHello prepareHello()
        Prepare a Hello packet. Just take the preinitialized Hello packet and return it. No further processing required.
        Returns:
        A pointer to the initialized Hello packet.

      • prepareHelloAck

        protected ZrtpPacketHelloAck prepareHelloAck()
        Prepare a HelloAck packet. Just take the preinitialized HelloAck packet and return it. No further processing required.
        Returns:
        A pointer to the initialized HelloAck packet.

      • prepareCommit

        protected ZrtpPacketCommit prepareCommit​(ZrtpPacketHello hello,
                                         ZrtpCodes.ZrtpErrorCodes[] errMsg)
        Prepare a Commit packet. We have received a Hello packet from our peer. Check the offers it makes to us and select the most appropriate. Using the selected values prepare a Commit packet and return it to protocol state engine.
        Parameters:
        hello - Points to the received Hello packet
        Returns:
        A pointer to the prepared Commit packet

      • prepareDHPart1

        protected ZrtpPacketDHPart prepareDHPart1​(ZrtpPacketCommit commit,
                                          ZrtpCodes.ZrtpErrorCodes[] errMsg)
        Prepare the DHPart1 packet. This method prepares a DHPart1 packet. The input to the method is always a Commit packet received from the peer. Also we are in the role of the Responder. When we receive a Commit packet we get the selected ciphers, hashes, etc and cross-check if this is ok. Then we need to initialize a set of DH keys according to the selected cipher. Using this data we prepare our DHPart1 packet.

      • prepareDHPart2

        protected ZrtpPacketDHPart prepareDHPart2​(ZrtpPacketDHPart dhPart1,
                                          ZrtpCodes.ZrtpErrorCodes[] errMsg)
        Prepare the DHPart2 packet. This method returns the prepared DHPart2 packet. The input to the method is always a DHPart1 packet received from the peer. Our peer sends the DH1Part as response to our Commit packet. Thus we are in the role of the Initiator. The method uses the DHPart1 data to create the Initiator's secrets.

      • prepareConfirm1

        protected ZrtpPacketConfirm prepareConfirm1​(ZrtpPacketDHPart dhPart2,
                                            ZrtpCodes.ZrtpErrorCodes[] errMsg)
        Prepare the Confirm1 packet. This method prepare the Confirm1 packet. The input to this method is the DHPart2 packect received from our peer. The peer sends the DHPart2 packet as response of our DHPart1. Here we are in the role of the Responder. The method uses the data of the DHPart2 packet to create the responder's secrets.

      • prepareConfirm2

        protected ZrtpPacketConfirm prepareConfirm2​(ZrtpPacketConfirm confirm1,
                                            ZrtpCodes.ZrtpErrorCodes[] errMsg)
        Prepare the Confirm2 packet. This method prepare the Confirm2 packet. The input to this method is the Confirm1 packet received from our peer. The peer sends the Confirm1 packet as response of our DHPart2. Here we are in the role of the Initiator

      • prepareConf2Ack

        protected ZrtpPacketConf2Ack prepareConf2Ack​(ZrtpPacketConfirm confirm2,
                                             ZrtpCodes.ZrtpErrorCodes[] errMsg)
        Prepare the Conf2Ack packet. This method prepare the Conf2Ack packet. The input to this method is the Confirm2 packet received from our peer. The peer sends the Confirm2 packet as response of our Confirm1. Here we are in the role of the Initiator

      • prepareErrorAck

        protected ZrtpPacketErrorAck prepareErrorAck​(ZrtpPacketError epkt)
        Prepare the ErrorAck packet. This method prepares the ErrorAck packet. The input to this method is the Error packet received from the peer.

      • prepareError

        protected ZrtpPacketError prepareError​(ZrtpCodes.ZrtpErrorCodes errMsg)
        Prepare the Error packet. This method prepares the Error packet. The input to this method is the error code to be included into the message.

      • preparePingAck

        protected ZrtpPacketPingAck preparePingAck​(ZrtpPacketPing ppkt)
        Prepare the PingAck packet. This method prepares the PingAck packet.

      • compareCommit

        protected int compareCommit​(ZrtpPacketCommit commit)
        Compare the hvi values. Compare a received Commit packet with our Commit packet and returns which Commit packt is "more important". See chapter 5.2 to get further information how to compare Commit packets.
        Parameters:
        commit - Pointer to the peer's commit packet we just received.
        Returns:
        <0 if our Commit packet is "less important" >0 if ours is "more important" 0 shouldn't happen because we compare crypto hashes

      • verifyH2

        protected boolean verifyH2​(ZrtpPacketCommit commit)
        Verify the H2 hash image. Verifies the H2 hash contained in a received commit message. This functions just verifies H2 but does not store it.
        Parameters:
        commit - Pointer to the peer's commit packet we just received.
        Returns:
        true if H2 is ok and verified false if H2 could not be verified

      • sendInfo

        protected 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, Error, Alert. Refer to the MessageSeverity enum in the ZrtpCallback class.
        Parameters:
        severity - This defines the message's severity
        subCode - The subcode identifying the reason.
        See Also:
        ZrtpCodes.MessageSeverity

      • zrtpNegotiationFailed

        protected void zrtpNegotiationFailed​(ZrtpCodes.MessageSeverity severity,
                                     EnumSet<?> subCode)
        ZRTP state engine calls this if the negotiation failed. ZRTP calls this method in case ZRTP negotiation failed. The parameters show the severity as well as some explanatory text.
        Parameters:
        severity - This defines the message's severity
        subCode - The subcode identifying the reason.
        See Also:
        ZrtpCodes.MessageSeverity

      • zrtpNotSuppOther

        protected void zrtpNotSuppOther()
        ZRTP state engine 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,

      • srtpSecretsReady

        protected boolean srtpSecretsReady​(ZrtpCallback.EnableSecurity part)
        Signal SRTP secrets are ready. This method calls a callback method to inform the host that the SRTP secrets are ready.
        Parameters:
        part - Defines for which part (sender or receiver) to switch on security
        Returns:
        Returns false if something went wrong during initialization of SRTP context. Propagate error back to state engine.

      • srtpSecretsOff

        protected void srtpSecretsOff​(ZrtpCallback.EnableSecurity part)
        Switch off SRTP secrets. This method calls a callback method to inform the host that the SRTP secrets shall be cleared.
        Parameters:
        part - Defines for which part (sender or receiver) to clear