/* * 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: *
*
* 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. * * @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 MessageIntegrityAttribute. */ 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 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 {@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 message. * @param length the length of the data in message 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 * MessageIntegrityAttribute transported by message. * * @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 StunStack in the context of which the * request to encode this ContentDependentAttribute is being made * @param content the content of the message that this attribute will be * transported in * @param offset the content-related offset where the actual * content starts. * @param length the length of the content in the content array. * * @return a binary representation of this attribute valid for the message * with the specified content. */ 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 MessageIntegrityAttributes. 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; } }