org.mobicents.media.server.impl.rtp.crypto

Class SRTPCryptoContext

java.lang.Object

org.mobicents.media.server.impl.rtp.crypto.SRTPCryptoContext

public class SRTPCryptoContext
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), SDES (RFC4568) or Phil Zimmermann's ZRTP protocol (RFC6189).

Author:

Bing SU ([email protected])

Constructor Summary

Constructors

Constructor and Description
SRTPCryptoContext(long ssrcIn) Construct an empty SRTPCryptoContext using ssrc.
SRTPCryptoContext(long ssrcIn, int rocIn, long kdr, byte[] masterK, byte[] masterS, SRTPPolicy policyIn) Construct a normal SRTPCryptoContext based on the given parameters.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Close the crypto context.
SRTPCryptoContext	deriveContext(long ssrc, int roc, long deriveRate) Derive a new SRTPCryptoContext for use with a new SSRC This method returns a new SRTPCryptoContext initialized with the data of this SRTPCryptoContext.
void	deriveSrtpKeys(long index) Derives the srtp 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
int	getROC() Get the Roll-Over-Counter of this SRTP cryptographic context
long	getSSRC() Get the SSRC of this SRTP cryptographic context
void	processPacketAESCM(RawPacket pkt) Perform Counter Mode AES encryption / decryption
void	processPacketAESF8(RawPacket pkt) Perform F8 Mode AES encryption / decryption
boolean	reverseTransformPacket(RawPacket pkt) Transform a SRTP packet into a RTP packet.
void	setROC(int rocIn) Set the Roll-Over-Counter of this SRTP cryptographic context
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

SRTPCryptoContext

public SRTPCryptoContext(long ssrcIn)

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

Parameters:

ssrcIn - SSRC of this SRTPCryptoContext

SRTPCryptoContext

public SRTPCryptoContext(long ssrcIn,
                 int rocIn,
                 long kdr,
                 byte[] masterK,
                 byte[] masterS,
                 SRTPPolicy policyIn)

Construct a normal SRTPCryptoContext based on the given parameters.

Parameters:

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

rocIn - the initial Roll-Over-Counter according to RFC 3711. These are the upper 32 bit of the overall 48 bit SRTP packet index. Refer to chapter 3.2.1 of the RFC.

kdr - the key derivation rate defines when to recompute the SRTP session keys. Refer to chapter 4.3.1 in the RFC.

masterK - 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.

masterS - 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.

policyIn - 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(...) .

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

getROC

public int getROC()

Get the Roll-Over-Counter of this SRTP cryptographic context

Returns:

the Roll-Over-Counter of this SRTP cryptographic context

setROC

public void setROC(int rocIn)

Set the Roll-Over-Counter of this SRTP cryptographic context

Parameters:

rocIn - the Roll-Over-Counter 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 SRTP packet into a RTP packet. This method is called when a SRTP packet is 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 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 just received

Returns:

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

processPacketAESCM

public void processPacketAESCM(RawPacket pkt)

Perform Counter Mode AES encryption / decryption

Parameters:

pkt - the RTP packet to be encrypted / decrypted

processPacketAESF8

public void processPacketAESF8(RawPacket pkt)

Perform F8 Mode AES encryption / decryption

Parameters:

pkt - the RTP packet to be encrypted / decrypted

deriveSrtpKeys

public void deriveSrtpKeys(long index)

Derives the srtp session keys from the master key

Parameters:

index - the 48 bit SRTP packet index

deriveContext

public SRTPCryptoContext deriveContext(long ssrc,
                              int roc,
                              long deriveRate)

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

roc - The Roll-Over-Counter for this context

deriveRate - The key derivation rate for this context

Returns:

a new SRTPCryptoContext with all relevant data set.