ice4j/src/main/java/org/ice4j/attribute/MessageIntegrityAttribute.java
Ingo Bauersachs de1260610d Merge pull request #69 from champtar/nullequals
Remove unneeded null checks & fix MagicCookieAttribute equals
2016-04-20 22:15:05 +02:00

354 lines
12 KiB
Java

/*
* ice4j, the OpenSource Java Solution for NAT and Firewall Traversal.
*
* Copyright @ 2015 Atlassian Pty Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.ice4j.attribute;
import java.util.*;
import javax.crypto.*;
import javax.crypto.spec.*;
import org.ice4j.message.*;
import org.ice4j.stack.*;
/**
* 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:
* <p>
* <pre>
* key = MD5(username ":" realm ":" SASLprep(password))
* </pre>
* 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.
* <p>
* For short-term credentials:
* <p>
* <pre>
* key = SASLprep(password)
* </pre>
* where MD5 is defined in RFC 1321 [RFC1321] and SASLprep() is defined
* in RFC 4013 [RFC4013].
* <p>
* 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.
* <p>
* 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.
*
* @author Emil Ivov
*/
public class MessageIntegrityAttribute
extends Attribute
implements ContentDependentAttribute
{
/**
* Attribute name.
*/
public static final String NAME = "MESSAGE_INTEGRITY";
/**
* The HMAC-SHA1 algorithm.
*/
public static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";
/**
* The HMAC-SHA1 algorithm.
*/
public static final char DATA_LENGTH = (char)20;
/**
* The actual content of the message
*/
private byte[] hmacSha1Content;
/**
* The username that we should use to obtain an encryption
* key (password) that the {@link #encode()} method should use when
* creating the content of this message.
*/
private String username;
/**
* The media name if we use short-term authentication.
*/
private String media;
/**
* Creates a <tt>MessageIntegrityAttribute</tt>.
*/
protected MessageIntegrityAttribute()
{
super(MESSAGE_INTEGRITY);
}
/**
* Sets the username that we should use to obtain an encryption
* key (password) that the {@link #encode()} method should use when
* creating the content of this message.
*
* @param username the username that we should use to obtain an encryption
* key (password) that the {@link #encode()} method should use when
* creating the content of this message.
*/
public void setUsername(String username)
{
this.username = username;
}
/**
* Sets the media name that we should use to get the corresponding remote
* key (short-term authentication only).
*
* @param media name
*/
public void setMedia(String media)
{
this.media = media;
}
/**
* Returns the HMAC-SHA1 value stored in this attribute.
*
* @return the HMAC-SHA1 value stored in this attribute.
*/
public byte[] getHmacSha1Content()
{
return hmacSha1Content;
}
/**
* Encodes <tt>message</tt> using <tt>key</tt> 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 {@link MessageIntegrityAttribute}
* regardless of the credentials being used (short or long term).
*
* @param message the STUN message that the resulting content will need to
* travel in.
* @param offset the index where data starts in <tt>message</tt>.
* @param length the length of the data in <tt>message</tt> that the method
* should consider.
* @param key the key that we should be using for the encoding (which
* depends on whether we are using short or long term credentials).
*
* @return the HMAC that should be used in a
* <tt>MessageIntegrityAttribute</tt> transported by <tt>message</tt>.
*
* @throws IllegalArgumentException if the encoding fails for some reason.
*/
public static byte[] calculateHmacSha1(byte[] message,
int offset,
int length,
byte[] key)
throws IllegalArgumentException
{
byte[] hmac;
try
{
// get an HMAC-SHA1 key from the raw key bytes
SecretKeySpec signingKey
= new SecretKeySpec(key, HMAC_SHA1_ALGORITHM);
// get an HMAC-SHA1 Mac instance and initialize it with the key
Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
mac.init(signingKey);
// compute the hmac on input data bytes
byte[] macInput = new byte[length];
//doFinal seems incapable to only work with a part of an array
//so we'd need to create an array that only contains what we
//actually need to work with.
System.arraycopy(message, offset, macInput, 0, length);
hmac = mac.doFinal(macInput);
}
catch (Exception exc)
{
throw new IllegalArgumentException(
"Could not create HMAC-SHA1 request encoding: ", exc);
}
return hmac;
}
/**
* Sets this attribute's fields according to the message and attributeValue
* arrays.
*
* @param attributeValue a binary array containing this attribute's field
* values and NOT containing the attribute header.
* @param offset the position where attribute values begin (most often
* offset is equal to the index of the first byte after length)
* @param length the length of the binary array.
* the start of this attribute.
*/
public void decodeAttributeBody( byte[] attributeValue,
char offset,
char length)
{
hmacSha1Content = new byte[length];
System.arraycopy(attributeValue, offset, hmacSha1Content, 0, length);
}
/**
* Returns a binary representation of this attribute.
*
* @return nothing
* @throws UnsupportedOperationException since {@link
* ContentDependentAttribute}s should be encoded through the content
* dependent encode method.
*/
public byte[] encode()
throws UnsupportedOperationException
{
throw new UnsupportedOperationException(
"ContentDependentAttributes should be encoded "
+ "through the contend-dependent encode method");
}
/**
* Returns a binary representation of this attribute.
*
* @param stunStack the <tt>StunStack</tt> in the context of which the
* request to encode this <tt>ContentDependentAttribute</tt> is being made
* @param content the content of the message that this attribute will be
* transported in
* @param offset the <tt>content</tt>-related offset where the actual
* content starts.
* @param length the length of the content in the <tt>content</tt> array.
*
* @return a binary representation of this attribute valid for the message
* with the specified <tt>content</tt>.
*/
public byte[] encode(
StunStack stunStack,
byte[] content, int offset, int length)
{
char type = getAttributeType();
byte binValue[] = new byte[HEADER_LENGTH + getDataLength()];
//Type
binValue[0] = (byte)(type >> 8);
binValue[1] = (byte)(type & 0x00FF);
//Length
binValue[2] = (byte)(getDataLength() >> 8);
binValue[3] = (byte)(getDataLength() & 0x00FF);
byte[] key = null;
char msgType =
(char) (((content[0] & 0xFF) << 8) | (content[1] & 0xFF));
if(Message.isRequestType(msgType))
{
/* attribute part of a request, use the remote key */
key = stunStack.getCredentialsManager().getRemoteKey(username,
media);
}
else if(Message.isSuccessResponseType(msgType) ||
Message.isErrorResponseType(msgType))
{
/* attribute part of a response, use the local key */
key = stunStack.getCredentialsManager().getLocalKey(username);
}
//now calculate the HMAC-SHA1
this.hmacSha1Content = calculateHmacSha1(content, offset, length, key);
//username
System.arraycopy(hmacSha1Content, 0, binValue, 4, getDataLength());
return binValue;
}
/**
* Returns the length of this attribute's body.
*
* @return the length of this attribute's value.
*/
public char getDataLength()
{
return DATA_LENGTH;
}
/**
* Returns the human readable name of this attribute.
*
* @return this attribute's name.
*/
public String getName()
{
return NAME;
}
/**
* Compares two <tt>MessageIntegrityAttribute</tt>s. Two attributes are
* considered equal when they have the same type length and value.
*
* @param obj the object to compare this attribute with.
* @return true if the attributes are equal and false otherwise.
*/
public boolean equals(Object obj)
{
if (! (obj instanceof MessageIntegrityAttribute))
return false;
if (obj == this)
return true;
MessageIntegrityAttribute att = (MessageIntegrityAttribute) obj;
if (att.getAttributeType() != getAttributeType()
|| att.getDataLength() != getDataLength()
|| !Arrays.equals( att.hmacSha1Content, hmacSha1Content))
return false;
return true;
}
}