A Developer’s Guide to Deriving Keys with WebAuthn PRF and YubiKeys

if (window.PublicKeyCredential &&
    typeof PublicKeyCredential.getClientCapabilities === 'function') {
    const caps = await PublicKeyCredential.getClientCapabilities("public-key");
    if (caps.extensions?.includes("prf")) {
        console.log("This browser supports the PRF extension.");
    }
}

// Enable the PRF capability for the new credential
const createOptions = {
  publicKey: {
    // ... other required publicKey options (rp, user, challenge, pubKeyCredParams)
    extensions: {
      prf: {} // The presence of the empty object enables the extension.
    }
  }
};

const newCredential = await navigator.credentials.create(createOptions);

// After creation, verify that the authenticator supports and enabled PRF.
const prfExtensionOutput = newCredential.getClientExtensionResults()?.prf;
if (prfExtensionOutput?.enabled) {
  console.log('✅ PRF was successfully enabled for this new credential.');
} else {
  console.log('⚠️ The authenticator does not support PRF or did not enable it.');
}

// For increased security, a unique, per-credential random salt should be
// generated by the server during registration and stored alongside the
// credential ID. For demonstration, we use a static salt here.
const encryptionSalt = new TextEncoder().encode('encryption-key-v1');

const getOptions = {
  publicKey: {
    // ... other required publicKey options (challenge, rpId)
    extensions: {
      prf: {
        eval: {
          first: encryptionSalt // Request evaluation using the salt
        }
      }
    }
  }
};

const assertion = await navigator.credentials.get(getOptions);
const prfResults = assertion.getClientExtensionResults()?.prf?.results?.first;

// This is the based on the FUNKE wwWallet keystore pattern.
if (prfResults) {
    // 1. First, import the raw PRF result as a master key for HKDF.
    //    This key's usage is restricted to only deriving other keys.
    const masterKey = await crypto.subtle.importKey(
        'raw',
        prfResults,
        'HKDF', // Specify that this key's algorithm is HKDF
        false,  // This key is not extractable
        ['deriveKey'] // It can ONLY be used to derive other keys
    );

    // 2. Now, derive a specific key for your purpose (e.g., AES-GCM).
    const aesKey = await crypto.subtle.deriveKey(
        {
            name: 'HKDF',
            salt: new Uint8Array(), // Salt can be empty if the masterKey is strong entropy, which PRF output is.
            hash: 'SHA-256',
            info: new TextEncoder().encode('AES-GCM Vault Encryption Key V1') // CRITICAL: Purpose-binding
        },
        masterKey, // The master key derived from the PRF secret
        { name: 'AES-GCM', length: 256 }, // The properties of the key you want to create footnote:[NIST-GCM: link:https://csrc.nist.gov/pubs/sp/800/38/d/final[NIST SP 800-38D Recommendation for AES-GCM]]
        false, // The final key should also be non-extractable
        ['encrypt', 'decrypt'] // The final key's intended usages
    );

    // Now use the derived `aesKey` for all encryption/decryption.
}

/**
 * Creates a new wrapped DEK for a newly registered authenticator.
 * @param {PublicKeyCredential} newCredential - The credential object from a successful create() call.
 * @param {CryptoKey} plaintextDEK - The plaintext Data Encryption Key held in the current session.
 * @returns {Promise<{credentialId: string, encryptedDEKBlob: ArrayBuffer}>} - The data to send to the server.
 */
async function createWrappedDEK(newCredential, plaintextDEK) {
    // 1. Get the PRF results from the new credential.
    //    This requires a get() call immediately after the create() call.
    const prfResults = await getPrfFromNewCredential(newCredential);

    // 2. Derive the new Key Encryption Key (KEK) using the recommended KDF pattern.
    const masterKey = await crypto.subtle.importKey('raw', prfResults, 'HKDF', false, ['deriveKey']);
    const newKEK = await crypto.subtle.deriveKey(
        { name: 'HKDF', salt: new Uint8Array(), hash: 'SHA-256', info: new TextEncoder().encode('DEK Wrapping Key V1') },
        masterKey,
        { name: 'AES-GCM', length: 256 },
        false,
        ['wrapKey'] // This key only needs to encrypt/wrap.
    );

    // 3. Generate a fresh, random 12-byte IV for this encryption operation.
    const newIv = crypto.getRandomValues(new Uint8Array(12));

    // 4. Encrypt (wrap) the plaintext DEK with the new KEK and the generated IV.
    //    For details on the parameters for AES-GCM, see the link:https://developer.mozilla.org/en-US/docs/Web/API/AesGcmParams[MDN Documentation].
    const wrappedDEK = await crypto.subtle.wrapKey(
        'raw',
        plaintextDEK,
        newKEK,
        { name: 'AES-GCM', iv: newIv }
    );

    // 5. Construct the final blob by prepending the IV to the ciphertext.
    //    This is the "envelope" that will be stored on the server.
    const encryptedDEKBlob = new Uint8Array(newIv.byteLength + wrappedDEK.byteLength);
    encryptedDEKBlob.set(new Uint8Array(newIv), 0);
    encryptedDEKBlob.set(new Uint8Array(wrappedDEK), newIv.byteLength);

    // 6. Return the new wrapped DEK blob to be stored on the server.
    return {
        credentialId: newCredential.id,
        encryptedDEKBlob: encryptedDEKBlob.buffer,
    };
}