path: root/keystore/java/android/security/KeyStoreKeyProperties.java

/*
 * Copyright (C) 2015 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.security;

import android.annotation.IntDef;
import android.annotation.StringDef;
import android.security.keymaster.KeymasterDefs;

import libcore.util.EmptyArray;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.security.Key;
import java.security.KeyFactory;
import java.security.KeyPairGenerator;
import java.util.Collection;
import java.util.Locale;

import javax.crypto.Cipher;
import javax.crypto.KeyGenerator;
import javax.crypto.Mac;
import javax.crypto.SecretKeyFactory;

/**
 * Properties of {@code AndroidKeyStore} keys.
 */
public abstract class KeyStoreKeyProperties {
    private KeyStoreKeyProperties() {}

    @Retention(RetentionPolicy.SOURCE)
    @IntDef(flag = true,
            value = {Purpose.ENCRYPT, Purpose.DECRYPT, Purpose.SIGN, Purpose.VERIFY})
    public @interface PurposeEnum {}

    /**
     * Purposes of key.
     */
    public static abstract class Purpose {
        private Purpose() {}

        /**
         * Purpose: encryption.
         */
        public static final int ENCRYPT = 1 << 0;

        /**
         * Purpose: decryption.
         */
        public static final int DECRYPT = 1 << 1;

        /**
         * Purpose: signing.
         */
        public static final int SIGN = 1 << 2;

        /**
         * Purpose: signature verification.
         */
        public static final int VERIFY = 1 << 3;

        /**
         * @hide
         */
        public static int toKeymaster(@PurposeEnum int purpose) {
            switch (purpose) {
                case ENCRYPT:
                    return KeymasterDefs.KM_PURPOSE_ENCRYPT;
                case DECRYPT:
                    return KeymasterDefs.KM_PURPOSE_DECRYPT;
                case SIGN:
                    return KeymasterDefs.KM_PURPOSE_SIGN;
                case VERIFY:
                    return KeymasterDefs.KM_PURPOSE_VERIFY;
                default:
                    throw new IllegalArgumentException("Unknown purpose: " + purpose);
            }
        }

        /**
         * @hide
         */
        public static @PurposeEnum int fromKeymaster(int purpose) {
            switch (purpose) {
                case KeymasterDefs.KM_PURPOSE_ENCRYPT:
                    return ENCRYPT;
                case KeymasterDefs.KM_PURPOSE_DECRYPT:
                    return DECRYPT;
                case KeymasterDefs.KM_PURPOSE_SIGN:
                    return SIGN;
                case KeymasterDefs.KM_PURPOSE_VERIFY:
                    return VERIFY;
                default:
                    throw new IllegalArgumentException("Unknown purpose: " + purpose);
            }
        }

        /**
         * @hide
         */
        public static int[] allToKeymaster(@PurposeEnum int purposes) {
            int[] result = getSetFlags(purposes);
            for (int i = 0; i < result.length; i++) {
                result[i] = toKeymaster(result[i]);
            }
            return result;
        }

        /**
         * @hide
         */
        public static @PurposeEnum int allFromKeymaster(Collection<Integer> purposes) {
            @PurposeEnum int result = 0;
            for (int keymasterPurpose : purposes) {
                result |= fromKeymaster(keymasterPurpose);
            }
            return result;
        }
    }

    @Retention(RetentionPolicy.SOURCE)
    @StringDef({
        Algorithm.RSA,
        Algorithm.EC,
        Algorithm.AES,
        Algorithm.HMAC_SHA1,
        Algorithm.HMAC_SHA224,
        Algorithm.HMAC_SHA256,
        Algorithm.HMAC_SHA384,
        Algorithm.HMAC_SHA512,
        })
    public @interface AlgorithmEnum {}

    /**
     * Key algorithms.
     *
     * <p>These are standard names which can be used to obtain instances of {@link KeyGenerator},
     * {@link KeyPairGenerator}, {@link Cipher} (as part of the transformation string), {@link Mac},
     * {@link KeyFactory}, {@link SecretKeyFactory}. These are also the names used by
     * {@link Key#getAlgorithm()}.
     */
    public static abstract class Algorithm {
        private Algorithm() {}

        /** Rivest Shamir Adleman (RSA) key. */
        public static final String RSA = "RSA";

        /** Elliptic Curve (EC) key. */
        public static final String EC = "EC";

        /** Advanced Encryption Standard (AES) key. */
        public static final String AES = "AES";

        /** Keyed-Hash Message Authentication Code (HMAC) key using SHA-1 as the hash. */
        public static final String HMAC_SHA1 = "HmacSHA1";

        /** Keyed-Hash Message Authentication Code (HMAC) key using SHA-224 as the hash. */
        public static final String HMAC_SHA224 = "HmacSHA224";

        /** Keyed-Hash Message Authentication Code (HMAC) key using SHA-256 as the hash. */
        public static final String HMAC_SHA256 = "HmacSHA256";

        /** Keyed-Hash Message Authentication Code (HMAC) key using SHA-384 as the hash. */
        public static final String HMAC_SHA384 = "HmacSHA384";

        /** Keyed-Hash Message Authentication Code (HMAC) key using SHA-512 as the hash. */
        public static final String HMAC_SHA512 = "HmacSHA512";

        /**
         * @hide
         */
        static int toKeymasterSecretKeyAlgorithm(@AlgorithmEnum String algorithm) {
            if (AES.equalsIgnoreCase(algorithm)) {
                return KeymasterDefs.KM_ALGORITHM_AES;
            } else if (algorithm.toUpperCase(Locale.US).startsWith("HMAC")) {
                return KeymasterDefs.KM_ALGORITHM_HMAC;
            } else {
                throw new IllegalArgumentException(
                        "Unsupported secret key algorithm: " + algorithm);
            }
        }

        /**
         * @hide
         */
        static @AlgorithmEnum String fromKeymasterSecretKeyAlgorithm(
                int keymasterAlgorithm, int keymasterDigest) {
            switch (keymasterAlgorithm) {
                case KeymasterDefs.KM_ALGORITHM_AES:
                    if (keymasterDigest != -1) {
                        throw new IllegalArgumentException("Digest not supported for AES key: "
                                + Digest.fromKeymaster(keymasterDigest));
                    }
                    return AES;
                case KeymasterDefs.KM_ALGORITHM_HMAC:
                    switch (keymasterDigest) {
                        case KeymasterDefs.KM_DIGEST_SHA1:
                            return HMAC_SHA1;
                        case KeymasterDefs.KM_DIGEST_SHA_2_224:
                            return HMAC_SHA224;
                        case KeymasterDefs.KM_DIGEST_SHA_2_256:
                            return HMAC_SHA256;
                        case KeymasterDefs.KM_DIGEST_SHA_2_384:
                            return HMAC_SHA384;
                        case KeymasterDefs.KM_DIGEST_SHA_2_512:
                            return HMAC_SHA512;
                        default:
                            throw new IllegalArgumentException("Unsupported HMAC digest: "
                                    + Digest.fromKeymaster(keymasterDigest));
                    }
                default:
                    throw new IllegalArgumentException(
                            "Unsupported algorithm: " + keymasterAlgorithm);
            }
        }

        /**
         * @hide
         *
         * @return keymaster digest or {@code -1} if the algorithm does not involve a digest.
         */
        static int toKeymasterDigest(@AlgorithmEnum String algorithm) {
            String algorithmUpper = algorithm.toUpperCase(Locale.US);
            if (algorithmUpper.startsWith("HMAC")) {
                String digestUpper = algorithmUpper.substring("HMAC".length());
                switch (digestUpper) {
                    case "SHA1":
                        return KeymasterDefs.KM_DIGEST_SHA1;
                    case "SHA224":
                        return KeymasterDefs.KM_DIGEST_SHA_2_224;
                    case "SHA256":
                        return KeymasterDefs.KM_DIGEST_SHA_2_256;
                    case "SHA384":
                        return KeymasterDefs.KM_DIGEST_SHA_2_384;
                    case "SHA512":
                        return KeymasterDefs.KM_DIGEST_SHA_2_512;
                    default:
                        throw new IllegalArgumentException(
                                "Unsupported HMAC digest: " + digestUpper);
                }
            } else {
                return -1;
            }
        }
    }

    @Retention(RetentionPolicy.SOURCE)
    @StringDef({
        BlockMode.ECB,
        BlockMode.CBC,
        BlockMode.CTR,
        BlockMode.GCM,
        })
    public @interface BlockModeEnum {}

    /**
     * Block modes that can be used when encrypting/decrypting using a key.
     */
    public static abstract class BlockMode {
        private BlockMode() {}

        /** Electronic Codebook (ECB) block mode. */
        public static final String ECB = "ECB";

        /** Cipher Block Chaining (CBC) block mode. */
        public static final String CBC = "CBC";

        /** Counter (CTR) block mode. */
        public static final String CTR = "CTR";

        /** Galois/Counter Mode (GCM) block mode. */
        public static final String GCM = "GCM";

        /**
         * @hide
         */
        static int toKeymaster(@BlockModeEnum String blockMode) {
            if (ECB.equalsIgnoreCase(blockMode)) {
                return KeymasterDefs.KM_MODE_ECB;
            } else if (CBC.equalsIgnoreCase(blockMode)) {
                return KeymasterDefs.KM_MODE_CBC;
            } else if (CTR.equalsIgnoreCase(blockMode)) {
                return KeymasterDefs.KM_MODE_CTR;
            } else if (GCM.equalsIgnoreCase(blockMode)) {
                return KeymasterDefs.KM_MODE_GCM;
            } else {
                throw new IllegalArgumentException("Unsupported block mode: " + blockMode);
            }
        }

        /**
         * @hide
         */
        static @BlockModeEnum String fromKeymaster(int blockMode) {
            switch (blockMode) {
                case KeymasterDefs.KM_MODE_ECB:
                    return ECB;
                case KeymasterDefs.KM_MODE_CBC:
                    return CBC;
                case KeymasterDefs.KM_MODE_CTR:
                    return CTR;
                case KeymasterDefs.KM_MODE_GCM:
                    return GCM;
                default:
                    throw new IllegalArgumentException("Unsupported block mode: " + blockMode);
            }
        }

        /**
         * @hide
         */
        static @BlockModeEnum String[] allFromKeymaster(Collection<Integer> blockModes) {
            if ((blockModes == null) || (blockModes.isEmpty())) {
                return EmptyArray.STRING;
            }
            @BlockModeEnum String[] result = new String[blockModes.size()];
            int offset = 0;
            for (int blockMode : blockModes) {
                result[offset] = fromKeymaster(blockMode);
                offset++;
            }
            return result;
        }

        /**
         * @hide
         */
        static int[] allToKeymaster(@BlockModeEnum String[] blockModes) {
            if ((blockModes == null) || (blockModes.length == 0)) {
                return EmptyArray.INT;
            }
            int[] result = new int[blockModes.length];
            for (int i = 0; i < blockModes.length; i++) {
                result[i] = toKeymaster(blockModes[i]);
            }
            return result;
        }
    }

    @Retention(RetentionPolicy.SOURCE)
    @StringDef({
        EncryptionPadding.NONE,
        EncryptionPadding.PKCS7,
        EncryptionPadding.RSA_PKCS1,
        EncryptionPadding.RSA_OAEP,
        })
    public @interface EncryptionPaddingEnum {}

    /**
     * Padding schemes for encryption/decryption.
     */
    public static abstract class EncryptionPadding {
        private EncryptionPadding() {}

        /**
         * No padding.
         */
        public static final String NONE = "NoPadding";

        /**
         * PKCS#7 padding.
         */
        public static final String PKCS7 = "PKCS7Padding";

        /**
         * RSA PKCS#1 v1.5 padding for encryption/decryption.
         */
        public static final String RSA_PKCS1 = "PKCS1Padding";

        /**
         * RSA Optimal Asymmetric Encryption Padding (OAEP).
         */
        public static final String RSA_OAEP = "OAEPPadding";

        /**
         * @hide
         */
        static int toKeymaster(@EncryptionPaddingEnum String padding) {
            if (NONE.equalsIgnoreCase(padding)) {
                return KeymasterDefs.KM_PAD_NONE;
            } else if (PKCS7.equalsIgnoreCase(padding)) {
                return KeymasterDefs.KM_PAD_PKCS7;
            } else if (RSA_PKCS1.equalsIgnoreCase(padding)) {
                return KeymasterDefs.KM_PAD_RSA_PKCS1_1_5_ENCRYPT;
            } else if (RSA_OAEP.equalsIgnoreCase(padding)) {
                return KeymasterDefs.KM_PAD_RSA_OAEP;
            } else {
                throw new IllegalArgumentException(
                        "Unsupported encryption padding scheme: " + padding);
            }
        }

        /**
         * @hide
         */
        static @EncryptionPaddingEnum String fromKeymaster(int padding) {
            switch (padding) {
                case KeymasterDefs.KM_PAD_NONE:
                    return NONE;
                case KeymasterDefs.KM_PAD_PKCS7:
                    return PKCS7;
                case KeymasterDefs.KM_PAD_RSA_PKCS1_1_5_ENCRYPT:
                    return RSA_PKCS1;
                case KeymasterDefs.KM_PAD_RSA_OAEP:
                    return RSA_OAEP;
                default:
                    throw new IllegalArgumentException(
                            "Unsupported encryption padding: " + padding);
            }
        }

        /**
         * @hide
         */
        static int[] allToKeymaster(@EncryptionPaddingEnum String[] paddings) {
            if ((paddings == null) || (paddings.length == 0)) {
                return EmptyArray.INT;
            }
            int[] result = new int[paddings.length];
            for (int i = 0; i < paddings.length; i++) {
                result[i] = toKeymaster(paddings[i]);
            }
            return result;
        }
    }

    @Retention(RetentionPolicy.SOURCE)
    @StringDef({
        SignaturePadding.RSA_PKCS1,
        SignaturePadding.RSA_PSS,
        })
    public @interface SignaturePaddingEnum {}

    /**
     * Padding schemes for signing/verification.
     */
    public static abstract class SignaturePadding {
        private SignaturePadding() {}

        /**
         * RSA PKCS#1 v1.5 padding for signatures.
         */
        public static final String RSA_PKCS1 = "PKCS1";

        /**
         * RSA PKCS#1 v2.1 Probabilistic Signature Scheme (PSS) padding.
         */
        public static final String RSA_PSS = "PSS";

        /**
         * @hide
         */
        static int toKeymaster(@SignaturePaddingEnum String padding) {
            switch (padding.toUpperCase(Locale.US)) {
                case RSA_PKCS1:
                    return KeymasterDefs.KM_PAD_RSA_PKCS1_1_5_SIGN;
                case RSA_PSS:
                    return KeymasterDefs.KM_PAD_RSA_PSS;
                default:
                    throw new IllegalArgumentException(
                            "Unsupported signature padding scheme: " + padding);
            }
        }

        /**
         * @hide
         */
        static @SignaturePaddingEnum String fromKeymaster(int padding) {
            switch (padding) {
                case KeymasterDefs.KM_PAD_RSA_PKCS1_1_5_SIGN:
                    return RSA_PKCS1;
                case KeymasterDefs.KM_PAD_RSA_PSS:
                    return RSA_PSS;
                default:
                    throw new IllegalArgumentException("Unsupported signature padding: " + padding);
            }
        }

        /**
         * @hide
         */
        static int[] allToKeymaster(@SignaturePaddingEnum String[] paddings) {
            if ((paddings == null) || (paddings.length == 0)) {
                return EmptyArray.INT;
            }
            int[] result = new int[paddings.length];
            for (int i = 0; i < paddings.length; i++) {
                result[i] = toKeymaster(paddings[i]);
            }
            return result;
        }
    }

    @Retention(RetentionPolicy.SOURCE)
    @StringDef({
        Digest.NONE,
        Digest.MD5,
        Digest.SHA1,
        Digest.SHA224,
        Digest.SHA256,
        Digest.SHA384,
        Digest.SHA512,
        })
    public @interface DigestEnum {}

    /**
     * Digests that can be used with a key when signing or generating Message Authentication
     * Codes (MACs).
     */
    public static abstract class Digest {
        private Digest() {}

        /**
         * No digest: sign/authenticate the raw message.
         */
        public static final String NONE = "NONE";

        /**
         * MD5 digest.
         */
        public static final String MD5 = "MD5";

        /**
         * SHA-1 digest.
         */
        public static final String SHA1 = "SHA-1";

        /**
         * SHA-2 224 (aka SHA-224) digest.
         */
        public static final String SHA224 = "SHA-224";

        /**
         * SHA-2 256 (aka SHA-256) digest.
         */
        public static final String SHA256 = "SHA-256";

        /**
         * SHA-2 384 (aka SHA-384) digest.
         */
        public static final String SHA384 = "SHA-384";

        /**
         * SHA-2 512 (aka SHA-512) digest.
         */
        public static final String SHA512 = "SHA-512";

        /**
         * @hide
         */
        static int toKeymaster(@DigestEnum String digest) {
            switch (digest.toUpperCase(Locale.US)) {
                case SHA1:
                    return KeymasterDefs.KM_DIGEST_SHA1;
                case SHA224:
                    return KeymasterDefs.KM_DIGEST_SHA_2_224;
                case SHA256:
                    return KeymasterDefs.KM_DIGEST_SHA_2_256;
                case SHA384:
                    return KeymasterDefs.KM_DIGEST_SHA_2_384;
                case SHA512:
                    return KeymasterDefs.KM_DIGEST_SHA_2_512;
                case NONE:
                    return KeymasterDefs.KM_DIGEST_NONE;
                case MD5:
                    return KeymasterDefs.KM_DIGEST_MD5;
                default:
                    throw new IllegalArgumentException("Unsupported digest algorithm: " + digest);
            }
        }

        /**
         * @hide
         */
        static @DigestEnum String fromKeymaster(int digest) {
            switch (digest) {
                case KeymasterDefs.KM_DIGEST_NONE:
                    return NONE;
                case KeymasterDefs.KM_DIGEST_MD5:
                    return MD5;
                case KeymasterDefs.KM_DIGEST_SHA1:
                    return SHA1;
                case KeymasterDefs.KM_DIGEST_SHA_2_224:
                    return SHA224;
                case KeymasterDefs.KM_DIGEST_SHA_2_256:
                    return SHA256;
                case KeymasterDefs.KM_DIGEST_SHA_2_384:
                    return SHA384;
                case KeymasterDefs.KM_DIGEST_SHA_2_512:
                    return SHA512;
                default:
                    throw new IllegalArgumentException("Unsupported digest algorithm: " + digest);
            }
        }

        /**
         * @hide
         */
        static @DigestEnum String[] allFromKeymaster(Collection<Integer> digests) {
            if (digests.isEmpty()) {
                return EmptyArray.STRING;
            }
            String[] result = new String[digests.size()];
            int offset = 0;
            for (int digest : digests) {
                result[offset] = fromKeymaster(digest);
                offset++;
            }
            return result;
        }

        /**
         * @hide
         */
        static int[] allToKeymaster(@DigestEnum String[] digests) {
            if ((digests == null) || (digests.length == 0)) {
                return EmptyArray.INT;
            }
            int[] result = new int[digests.length];
            int offset = 0;
            for (@DigestEnum String digest : digests) {
                result[offset] = toKeymaster(digest);
                offset++;
            }
            return result;
        }
    }

    @Retention(RetentionPolicy.SOURCE)
    @IntDef({Origin.GENERATED, Origin.IMPORTED, Origin.UNKNOWN})
    public @interface OriginEnum {}

    /**
     * Origin of the key.
     */
    public static abstract class Origin {
        private Origin() {}

        /** Key was generated inside AndroidKeyStore. */
        public static final int GENERATED = 1 << 0;

        /** Key was imported into AndroidKeyStore. */
        public static final int IMPORTED = 1 << 1;

        /**
         * Origin of the key is unknown. This can occur only for keys backed by an old TEE-backed
         * implementation which does not record origin information.
         */
        public static final int UNKNOWN = 1 << 2;

        /**
         * @hide
         */
        public static @OriginEnum int fromKeymaster(int origin) {
            switch (origin) {
                case KeymasterDefs.KM_ORIGIN_GENERATED:
                    return GENERATED;
                case KeymasterDefs.KM_ORIGIN_IMPORTED:
                    return IMPORTED;
                case KeymasterDefs.KM_ORIGIN_UNKNOWN:
                    return UNKNOWN;
                default:
                    throw new IllegalArgumentException("Unknown origin: " + origin);
            }
        }
    }

    private static int[] getSetFlags(int flags) {
        if (flags == 0) {
            return EmptyArray.INT;
        }
        int result[] = new int[getSetBitCount(flags)];
        int resultOffset = 0;
        int flag = 1;
        while (flags != 0) {
            if ((flags & 1) != 0) {
                result[resultOffset] = flag;
                resultOffset++;
            }
            flags >>>= 1;
            flag <<= 1;
        }
        return result;
    }

    private static int getSetBitCount(int value) {
        if (value == 0) {
            return 0;
        }
        int result = 0;
        while (value != 0) {
            if ((value & 1) != 0) {
                result++;
            }
            value >>>= 1;
        }
        return result;
    }
}