src.android.net.IpSecAlgorithm Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* 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.content.res.Resources;
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;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Set;
/**
* 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)";
/**
* AES-CTR Encryption/Ciphering Algorithm.
*
*
Valid lengths for keying material are {160, 224, 288}.
*
*
As per RFC3686 (Section
* 5.1), keying material consists of a 128, 192, or 256 bit AES key followed by a 32-bit
* nonce. RFC compliance requires that the nonce must be unique per security association.
*
*
This algorithm may be available on the device. Caller MUST check if it is supported before
* using it by calling {@link #getSupportedAlgorithms()} and checking if this algorithm is
* included in the returned algorithm set. The returned algorithm set will not change unless the
* device is rebooted. {@link IllegalArgumentException} will be thrown if this algorithm is
* requested on an unsupported device.
*
*
@see {@link #getSupportedAlgorithms()}
*/
// This algorithm may be available on devices released before Android 12, and is guaranteed
// to be available on devices first shipped with Android 12 or later.
public static final String CRYPT_AES_CTR = "rfc3686(ctr(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-XCBC Authentication/Integrity Algorithm.
*
*
Keys for this algorithm must be 128 bits in length.
*
*
The only valid truncation length is 96 bits.
*
*
This algorithm may be available on the device. Caller MUST check if it is supported before
* using it by calling {@link #getSupportedAlgorithms()} and checking if this algorithm is
* included in the returned algorithm set. The returned algorithm set will not change unless the
* device is rebooted. {@link IllegalArgumentException} will be thrown if this algorithm is
* requested on an unsupported device.
*
*
@see {@link #getSupportedAlgorithms()}
*/
// This algorithm may be available on devices released before Android 12, and is guaranteed
// to be available on devices first shipped with Android 12 or later.
public static final String AUTH_AES_XCBC = "xcbc(aes)";
/**
* AES-CMAC Authentication/Integrity Algorithm.
*
*
Keys for this algorithm must be 128 bits in length.
*
*
The only valid truncation length is 96 bits.
*
*
This algorithm may be available on the device. Caller MUST check if it is supported before
* using it by calling {@link #getSupportedAlgorithms()} and checking if this algorithm is
* included in the returned algorithm set. The returned algorithm set will not change unless the
* device is rebooted. {@link IllegalArgumentException} will be thrown if this algorithm is
* requested on an unsupported device.
*
*
@see {@link #getSupportedAlgorithms()}
*/
// This algorithm may be available on devices released before Android 12, and is guaranteed
// to be available on devices first shipped with Android 12 or later.
public static final String AUTH_AES_CMAC = "cmac(aes)";
/**
* 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))";
/**
* ChaCha20-Poly1305 Authentication/Integrity + Encryption/Ciphering Algorithm.
*
*
Keys for this algorithm must be 288 bits in length.
*
*
As per RFC7634 (Section 2),
* keying material consists of a 256 bit key followed by a 32-bit salt. The salt is fixed per
* security association.
*
*
The only valid ICV (truncation) length is 128 bits.
*
*
This algorithm may be available on the device. Caller MUST check if it is supported before
* using it by calling {@link #getSupportedAlgorithms()} and checking if this algorithm is
* included in the returned algorithm set. The returned algorithm set will not change unless the
* device is rebooted. {@link IllegalArgumentException} will be thrown if this algorithm is
* requested on an unsupported device.
*
*
@see {@link #getSupportedAlgorithms()}
*/
// This algorithm may be available on devices released before Android 12, and is guaranteed
// to be available on devices first shipped with Android 12 or later.
public static final String AUTH_CRYPT_CHACHA20_POLY1305 = "rfc7539esp(chacha20,poly1305)";
/** @hide */
@StringDef({
CRYPT_AES_CBC,
CRYPT_AES_CTR,
AUTH_HMAC_MD5,
AUTH_HMAC_SHA1,
AUTH_HMAC_SHA256,
AUTH_HMAC_SHA384,
AUTH_HMAC_SHA512,
AUTH_AES_XCBC,
AUTH_AES_CMAC,
AUTH_CRYPT_AES_GCM,
AUTH_CRYPT_CHACHA20_POLY1305
})
@Retention(RetentionPolicy.SOURCE)
public @interface AlgorithmName {}
/** @hide */
@VisibleForTesting
public static final Map ALGO_TO_REQUIRED_FIRST_SDK = new HashMap<>();
private static final int SDK_VERSION_ZERO = 0;
static {
ALGO_TO_REQUIRED_FIRST_SDK.put(CRYPT_AES_CBC, SDK_VERSION_ZERO);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_HMAC_MD5, SDK_VERSION_ZERO);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_HMAC_SHA1, SDK_VERSION_ZERO);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_HMAC_SHA256, SDK_VERSION_ZERO);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_HMAC_SHA384, SDK_VERSION_ZERO);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_HMAC_SHA512, SDK_VERSION_ZERO);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_CRYPT_AES_GCM, SDK_VERSION_ZERO);
// STOPSHIP: b/170424293 Use Build.VERSION_CODES.S when it is defined
ALGO_TO_REQUIRED_FIRST_SDK.put(CRYPT_AES_CTR, Build.VERSION_CODES.R + 1);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_AES_XCBC, Build.VERSION_CODES.R + 1);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_AES_CMAC, Build.VERSION_CODES.R + 1);
ALGO_TO_REQUIRED_FIRST_SDK.put(AUTH_CRYPT_CHACHA20_POLY1305, Build.VERSION_CODES.R + 1);
}
private static final Set ENABLED_ALGOS =
Collections.unmodifiableSet(loadAlgos(Resources.getSystem()));
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.
* @throws IllegalArgumentException if algorithm or key length is invalid.
*/
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.
* @throws IllegalArgumentException if algorithm, key length or truncation length is invalid.
*/
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 @android.annotation.NonNull Parcelable.Creator CREATOR =
new Parcelable.Creator() {
public IpSecAlgorithm createFromParcel(Parcel in) {
final String name = in.readString();
final byte[] key = in.createByteArray();
final int truncLenBits = in.readInt();
return new IpSecAlgorithm(name, key, truncLenBits);
}
public IpSecAlgorithm[] newArray(int size) {
return new IpSecAlgorithm[size];
}
};
/**
* Returns supported IPsec algorithms for the current device.
*
* Some algorithms may not be supported on old devices. Callers MUST check if an algorithm is
* supported before using it.
*/
@NonNull
public static Set getSupportedAlgorithms() {
return ENABLED_ALGOS;
}
/** @hide */
@VisibleForTesting
public static Set loadAlgos(Resources systemResources) {
final Set enabledAlgos = new HashSet<>();
// Load and validate the optional algorithm resource. Undefined or duplicate algorithms in
// the resource are not allowed.
final String[] resourceAlgos = systemResources.getStringArray(
com.android.internal.R.array.config_optionalIpSecAlgorithms);
for (String str : resourceAlgos) {
if (!ALGO_TO_REQUIRED_FIRST_SDK.containsKey(str) || !enabledAlgos.add(str)) {
// This error should be caught by CTS and never be thrown to API callers
throw new IllegalArgumentException("Invalid or repeated algorithm " + str);
}
}
for (Entry entry : ALGO_TO_REQUIRED_FIRST_SDK.entrySet()) {
if (Build.VERSION.DEVICE_INITIAL_SDK_INT >= entry.getValue()) {
enabledAlgos.add(entry.getKey());
}
}
return enabledAlgos;
}
private static void checkValidOrThrow(String name, int keyLen, int truncLen) {
final boolean isValidLen;
final boolean isValidTruncLen;
if (!getSupportedAlgorithms().contains(name)) {
throw new IllegalArgumentException("Unsupported algorithm: " + name);
}
switch (name) {
case CRYPT_AES_CBC:
isValidLen = keyLen == 128 || keyLen == 192 || keyLen == 256;
isValidTruncLen = true;
break;
case CRYPT_AES_CTR:
// The keying material for AES-CTR is a key plus a 32-bit salt
isValidLen = keyLen == 128 + 32 || keyLen == 192 + 32 || keyLen == 256 + 32;
isValidTruncLen = true;
break;
case AUTH_HMAC_MD5:
isValidLen = keyLen == 128;
isValidTruncLen = truncLen >= 96 && truncLen <= 128;
break;
case AUTH_HMAC_SHA1:
isValidLen = keyLen == 160;
isValidTruncLen = truncLen >= 96 && truncLen <= 160;
break;
case AUTH_HMAC_SHA256:
isValidLen = keyLen == 256;
isValidTruncLen = truncLen >= 96 && truncLen <= 256;
break;
case AUTH_HMAC_SHA384:
isValidLen = keyLen == 384;
isValidTruncLen = truncLen >= 192 && truncLen <= 384;
break;
case AUTH_HMAC_SHA512:
isValidLen = keyLen == 512;
isValidTruncLen = truncLen >= 256 && truncLen <= 512;
break;
case AUTH_AES_XCBC:
isValidLen = keyLen == 128;
isValidTruncLen = truncLen == 96;
break;
case AUTH_AES_CMAC:
isValidLen = keyLen == 128;
isValidTruncLen = truncLen == 96;
break;
case AUTH_CRYPT_AES_GCM:
// The keying material for GCM is a key plus a 32-bit salt
isValidLen = keyLen == 128 + 32 || keyLen == 192 + 32 || keyLen == 256 + 32;
isValidTruncLen = truncLen == 64 || truncLen == 96 || truncLen == 128;
break;
case AUTH_CRYPT_CHACHA20_POLY1305:
// The keying material for ChaCha20Poly1305 is a key plus a 32-bit salt
isValidLen = keyLen == 256 + 32;
isValidTruncLen = truncLen == 128;
break;
default:
// Should never hit here.
throw new IllegalArgumentException("Couldn't find an algorithm: " + name);
}
if (!isValidLen) {
throw new IllegalArgumentException("Invalid key material keyLength: " + keyLen);
}
if (!isValidTruncLen) {
throw new IllegalArgumentException("Invalid truncation keyLength: " + truncLen);
}
}
/** @hide */
public boolean isAuthentication() {
switch (getName()) {
// Fallthrough
case AUTH_HMAC_MD5:
case AUTH_HMAC_SHA1:
case AUTH_HMAC_SHA256:
case AUTH_HMAC_SHA384:
case AUTH_HMAC_SHA512:
case AUTH_AES_XCBC:
case AUTH_AES_CMAC:
return true;
default:
return false;
}
}
/** @hide */
public boolean isEncryption() {
switch (getName()) {
case CRYPT_AES_CBC: // fallthrough
case CRYPT_AES_CTR:
return true;
default:
return false;
}
}
/** @hide */
public boolean isAead() {
switch (getName()) {
case AUTH_CRYPT_AES_GCM: // fallthrough
case AUTH_CRYPT_CHACHA20_POLY1305:
return true;
default:
return false;
}
}
// Because encryption keys are sensitive and userdebug builds are used by large user pools
// such as beta testers, we only allow sensitive info such as keys on eng builds.
private static boolean isUnsafeBuild() {
return Build.IS_DEBUGGABLE && Build.IS_ENG;
}
@Override
@NonNull
public String toString() {
return new StringBuilder()
.append("{mName=")
.append(mName)
.append(", mKey=")
.append(isUnsafeBuild() ? HexDump.toHexString(mKey) : "")
.append(", mTruncLenBits=")
.append(mTruncLenBits)
.append("}")
.toString();
}
/** @hide */
@VisibleForTesting
public static boolean equals(IpSecAlgorithm lhs, IpSecAlgorithm rhs) {
if (lhs == null || rhs == null) return (lhs == rhs);
return (lhs.mName.equals(rhs.mName)
&& Arrays.equals(lhs.mKey, rhs.mKey)
&& lhs.mTruncLenBits == rhs.mTruncLenBits);
}
};