org.restcomm.media.stun.messages.attributes.general

Class MessageIntegrityAttribute

java.lang.Object

org.restcomm.media.stun.messages.attributes.StunAttribute

org.restcomm.media.stun.messages.attributes.general.MessageIntegrityAttribute

All Implemented Interfaces:

ContextDependentAttribute

public class MessageIntegrityAttribute
extends StunAttribute
implements ContextDependentAttribute

The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [RFC2104] of the STUN message. The MESSAGE-INTEGRITY attribute can be present in any STUN message type. Since it uses the SHA1 hash, the HMAC will be 20 bytes. The text used as input to HMAC is the STUN message, including the header, up to and including the attribute preceding the MESSAGE-INTEGRITY attribute. With the exception of the FINGERPRINT attribute, which appears after MESSAGE-INTEGRITY, agents MUST ignore all other attributes that follow MESSAGE-INTEGRITY. The key for the HMAC depends on whether long-term or short-term credentials are in use. For long-term credentials, the key is 16 bytes:

          key = MD5(username ":" realm ":" SASLprep(password))
 

That is, the 16-byte key is formed by taking the MD5 hash of the result of concatenating the following five fields: (1) the username, with any quotes and trailing nulls removed, as taken from the USERNAME attribute (in which case SASLprep has already been applied); (2) a single colon; (3) the realm, with any quotes and trailing nulls removed; (4) a single colon; and (5) the password, with any trailing nulls removed and after processing using SASLprep. For example, if the username was 'user', the realm was 'realm', and the password was 'pass', then the 16-byte HMAC key would be the result of performing an MD5 hash on the string 'user:realm:pass', the resulting hash being 0x8493fbc53ba582fb4c044c456bdc40eb.

For short-term credentials:

 key = SASLprep(password)
 

where MD5 is defined in RFC 1321 [RFC1321] and SASLprep() is defined in RFC 4013 [RFC4013].

The structure of the key when used with long-term credentials facilitates deployment in systems that also utilize SIP. Typically, SIP systems utilizing SIP's digest authentication mechanism do not actually store the password in the database. Rather, they store a value called H(A1), which is equal to the key defined above.

Based on the rules above, the hash used to construct MESSAGE- INTEGRITY includes the length field from the STUN message header. Prior to performing the hash, the MESSAGE-INTEGRITY attribute MUST be inserted into the message (with dummy content). The length MUST then be set to point to the length of the message up to, and including, the MESSAGE-INTEGRITY attribute itself, but excluding any attributes after it. Once the computation is performed, the value of the MESSAGE-INTEGRITY attribute can be filled in, and the value of the length in the STUN header can be set to its correct value -- the length of the entire message. Similarly, when validating the MESSAGE-INTEGRITY, the length field should be adjusted to point to the end of the MESSAGE-INTEGRITY attribute prior to calculating the HMAC. Such adjustment is necessary when attributes, such as FINGERPRINT, appear after MESSAGE-INTEGRITY.

Field Summary

Fields

Modifier and Type	Field and Description
static char	DATA_LENGTH
static String	HMAC_SHA1_ALGORITHM
static String	NAME

Fields inherited from class org.restcomm.media.stun.messages.attributes.StunAttribute

ALTERNATE_SERVER, attributeType, CHANGE_REQUEST, CHANGED_ADDRESS, CHANNEL_NUMBER, DATA, DESTINATION_ADDRESS, DONT_FRAGMENT, ERROR_CODE, EVEN_PORT, FINGERPRINT, HEADER_LENGTH, ICE_CONTROLLED, ICE_CONTROLLING, LIFETIME, MAGIC_COOKIE, MAPPED_ADDRESS, MESSAGE_INTEGRITY, NONCE, PASSWORD, PRIORITY, REALM, REFLECTED_FROM, REMOTE_ADDRESS, REQUESTED_TRANSPORT, RESERVATION_TOKEN, RESPONSE_ADDRESS, SOFTWARE, SOURCE_ADDRESS, UNKNOWN_ATTRIBUTES, UNKNOWN_OPTIONAL_ATTRIBUTE, USE_CANDIDATE, USERNAME, XOR_MAPPED_ADDRESS, XOR_ONLY, XOR_PEER_ADDRESS, XOR_RELAYED_ADDRESS

Constructor Summary

Constructors

Constructor and Description
MessageIntegrityAttribute()

Method Summary

Methods

Modifier and Type	Method and Description
static byte[]	calculateHmacSha1(byte[] message, int offset, int length, byte[] key) Encodes message using key and the HMAC-SHA1 algorithm as per RFC 2104 and returns the resulting byte array.
protected void	decodeAttributeBody(byte[] data, char offset, char length) Sets this attribute's fields according to attributeValue array.
byte[]	encode() Returns a binary representation of this attribute.
byte[]	encode(byte[] data, int offset, int length) Returns a binary representation of this attribute.
boolean	equals(Object other) Compares two STUN Attributes.
char	getDataLength() Returns the length of this attribute's body.
byte[]	getHmacSha1Content()
byte[]	getKey()
String	getMedia()
String	getName() Returns the human readable name of this attribute.
String	getUsername()
void	setHmacSha1Content(byte[] hmacSha1Content)
void	setKey(byte[] key)
void	setMedia(String media) Sets the media name that we should use to get the corresponding remote key (short-term authentication only).
void	setUsername(String username) Sets the username that we should use to obtain an encryption key (password) that the encode() method should use when creating the content of this message.
String	toString()

Methods inherited from class org.restcomm.media.stun.messages.attributes.StunAttribute

getAttributeType, getLocationInMessage, setAttributeType, setLocationInMessage

Methods inherited from class java.lang.Object

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

Field Detail

NAME

public static final String NAME

See Also:

Constant Field Values

HMAC_SHA1_ALGORITHM

public static final String HMAC_SHA1_ALGORITHM

See Also:

Constant Field Values

DATA_LENGTH

public static final char DATA_LENGTH

See Also:

Constant Field Values

Constructor Detail

MessageIntegrityAttribute

public MessageIntegrityAttribute()

Method Detail

getKey

public byte[] getKey()

setKey

public void setKey(byte[] key)

getHmacSha1Content

public byte[] getHmacSha1Content()

setHmacSha1Content

public void setHmacSha1Content(byte[] hmacSha1Content)

getUsername

public String getUsername()

setUsername

public void setUsername(String username)

Sets the username that we should use to obtain an encryption key (password) that the encode() method should use when creating the content of this message.

Parameters:

username - the username that we should use to obtain an encryption key (password) that the encode() method should use when creating the content of this message.

getMedia

public String getMedia()

setMedia

public void setMedia(String media)

Sets the media name that we should use to get the corresponding remote key (short-term authentication only).

Parameters:

media - name

calculateHmacSha1

public static byte[] calculateHmacSha1(byte[] message,
                       int offset,
                       int length,
                       byte[] key)
                                throws IllegalArgumentException

Encodes message using key and the HMAC-SHA1 algorithm as per RFC 2104 and returns the resulting byte array. This is a utility method that generates content for the MessageIntegrityAttribute regardless of the credentials being used (short or long term).

Parameters:

message - the STUN message that the resulting content will need to travel in.

offset - the index where data starts in message.

length - the length of the data in message that the method should consider.

key - the key that we should be using for the encoding (which depends on whether we are using short or long term credentials).

Returns:

the HMAC that should be used in a MessageIntegrityAttribute transported by message.

Throws:

IllegalArgumentException - if the encoding fails for some reason.

encode

public byte[] encode(byte[] data,
            int offset,
            int length)

Description copied from interface: ContextDependentAttribute

Returns a binary representation of this attribute.

Specified by:

encode in interface ContextDependentAttribute

Parameters:

data - the content of the message that this attribute will be transported in

offset - the content-related offset where the actual content starts.

length - the length of the content in the content array.

Returns:

a binary representation of this attribute valid for the message with the specified content.

getDataLength

public char getDataLength()

Description copied from class: StunAttribute

Returns the length of this attribute's body.

Specified by:

getDataLength in class StunAttribute

Returns:

the length of this attribute's value.

getName

public String getName()

Description copied from class: StunAttribute

Returns the human readable name of this attribute. Attribute names do not really matter from the protocol point of view. They are only used for debugging and readability.

Specified by:

getName in class StunAttribute

Returns:

this attribute's name.

equals

public boolean equals(Object other)

Description copied from class: StunAttribute

Compares two STUN Attributes. Two attributes are considered equal when they have the same type length and value.

Specified by:

equals in class StunAttribute

Parameters:

other - the object to compare this attribute with.

Returns:

true if the attributes are equal and false otherwise.

encode

public byte[] encode()
              throws UnsupportedOperationException

Description copied from class: StunAttribute

Returns a binary representation of this attribute.

Specified by:

encode in class StunAttribute

Returns:

a binary representation of this attribute.

Throws:

UnsupportedOperationException

decodeAttributeBody

protected void decodeAttributeBody(byte[] data,
                       char offset,
                       char length)
                            throws StunException

Description copied from class: StunAttribute

Sets this attribute's fields according to attributeValue array.

Specified by:

decodeAttributeBody in class StunAttribute

Parameters:

data - a binary array containing this attribute's field values and NOT containing the attribute header.

offset - the position where attribute values begin (most often offset is equal to the index of the first byte after length)

length - the length of the binary array.

Throws:

StunException - if attrubteValue contains invalid data.

toString

public String toString()

Overrides:

toString in class Object