net.java.sip.communicator.impl.neomedia.transform.srtp
Class SRTCPCryptoContext

java.lang.Object
  net.java.sip.communicator.impl.neomedia.transform.srtp.SRTCPCryptoContext

public class SRTCPCryptoContext
extends Object

SRTPCryptoContext class is the core class of SRTP implementation. There can be multiple SRTP sources in one SRTP session. And each SRTP stream has a corresponding SRTPCryptoContext object, identified by SSRC. In this way, different sources can be protected independently. SRTPCryptoContext class acts as a manager class and maintains all the information used in SRTP transformation. It is responsible for deriving encryption keys / salting keys / authentication keys from master keys. And it will invoke certain class to encrypt / decrypt (transform / reverse transform) RTP packets. It will hold a replay check db and do replay check against incoming packets. Refer to section 3.2 in RFC3711 for detailed description of cryptographic context. Cryptographic related parameters, i.e. encryption mode / authentication mode, master encryption key and master salt key are determined outside the scope of SRTP implementation. They can be assigned manually, or can be assigned automatically using some key management protocol, such as MIKEY (RFC3830) or Phil Zimmermann's ZRTP protocol.

Author:

Bing SU (nova.su@gmail.com)

Constructor Summary

SRTCPCryptoContext(long ssrcIn)
Construct an empty SRTPCryptoContext using ssrc.

SRTCPCryptoContext(long ssrcIn, byte[] masterK, byte[] masterS, SRTPPolicy policyIn)
Construct a normal SRTPCryptoContext based on the given parameters.

Method Summary

(package private) boolean	checkReplay(int index) Checks if a packet is a replayed on based on its sequence number.
void	close() Close the crypto context.
SRTCPCryptoContext	deriveContext(long ssrc) Derive a new SRTPCryptoContext for use with a new SSRC This method returns a new SRTPCryptoContext initialized with the data of this SRTPCryptoContext.
void	deriveSrtcpKeys() Derives the srtcp session keys from the master key.
int	getAuthTagLength() Get the authentication tag length of this SRTP cryptographic context
int	getMKILength() Get the MKI length of this SRTP cryptographic context
long	getSSRC() Get the SSRC of this SRTP cryptographic context
void	processPacketAESCM(RawPacket pkt, int index) Perform Counter Mode AES encryption / decryption
void	processPacketAESF8(RawPacket pkt, int index) Perform F8 Mode AES encryption / decryption
boolean	reverseTransformPacket(RawPacket pkt) Transform a SRTCP packet into a RTCP packet.
void	transformPacket(RawPacket pkt) Transform a RTP packet into a SRTP packet.

Methods inherited from class java.lang.Object

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

Constructor Detail

SRTCPCryptoContext

public SRTCPCryptoContext(long ssrcIn)

Construct an empty SRTPCryptoContext using ssrc. The other parameters are set to default null value.

Parameters:

ssrc - SSRC of this SRTPCryptoContext

SRTCPCryptoContext

public SRTCPCryptoContext(long ssrcIn,
                          byte[] masterK,
                          byte[] masterS,
                          SRTPPolicy policyIn)

Construct a normal SRTPCryptoContext based on the given parameters.

Parameters:

ssrc - the RTP SSRC that this SRTP cryptographic context protects.

masterKey - byte array holding the master key for this SRTP cryptographic context. Refer to chapter 3.2.1 of the RFC about the role of the master key.

masterSalt - byte array holding the master salt for this SRTP cryptographic context. It is used to computer the initialization vector that in turn is input to compute the session key, session authentication key and the session salt.

policy - SRTP policy for this SRTP cryptographic context, defined the encryption algorithm, the authentication algorithm, etc

Method Detail

close

public void close()

Close the crypto context. The close functions deletes key data and performs a cleanup of the crypto context. Clean up key data, maybe this is the second time. However, sometimes we cannot know if the CryptoContext was used and the application called deriveSrtpKeys(...) tah would have cleaned the key data.

getAuthTagLength

public int getAuthTagLength()

Get the authentication tag length of this SRTP cryptographic context

Returns:

the authentication tag length of this SRTP cryptographic context

getMKILength

public int getMKILength()

Get the MKI length of this SRTP cryptographic context

Returns:

the MKI length of this SRTP cryptographic context

getSSRC

public long getSSRC()

Get the SSRC of this SRTP cryptographic context

Returns:

the SSRC of this SRTP cryptographic context

transformPacket

public void transformPacket(RawPacket pkt)

Transform a RTP packet into a SRTP packet. This method is called when a normal RTP packet ready to be sent. Operations done by the transformation may include: encryption, using either Counter Mode encryption, or F8 Mode encryption, adding authentication tag, currently HMC SHA1 method. Both encryption and authentication functionality can be turned off as long as the SRTPPolicy used in this SRTPCryptoContext is requires no encryption and no authentication. Then the packet will be sent out untouched. However this is not encouraged. If no SRTP feature is enabled, then we shall not use SRTP TransformConnector. We should use the original method (RTPManager managed transportation) instead.

Parameters:

pkt - the RTP packet that is going to be sent out

reverseTransformPacket

public boolean reverseTransformPacket(RawPacket pkt)

Transform a SRTCP packet into a RTCP packet. This method is called when a SRTCP packet was received. Operations done by the this operation include: Authentication check, Packet replay check and decryption. Both encryption and authentication functionality can be turned off as long as the SRTPPolicy used in this SRTPCryptoContext requires no encryption and no authentication. Then the packet will be sent out untouched. However this is not encouraged. If no SRTCP feature is enabled, then we shall not use SRTP TransformConnector. We should use the original method (RTPManager managed transportation) instead.

Parameters:

pkt - the received RTCP packet

Returns:

true if the packet can be accepted false if authentication or replay check failed

processPacketAESCM

public void processPacketAESCM(RawPacket pkt,
                               int index)

Perform Counter Mode AES encryption / decryption

Parameters:

pkt - the RTP packet to be encrypted / decrypted

processPacketAESF8

public void processPacketAESF8(RawPacket pkt,
                               int index)

Perform F8 Mode AES encryption / decryption

Parameters:

pkt - the RTP packet to be encrypted / decrypted

checkReplay

boolean checkReplay(int index)

Checks if a packet is a replayed on based on its sequence number. This method supports a 64 packet history relative the the given sequence number. Sequence Number is guaranteed to be real (not faked) through authentication.

Parameters:

index - index number of the SRTCP packet

Returns:

true if this sequence number indicates the packet is not a replayed one, false if not

deriveSrtcpKeys

public void deriveSrtcpKeys()

Derives the srtcp session keys from the master key.

deriveContext

public SRTCPCryptoContext deriveContext(long ssrc)

Derive a new SRTPCryptoContext for use with a new SSRC This method returns a new SRTPCryptoContext initialized with the data of this SRTPCryptoContext. Replacing the SSRC, Roll-over-Counter, and the key derivation rate the application cab use this SRTPCryptoContext to encrypt / decrypt a new stream (Synchronization source) inside one RTP session. Before the application can use this SRTPCryptoContext it must call the deriveSrtpKeys method.

Parameters:

ssrc - The SSRC for this context

Returns:

a new SRTPCryptoContext with all relevant data set.