| // Copyright 2020, 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. |
| |
| //! KeyParameter is used to express different characteristics of a key requested by the user |
| //! and enforced by the OEMs. This module implements the internal representation of KeyParameter |
| //! and the methods to work with KeyParameter. |
| |
| use crate::keymint_definitions::{ |
| Algorithm, BlockMode, Digest, EcCurve, HardwareAuthenticatorType, KeyBlobUsageRequirements, |
| KeyOrigin, KeyPurpose, PaddingMode, SecurityLevel, Tag, |
| }; |
| |
| /// KeyParameter wraps the KeyParameterValue and the security level at which it is enforced. |
| pub struct KeyParameter { |
| key_parameter_value: KeyParameterValue, |
| security_level: SecurityLevel, |
| } |
| |
| /// KeyParameterValue holds a value corresponding to one of the Tags defined in |
| /// the AIDL spec at hardware/interfaces/keymint |
| #[derive(PartialEq, Debug)] |
| pub enum KeyParameterValue { |
| /// Associated with Tag:INVALID |
| Invalid, |
| /// Set of purposes for which the key may be used |
| KeyPurpose(KeyPurpose), |
| /// Cryptographic algorithm with which the key is used |
| Algorithm(Algorithm), |
| /// Size of the key , in bits |
| KeySize(u32), |
| /// Block cipher mode(s) with which the key may be used |
| BlockMode(BlockMode), |
| /// Digest algorithms that may be used with the key to perform signing and verification |
| Digest(Digest), |
| /// Padding modes that may be used with the key. Relevant to RSA, AES and 3DES keys. |
| PaddingMode(PaddingMode), |
| /// Can the caller provide a nonce for nonce-requiring operations |
| CallerNonce, |
| /// Minimum length of MAC for HMAC keys and AES keys that support GCM mode |
| MinMacLength(u32), |
| /// The elliptic curve |
| EcCurve(EcCurve), |
| /// Value of the public exponent for an RSA key pair |
| RSAPublicExponent(u64), |
| /// An attestation certificate for the generated key should contain an application-scoped |
| /// and time-bounded device-unique ID |
| IncludeUniqueID, |
| /// Necessary system environment conditions for the generated key to be used |
| KeyBlobUsageRequirements(KeyBlobUsageRequirements), |
| /// Only the boot loader can use the key |
| BootLoaderOnly, |
| /// When deleted, the key is guaranteed to be permanently deleted and unusable |
| RollbackResistance, |
| //TODO: HARDWARE_TYPE reserved for future use |
| /// The date and time at which the key becomes active |
| ActiveDateTime(u64), |
| /// The date and time at which the key expires for signing and encryption |
| OriginationExpireDateTime(u64), |
| /// The date and time at which the key expires for verification and decryption |
| UsageExpireDateTime(u64), |
| /// Minimum amount of time that elapses between allowed operations |
| MinSecondsBetweenOps(u32), |
| /// Maximum number of times that a key may be used between system reboots |
| MaxUsesPerBoot(u32), |
| /// ID of the Android user that is permitted to use the key |
| UserID(u32), |
| /// A key may only be used under a particular secure user authentication state |
| UserSecureID(u64), |
| /// No authentication is required to use this key |
| NoAuthRequired, |
| /// The types of user authenticators that may be used to authorize this key |
| HardwareAuthenticatorType(HardwareAuthenticatorType), |
| /// The time in seconds for which the key is authorized for use, after user authentication |
| AuthTimeout(u32), |
| /// The key may be used after authentication timeout if device is still on-body |
| AllowWhileOnBody, |
| /// The key must be unusable except when the user has provided proof of physical presence |
| TrustedUserPresenceRequired, |
| /// Applicable to keys with KeyPurpose SIGN, and specifies that this key must not be usable |
| /// unless the user provides confirmation of the data to be signed |
| TrustedConfirmationRequired, |
| /// The key may only be used when the device is unlocked |
| UnlockedDeviceRequired, |
| /// When provided to generateKey or importKey, this tag specifies data |
| /// that is necessary during all uses of the key |
| ApplicationID(Vec<u8>), |
| /// When provided to generateKey or importKey, this tag specifies data |
| /// that is necessary during all uses of the key |
| ApplicationData(Vec<u8>), |
| /// Specifies the date and time the key was created |
| CreationDateTime(u64), |
| /// Specifies where the key was created, if known |
| KeyOrigin(KeyOrigin), |
| /// The key used by verified boot to validate the operating system booted |
| RootOfTrust(Vec<u8>), |
| /// System OS version with which the key may be used |
| OSVersion(u32), |
| /// Specifies the system security patch level with which the key may be used |
| OSPatchLevel(u32), |
| /// Specifies a unique, time-based identifier |
| UniqueID(Vec<u8>), |
| /// Used to deliver a "challenge" value to the attestKey() method |
| AttestationChallenge(Vec<u8>), |
| /// The set of applications which may use a key, used only with attestKey() |
| AttestationApplicationID(Vec<u8>), |
| /// Provides the device's brand name, to attestKey() |
| AttestationIdBrand(Vec<u8>), |
| /// Provides the device's device name, to attestKey() |
| AttestationIdDevice(Vec<u8>), |
| /// Provides the device's product name, to attestKey() |
| AttestationIdProduct(Vec<u8>), |
| /// Provides the device's serial number, to attestKey() |
| AttestationIdSerial(Vec<u8>), |
| /// Provides the IMEIs for all radios on the device, to attestKey() |
| AttestationIdIMEI(Vec<u8>), |
| /// Provides the MEIDs for all radios on the device, to attestKey() |
| AttestationIdMEID(Vec<u8>), |
| /// Provides the device's manufacturer name, to attestKey() |
| AttestationIdManufacturer(Vec<u8>), |
| /// Provides the device's model name, to attestKey() |
| AttestationIdModel(Vec<u8>), |
| /// Specifies the vendor image security patch level with which the key may be used |
| VendorPatchLevel(u32), |
| /// Specifies the boot image (kernel) security patch level with which the key may be used |
| BootPatchLevel(u32), |
| /// Provides "associated data" for AES-GCM encryption or decryption |
| AssociatedData(Vec<u8>), |
| /// Provides or returns a nonce or Initialization Vector (IV) for AES-GCM, |
| /// AES-CBC, AES-CTR, or 3DES-CBC encryption or decryption |
| Nonce(Vec<u8>), |
| /// Provides the requested length of a MAC or GCM authentication tag, in bits |
| MacLength(u32), |
| /// Specifies whether the device has been factory reset since the |
| /// last unique ID rotation. Used for key attestation |
| ResetSinceIdRotation, |
| /// Used to deliver a cryptographic token proving that the user |
| /// confirmed a signing request |
| ConfirmationToken(Vec<u8>), |
| } |
| |
| impl KeyParameter { |
| /// Create an instance of KeyParameter, given the value and the security level. |
| pub fn new(key_parameter_value: KeyParameterValue, security_level: SecurityLevel) -> Self { |
| KeyParameter { key_parameter_value, security_level } |
| } |
| |
| /// Returns the tag given the KeyParameter instance. |
| pub fn get_tag(&self) -> Tag { |
| match self.key_parameter_value { |
| KeyParameterValue::Invalid => Tag::INVALID, |
| KeyParameterValue::KeyPurpose(_) => Tag::PURPOSE, |
| KeyParameterValue::Algorithm(_) => Tag::ALGORITHM, |
| KeyParameterValue::KeySize(_) => Tag::KEY_SIZE, |
| KeyParameterValue::BlockMode(_) => Tag::BLOCK_MODE, |
| KeyParameterValue::Digest(_) => Tag::DIGEST, |
| KeyParameterValue::PaddingMode(_) => Tag::PADDING, |
| KeyParameterValue::CallerNonce => Tag::CALLER_NONCE, |
| KeyParameterValue::MinMacLength(_) => Tag::MIN_MAC_LENGTH, |
| KeyParameterValue::EcCurve(_) => Tag::EC_CURVE, |
| KeyParameterValue::RSAPublicExponent(_) => Tag::RSA_PUBLIC_EXPONENT, |
| KeyParameterValue::IncludeUniqueID => Tag::INCLUDE_UNIQUE_ID, |
| KeyParameterValue::KeyBlobUsageRequirements(_) => Tag::BLOB_USAGE_REQUIREMENTS, |
| KeyParameterValue::BootLoaderOnly => Tag::BOOTLOADER_ONLY, |
| KeyParameterValue::RollbackResistance => Tag::ROLLBACK_RESISTANCE, |
| KeyParameterValue::ActiveDateTime(_) => Tag::ACTIVE_DATETIME, |
| KeyParameterValue::OriginationExpireDateTime(_) => Tag::ORIGINATION_EXPIRE_DATETIME, |
| KeyParameterValue::UsageExpireDateTime(_) => Tag::USAGE_EXPIRE_DATETIME, |
| KeyParameterValue::MinSecondsBetweenOps(_) => Tag::MIN_SECONDS_BETWEEN_OPS, |
| KeyParameterValue::MaxUsesPerBoot(_) => Tag::MAX_USES_PER_BOOT, |
| KeyParameterValue::UserID(_) => Tag::USER_ID, |
| KeyParameterValue::UserSecureID(_) => Tag::USER_SECURE_ID, |
| KeyParameterValue::NoAuthRequired => Tag::NO_AUTH_REQUIRED, |
| KeyParameterValue::HardwareAuthenticatorType(_) => Tag::USER_AUTH_TYPE, |
| KeyParameterValue::AuthTimeout(_) => Tag::AUTH_TIMEOUT, |
| KeyParameterValue::AllowWhileOnBody => Tag::ALLOW_WHILE_ON_BODY, |
| KeyParameterValue::TrustedUserPresenceRequired => Tag::TRUSTED_USER_PRESENCE_REQUIRED, |
| KeyParameterValue::TrustedConfirmationRequired => Tag::TRUSTED_CONFIRMATION_REQUIRED, |
| KeyParameterValue::UnlockedDeviceRequired => Tag::UNLOCKED_DEVICE_REQUIRED, |
| KeyParameterValue::ApplicationID(_) => Tag::APPLICATION_ID, |
| KeyParameterValue::ApplicationData(_) => Tag::APPLICATION_DATA, |
| KeyParameterValue::CreationDateTime(_) => Tag::CREATION_DATETIME, |
| KeyParameterValue::KeyOrigin(_) => Tag::ORIGIN, |
| KeyParameterValue::RootOfTrust(_) => Tag::ROOT_OF_TRUST, |
| KeyParameterValue::OSVersion(_) => Tag::OS_VERSION, |
| KeyParameterValue::OSPatchLevel(_) => Tag::OS_PATCHLEVEL, |
| KeyParameterValue::UniqueID(_) => Tag::UNIQUE_ID, |
| KeyParameterValue::AttestationChallenge(_) => Tag::ATTESTATION_CHALLENGE, |
| KeyParameterValue::AttestationApplicationID(_) => Tag::ATTESTATION_APPLICATION_ID, |
| KeyParameterValue::AttestationIdBrand(_) => Tag::ATTESTATION_ID_BRAND, |
| KeyParameterValue::AttestationIdDevice(_) => Tag::ATTESTATION_ID_DEVICE, |
| KeyParameterValue::AttestationIdProduct(_) => Tag::ATTESTATION_ID_PRODUCT, |
| KeyParameterValue::AttestationIdSerial(_) => Tag::ATTESTATION_ID_SERIAL, |
| KeyParameterValue::AttestationIdIMEI(_) => Tag::ATTESTATION_ID_IMEI, |
| KeyParameterValue::AttestationIdMEID(_) => Tag::ATTESTATION_ID_MEID, |
| KeyParameterValue::AttestationIdManufacturer(_) => Tag::ATTESTATION_ID_MANUFACTURER, |
| KeyParameterValue::AttestationIdModel(_) => Tag::ATTESTATION_ID_MODEL, |
| KeyParameterValue::VendorPatchLevel(_) => Tag::VENDOR_PATCHLEVEL, |
| KeyParameterValue::BootPatchLevel(_) => Tag::BOOT_PATCHLEVEL, |
| KeyParameterValue::AssociatedData(_) => Tag::ASSOCIATED_DATA, |
| KeyParameterValue::Nonce(_) => Tag::NONCE, |
| KeyParameterValue::MacLength(_) => Tag::MAC_LENGTH, |
| KeyParameterValue::ResetSinceIdRotation => Tag::RESET_SINCE_ID_ROTATION, |
| KeyParameterValue::ConfirmationToken(_) => Tag::CONFIRMATION_TOKEN, |
| } |
| } |
| |
| /// Returns key parameter value. |
| pub fn key_parameter_value(&self) -> &KeyParameterValue { |
| &self.key_parameter_value |
| } |
| |
| /// Returns the security level of a KeyParameter. |
| pub fn security_level(&self) -> &SecurityLevel { |
| &self.security_level |
| } |
| } |
| |
| #[cfg(test)] |
| mod basic_tests { |
| use crate::key_parameter::*; |
| use crate::keymint_definitions::{SecurityLevel, Tag}; |
| |
| // Test basic functionality of KeyParameter. |
| #[test] |
| fn test_key_parameter() { |
| let key_parameter = KeyParameter::new( |
| KeyParameterValue::Algorithm(Algorithm::RSA), |
| SecurityLevel::STRONGBOX, |
| ); |
| |
| assert_eq!(key_parameter.get_tag(), Tag::ALGORITHM); |
| |
| assert_eq!( |
| *key_parameter.key_parameter_value(), |
| KeyParameterValue::Algorithm(Algorithm::RSA) |
| ); |
| |
| assert_eq!(*key_parameter.security_level(), SecurityLevel::STRONGBOX); |
| } |
| } |