/* * Copyright (C) 2017 The Android Open Source Project * * 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 android.net; import android.annotation.NonNull; import android.annotation.StringDef; import android.os.Build; import android.os.Parcel; import android.os.Parcelable; import com.android.internal.annotations.VisibleForTesting; import com.android.internal.util.HexDump; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.util.Arrays; /** * This class represents a single algorithm that can be used by an {@link IpSecTransform}. * * @see RFC 4301, Security Architecture for the * Internet Protocol */ public final class IpSecAlgorithm implements Parcelable { private static final String TAG = "IpSecAlgorithm"; /** * Null cipher. * * @hide */ public static final String CRYPT_NULL = "ecb(cipher_null)"; /** * AES-CBC Encryption/Ciphering Algorithm. * *
Valid lengths for this key are {128, 192, 256}. */ public static final String CRYPT_AES_CBC = "cbc(aes)"; /** * MD5 HMAC Authentication/Integrity Algorithm. This algorithm is not recommended for use in * new applications and is provided for legacy compatibility with 3gpp infrastructure. * *
Keys for this algorithm must be 128 bits in length. * *
Valid truncation lengths are multiples of 8 bits from 96 to 128. */ public static final String AUTH_HMAC_MD5 = "hmac(md5)"; /** * SHA1 HMAC Authentication/Integrity Algorithm. This algorithm is not recommended for use in * new applications and is provided for legacy compatibility with 3gpp infrastructure. * *
Keys for this algorithm must be 160 bits in length. * *
Valid truncation lengths are multiples of 8 bits from 96 to 160. */ public static final String AUTH_HMAC_SHA1 = "hmac(sha1)"; /** * SHA256 HMAC Authentication/Integrity Algorithm. * *
Keys for this algorithm must be 256 bits in length. * *
Valid truncation lengths are multiples of 8 bits from 96 to 256. */ public static final String AUTH_HMAC_SHA256 = "hmac(sha256)"; /** * SHA384 HMAC Authentication/Integrity Algorithm. * *
Keys for this algorithm must be 384 bits in length. * *
Valid truncation lengths are multiples of 8 bits from 192 to 384. */ public static final String AUTH_HMAC_SHA384 = "hmac(sha384)"; /** * SHA512 HMAC Authentication/Integrity Algorithm. * *
Keys for this algorithm must be 512 bits in length. * *
Valid truncation lengths are multiples of 8 bits from 256 to 512. */ public static final String AUTH_HMAC_SHA512 = "hmac(sha512)"; /** * AES-GCM Authentication/Integrity + Encryption/Ciphering Algorithm. * *
Valid lengths for keying material are {160, 224, 288}. * *
As per RFC4106 (Section * 8.1), keying material consists of a 128, 192, or 256 bit AES key followed by a 32-bit * salt. RFC compliance requires that the salt must be unique per invocation with the same key. * *
Valid ICV (truncation) lengths are {64, 96, 128}. */ public static final String AUTH_CRYPT_AES_GCM = "rfc4106(gcm(aes))"; /** @hide */ @StringDef({ CRYPT_AES_CBC, AUTH_HMAC_MD5, AUTH_HMAC_SHA1, AUTH_HMAC_SHA256, AUTH_HMAC_SHA384, AUTH_HMAC_SHA512, AUTH_CRYPT_AES_GCM }) @Retention(RetentionPolicy.SOURCE) public @interface AlgorithmName {} private final String mName; private final byte[] mKey; private final int mTruncLenBits; /** * Creates an IpSecAlgorithm of one of the supported types. Supported algorithm names are * defined as constants in this class. * *
For algorithms that produce an integrity check value, the truncation length is a required * parameter. See {@link #IpSecAlgorithm(String algorithm, byte[] key, int truncLenBits)} * * @param algorithm name of the algorithm. * @param key key padded to a multiple of 8 bits. */ public IpSecAlgorithm(@NonNull @AlgorithmName String algorithm, @NonNull byte[] key) { this(algorithm, key, 0); } /** * Creates an IpSecAlgorithm of one of the supported types. Supported algorithm names are * defined as constants in this class. * *
This constructor only supports algorithms that use a truncation length. i.e.
* Authentication and Authenticated Encryption algorithms.
*
* @param algorithm name of the algorithm.
* @param key key padded to a multiple of 8 bits.
* @param truncLenBits number of bits of output hash to use.
*/
public IpSecAlgorithm(
@NonNull @AlgorithmName String algorithm, @NonNull byte[] key, int truncLenBits) {
mName = algorithm;
mKey = key.clone();
mTruncLenBits = truncLenBits;
checkValidOrThrow(mName, mKey.length * 8, mTruncLenBits);
}
/** Get the algorithm name */
@NonNull
public String getName() {
return mName;
}
/** Get the key for this algorithm */
@NonNull
public byte[] getKey() {
return mKey.clone();
}
/** Get the truncation length of this algorithm, in bits */
public int getTruncationLengthBits() {
return mTruncLenBits;
}
/* Parcelable Implementation */
public int describeContents() {
return 0;
}
/** Write to parcel */
public void writeToParcel(Parcel out, int flags) {
out.writeString(mName);
out.writeByteArray(mKey);
out.writeInt(mTruncLenBits);
}
/** Parcelable Creator */
public static final Parcelable.Creator