script_webcrypto/subtlecrypto/

hmac_operation.rs

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */

use aws_lc_rs::constant_time::verify_slices_are_equal;
use aws_lc_rs::hmac;
use js::context::JSContext;
use rand::TryRng;
use rand::rngs::SysRng;
use script_bindings::codegen::GenericBindings::CryptoKeyBinding::{
    CryptoKeyMethods, KeyType, KeyUsage,
};
use script_bindings::codegen::GenericBindings::SubtleCryptoBinding::{JsonWebKey, KeyFormat};
use script_bindings::domstring::DOMString;
use script_bindings::error::Error;
use script_bindings::root::DomRoot;
use zeroize::Zeroizing;

use crate::cryptokey::{CryptoKey, Handle, KeyUsageSliceHelper};
use crate::subtlecrypto::{
    CryptoAlgorithm, ExportedKey, HmacImportParams, HmacKeyAlgorithm, HmacKeyGenParams,
    JsonWebKeyExt, JwkStringField, KeyAlgorithmAndDerivatives, NormalizedAlgorithm,
};
use crate::traits::Equivalence;

/// <https://w3c.github.io/webcrypto/#hmac-operations-sign>
pub(crate) fn sign<D: Equivalence>(key: &CryptoKey<D>, message: &[u8]) -> Result<Vec<u8>, Error> {
    // Step 1. Let mac be the result of performing the MAC Generation operation described in
    // Section 4 of [FIPS-198-1] using the key represented by the [[handle]] internal slot of key,
    // the hash function identified by the hash attribute of the [[algorithm]] internal slot of key
    // and message as the input data text.
    let hash_function = match key.algorithm() {
        KeyAlgorithmAndDerivatives::HmacKeyAlgorithm(algo) => match algo.hash.name() {
            CryptoAlgorithm::Sha1 => hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY,
            CryptoAlgorithm::Sha256 => hmac::HMAC_SHA256,
            CryptoAlgorithm::Sha384 => hmac::HMAC_SHA384,
            CryptoAlgorithm::Sha512 => hmac::HMAC_SHA512,
            _ => {
                return Err(Error::NotSupported(Some(
                    "Unsupported hash algorithm for HMAC".into(),
                )));
            },
        },
        _ => {
            return Err(Error::NotSupported(Some(
                "The key algorithm is not HMAC".into(),
            )));
        },
    };
    let sign_key = hmac::Key::new(hash_function, key.handle().as_bytes());
    let mac = hmac::sign(&sign_key, message);

    // Step 2. Return mac.
    Ok(mac.as_ref().to_vec())
}

/// <https://w3c.github.io/webcrypto/#hmac-operations-verify>
pub(crate) fn verify<D: Equivalence>(
    key: &CryptoKey<D>,
    message: &[u8],
    signature: &[u8],
) -> Result<bool, Error> {
    // Step 1. Let mac be the result of performing the MAC Generation operation described in
    // Section 4 of [FIPS-198-1] using the key represented by the [[handle]] internal slot of key,
    // the hash function identified by the hash attribute of the [[algorithm]] internal slot of key
    // and message as the input data text.
    let hash_function = match key.algorithm() {
        KeyAlgorithmAndDerivatives::HmacKeyAlgorithm(algo) => match algo.hash.name() {
            CryptoAlgorithm::Sha1 => hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY,
            CryptoAlgorithm::Sha256 => hmac::HMAC_SHA256,
            CryptoAlgorithm::Sha384 => hmac::HMAC_SHA384,
            CryptoAlgorithm::Sha512 => hmac::HMAC_SHA512,
            _ => {
                return Err(Error::NotSupported(Some(
                    "Unsupported hash algorithm for HMAC".into(),
                )));
            },
        },
        _ => {
            return Err(Error::NotSupported(Some(
                "The key algorithm is not HMAC".into(),
            )));
        },
    };
    let sign_key = hmac::Key::new(hash_function, key.handle().as_bytes());
    let mac = hmac::sign(&sign_key, message);

    // Step 2. Return true if mac is equal to signature and false otherwise. This comparison must
    // be performed in constant-time.
    Ok(verify_slices_are_equal(mac.as_ref(), signature).is_ok())
}

/// <https://w3c.github.io/webcrypto/#hmac-operations-generate-key>
pub(crate) fn generate_key<D: Equivalence>(
    cx: &mut JSContext,
    global: &D::GlobalScope,
    normalized_algorithm: &HmacKeyGenParams,
    extractable: bool,
    usages: Vec<KeyUsage>,
) -> Result<DomRoot<CryptoKey<D>>, Error> {
    // Step 1. If usages contains any entry which is not "sign" or "verify", then throw a
    // SyntaxError.
    usages.ensure_only_contain_entries_from(&[KeyUsage::Sign, KeyUsage::Verify])?;

    // Step 2.
    let length = match normalized_algorithm.length {
        // If the length member of normalizedAlgorithm is not present:
        None => {
            // Let length be the block size in bits of the hash function identified by the
            // hash member of normalizedAlgorithm.
            hash_function_block_size_in_bits(normalized_algorithm.hash.name())?
        },
        // Otherwise, if the length member of normalizedAlgorithm is non-zero:
        Some(length) if length != 0 => {
            // Let length be equal to the length member of normalizedAlgorithm.
            length
        },
        // Otherwise:
        _ => {
            // throw an OperationError.
            return Err(Error::Operation(Some(
                "The length member of normalizedAlgorithm is zero".into(),
            )));
        },
    };

    // Step 3. Generate a key of length length bits.
    // Step 4. If the key generation step fails, then throw an OperationError.
    let mut key_data = vec![0; length as usize];
    if SysRng.try_fill_bytes(&mut key_data).is_err() {
        return Err(Error::JSFailed);
    }

    // Step 6. Let algorithm be a new HmacKeyAlgorithm.
    // Step 7. Set the name attribute of algorithm to "HMAC".
    // Step 8. Set the length attribute of algorithm to length.
    // Step 9. Let hash be a new KeyAlgorithm.
    // Step 10. Set the name attribute of hash to equal the name member of the hash member of
    // normalizedAlgorithm.
    // Step 11. Set the hash attribute of algorithm to hash.
    let algorithm = HmacKeyAlgorithm {
        name: CryptoAlgorithm::Hmac,
        hash: normalized_algorithm.hash.clone(),
        length,
    };

    // Step 5. Let key be a new CryptoKey object representing the generated key.
    // Step 12. Set the [[type]] internal slot of key to "secret".
    // Step 13. Set the [[algorithm]] internal slot of key to algorithm.
    // Step 14. Set the [[extractable]] internal slot of key to be extractable.
    // Step 15. Set the [[usages]] internal slot of key to be the normalized value of usages.
    let key = CryptoKey::new(
        cx,
        global,
        KeyType::Secret,
        extractable,
        KeyAlgorithmAndDerivatives::HmacKeyAlgorithm(algorithm),
        usages.normalized_value(),
        Handle::Hmac(key_data.into()),
    );

    // Step 16. Return key.
    Ok(key)
}

/// <https://w3c.github.io/webcrypto/#hmac-operations-import-key>
pub(crate) fn import_key<D: Equivalence>(
    cx: &mut JSContext,
    global: &D::GlobalScope,
    normalized_algorithm: &HmacImportParams,
    format: KeyFormat,
    key_data: &[u8],
    extractable: bool,
    usages: Vec<KeyUsage>,
) -> Result<DomRoot<CryptoKey<D>>, Error> {
    // Step 1. If the length member of normalizedAlgorithm is present and is zero, then throw a
    // DataError.
    if normalized_algorithm
        .length
        .is_some_and(|length| length == 0)
    {
        return Err(Error::Data(Some(
            "The length member of normalizedAlgorithm is present and is zero".into(),
        )));
    }

    // Step 2. Let keyData be the key data to be imported.

    // Step 3. If usages contains an entry which is not "sign" or "verify", then throw a SyntaxError.
    usages.ensure_only_contain_entries_from(&[KeyUsage::Sign, KeyUsage::Verify])?;

    // Step 4. Let hash be a new KeyAlgorithm.
    let hash;

    // Step 5.
    let data: Zeroizing<Vec<u8>>;
    match format {
        // If format is "raw":
        KeyFormat::Raw | KeyFormat::Raw_secret => {
            // Step 5.1. Let data be keyData.
            data = key_data.to_vec().into();

            // Step 5.2. Set hash to equal the hash member of normalizedAlgorithm.
            hash = &normalized_algorithm.hash;
        },
        // If format is "jwk":
        KeyFormat::Jwk => {
            // Step 5.1. If keyData is a JsonWebKey dictionary: Let jwk equal keyData.
            // Otherwise: Throw a DataError.
            // NOTE: Deserialize keyData to JsonWebKey dictionary by running JsonWebKey::parse
            let jwk = JsonWebKey::parse(cx, key_data)?;

            // Step 5.2. If the kty field of jwk is not "oct", then throw a DataError.
            if jwk.kty.as_ref().is_none_or(|kty| kty != "oct") {
                return Err(Error::Data(Some(
                    "The kty field of jwk is not \"oct\"".into(),
                )));
            }

            // Step 5.3. If jwk does not meet the requirements of Section 6.4 of JSON Web
            // Algorithms [JWA], then throw a DataError.
            // NOTE: Done by Step 5.4 and 5.6.

            // Step 5.4. Let data be the byte sequence obtained by decoding the k field of jwk.
            data = jwk.decode_required_string_field(JwkStringField::K)?;

            // Step 5.5. Set the hash to equal the hash member of normalizedAlgorithm.
            hash = &normalized_algorithm.hash;

            // Step 5.6.
            match hash.name() {
                // If the name attribute of hash is "SHA-1":
                CryptoAlgorithm::Sha1 => {
                    // If the alg field of jwk is present and is not "HS1", then throw a DataError.
                    if jwk.alg.as_ref().is_some_and(|alg| alg != "HS1") {
                        return Err(Error::Data(Some(
                            "The alg field of jwk is present, and is not \"HS1\"".into(),
                        )));
                    }
                },
                // If the name attribute of hash is "SHA-256":
                CryptoAlgorithm::Sha256 => {
                    // If the alg field of jwk is present and is not "HS256", then throw a DataError.
                    if jwk.alg.as_ref().is_some_and(|alg| alg != "HS256") {
                        return Err(Error::Data(Some(
                            "The alg field of jwk is present, and is not \"HS256\"".into(),
                        )));
                    }
                },
                // If the name attribute of hash is "SHA-384":
                CryptoAlgorithm::Sha384 => {
                    // If the alg field of jwk is present and is not "HS384", then throw a DataError.
                    if jwk.alg.as_ref().is_some_and(|alg| alg != "HS384") {
                        return Err(Error::Data(Some(
                            "The alg field of jwk is present, and is not \"HS384\"".into(),
                        )));
                    }
                },
                // If the name attribute of hash is "SHA-512":
                CryptoAlgorithm::Sha512 => {
                    // If the alg field of jwk is present and is not "HS512", then throw a DataError.
                    if jwk.alg.as_ref().is_some_and(|alg| alg != "HS512") {
                        return Err(Error::Data(Some(
                            "The alg field of jwk is present, and is not \"HS512\"".into(),
                        )));
                    }
                },
                // Otherwise,
                _name => {
                    // if the name attribute of hash is defined in another applicable specification:
                    // Perform any key import steps defined by other applicable specifications,
                    // passing format, jwk and hash and obtaining hash
                    // NOTE: Currently not support applicable specification.
                    return Err(Error::NotSupported(Some(
                        "Unsupported hash algorithm".into(),
                    )));
                },
            }

            // Step 5.7. If usages is non-empty and the use field of jwk is present and is not
            // "sig", then throw a DataError.
            if !usages.is_empty() && jwk.use_.as_ref().is_some_and(|use_| use_ != "sig") {
                return Err(Error::Data(Some(
                    "Usages is non-empty and the use field of jwk is present and is not \"sig\""
                        .into(),
                )));
            }

            // Step 5.8. If the key_ops field of jwk is present, and is invalid according to
            // the requirements of JSON Web Key [JWK] or does not contain all of the specified
            // usages values, then throw a DataError.
            jwk.check_key_ops(&usages)?;

            // Step 5.9. If the ext field of jwk is present and has the value false and
            // extractable is true, then throw a DataError.
            if jwk.ext.is_some_and(|ext| !ext) && extractable {
                return Err(Error::Data(Some(
                    "The ext field of jwk is present and has the value false and extractable is true"
                        .into(),
                )));
            }
        },
        // Otherwise:
        _ => {
            // throw a NotSupportedError.
            return Err(Error::NotSupported(Some(
                "Unsupported import key format for HMAC key".into(),
            )));
        },
    }

    // Step 6. Let length be the length in bits of data.
    let mut length = data.len() as u32 * 8;

    // Step 7. If length is zero then throw a DataError.
    if length == 0 {
        return Err(Error::Data(Some(
            "The length in bits of data is zero".into(),
        )));
    }

    // Step 8. If the length member of normalizedAlgorithm is present:
    if let Some(given_length) = normalized_algorithm.length {
        //  If the length member of normalizedAlgorithm is greater than length:
        if given_length > length {
            // throw a DataError.
            return Err(Error::Data(Some(
                "The length member of normalizedAlgorithm is greater than the length in bits of data"
                    .into(),
            )));
        }
        // Otherwise:
        else {
            // Set length equal to the length member of normalizedAlgorithm.
            length = given_length;
        }
    }

    // Step 9. Let key be a new CryptoKey object representing an HMAC key with the first length
    // bits of data.
    // Step 10. Set the [[type]] internal slot of key to "secret".
    // Step 11. Let algorithm be a new HmacKeyAlgorithm.
    // Step 12. Set the name attribute of algorithm to "HMAC".
    // Step 13. Set the length attribute of algorithm to length.
    // Step 14. Set the hash attribute of algorithm to hash.
    // Step 15. Set the [[algorithm]] internal slot of key to algorithm.
    let algorithm = HmacKeyAlgorithm {
        name: CryptoAlgorithm::Hmac,
        hash: hash.clone(),
        length,
    };
    let truncated_data = data[..length as usize / 8].to_vec();
    let key = CryptoKey::new(
        cx,
        global,
        KeyType::Secret,
        extractable,
        KeyAlgorithmAndDerivatives::HmacKeyAlgorithm(algorithm),
        usages.normalized_value(),
        Handle::Hmac(truncated_data.into()),
    );

    // Step 16. Return key.
    Ok(key)
}

/// <https://w3c.github.io/webcrypto/#hmac-operations-export-key>
pub(crate) fn export_key<D: Equivalence>(
    format: KeyFormat,
    key: &CryptoKey<D>,
) -> Result<ExportedKey, Error> {
    match format {
        KeyFormat::Raw | KeyFormat::Raw_secret => match key.handle() {
            Handle::Hmac(key_data) => Ok(ExportedKey::new_bytes(key_data.as_slice().to_vec())),
            _ => Err(Error::Operation(Some(
                "The key handle is not representing an HMAC key".into(),
            ))),
        },
        KeyFormat::Jwk => {
            // Step 4.1. Let jwk be a new JsonWebKey dictionary.
            let mut jwk = JsonWebKey::default();

            // Step 4.2. Set the kty attribute of jwk to the string "oct".
            jwk.kty = Some(DOMString::from_static("oct"));

            // Step 4.3. Set the k attribute of jwk to be a string containing data, encoded according
            // to Section 6.4 of JSON Web Algorithms [JWA].
            let key_data = key.handle().as_bytes();
            jwk.encode_string_field(JwkStringField::K, key_data);

            // Step 4.4. Let algorithm be the [[algorithm]] internal slot of key.
            // Step 4.5. Let hash be the hash attribute of algorithm.
            // Step 4.6.
            // If the name attribute of hash is "SHA-1":
            //     Set the alg attribute of jwk to the string "HS1".
            // If the name attribute of hash is "SHA-256":
            //     Set the alg attribute of jwk to the string "HS256".
            // If the name attribute of hash is "SHA-384":
            //     Set the alg attribute of jwk to the string "HS384".
            // If the name attribute of hash is "SHA-512":
            //     Set the alg attribute of jwk to the string "HS512".
            // Otherwise, the name attribute of hash is defined in another applicable
            // specification:
            //     Perform any key export steps defined by other applicable specifications, passing
            //     format and key and obtaining alg.
            //     Set the alg attribute of jwk to alg.
            let hash_algorithm = match key.algorithm() {
                KeyAlgorithmAndDerivatives::HmacKeyAlgorithm(algorithm) => {
                    match algorithm.hash.name() {
                        CryptoAlgorithm::Sha1 => "HS1",
                        CryptoAlgorithm::Sha256 => "HS256",
                        CryptoAlgorithm::Sha384 => "HS384",
                        CryptoAlgorithm::Sha512 => "HS512",
                        _ => {
                            return Err(Error::NotSupported(Some(
                                "Unsupported hash algorithm for HMAC".into(),
                            )));
                        },
                    }
                },
                _ => {
                    return Err(Error::NotSupported(Some(
                        "The key algorithm is not HMAC".into(),
                    )));
                },
            };
            jwk.alg = Some(DOMString::from(hash_algorithm));

            // Step 4.7. Set the key_ops attribute of jwk to the usages attribute of key.
            jwk.set_key_ops(key.usages());

            // Step 4.8. Set the ext attribute of jwk to the [[extractable]] internal slot of key.
            jwk.ext = Some(key.Extractable());

            // Step 4.9. Let result be jwk.
            Ok(ExportedKey::new_jwk(jwk))
        },
        // Otherwise:
        _ => {
            // throw a NotSupportedError.
            Err(Error::NotSupported(Some(
                "Unsupported export key format for HMAC key".into(),
            )))
        },
    }
}

/// <https://w3c.github.io/webcrypto/#hmac-operations-get-key-length>
pub(crate) fn get_key_length(
    normalized_derived_key_algorithm: &HmacImportParams,
) -> Result<Option<u32>, Error> {
    // Step 1.
    let length = match normalized_derived_key_algorithm.length {
        // If the length member of normalizedDerivedKeyAlgorithm is not present:
        None => {
            // Let length be the block size in bits of the hash function identified by the hash
            // member of normalizedDerivedKeyAlgorithm.
            hash_function_block_size_in_bits(normalized_derived_key_algorithm.hash.name())?
        },
        // Otherwise, if the length member of normalizedDerivedKeyAlgorithm is non-zero:
        Some(length) if length != 0 => {
            // Let length be equal to the length member of normalizedDerivedKeyAlgorithm.
            length
        },
        // Otherwise:
        _ => {
            // throw a TypeError.
            return Err(Error::Type(c"[[length]] must not be zero".to_owned()));
        },
    };

    // Step 2. Return length.
    Ok(Some(length))
}

/// Return the block size in bits of a hash function, according to Figure 1 of
/// <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf>.
fn hash_function_block_size_in_bits(hash: CryptoAlgorithm) -> Result<u32, Error> {
    match hash {
        CryptoAlgorithm::Sha1 => Ok(512),
        CryptoAlgorithm::Sha256 => Ok(512),
        CryptoAlgorithm::Sha384 => Ok(1024),
        CryptoAlgorithm::Sha512 => Ok(1024),
        _ => Err(Error::NotSupported(Some(
            "Unidentified hash member".to_string(),
        ))),
    }
}