🔐 REL-ID SDK: getTOTPPassword Event and setTOTPPassword API

This document provides a complete reference for handling password-based TOTP generation in the REL-ID SDK.

🔁 Event: getTOTPPassword

🧭 Overview

Triggered when the SDK requires the user's password to proceed with generating a TOTP. This typically happens in offline or fallback authentication scenarios when LDA (e.g., fingerprint or pattern) is not available.

🔐 Conditions for triggering getTOTPPassword

getTOTPPassword may still be triggered by the SDK when:

• LDA is not available or disabled
• SDK policy requires password confirmation before TOTP generation
• Offline mode is enabled and cached password fallback is required

🧾 UI Guidelines

• Display a clear message like:

  “Please enter your REL-ID password to generate your one-time password (TOTP).”

• Use masked input for the password field.
• Clearly indicate the number of attempts remaining if attemptsLeft is provided.

📦 Sample Payload

{
  "userID": "ad3",
  "challengeMode": 0,
  "attemptsLeft": 3,
  "challengeResponse": {},
  "error": {
    "longErrorCode": 0,
    "shortErrorCode": 0,
    "errorString": "Success"
  }
}

📥 Payload Fields

💻 Platform Handling

let getTOTPPasswordSubscription = rdnaEventRegistery.addListener(
  'getTOTPPassword',
  this.getTOTPPassword.bind(this)
);

rdnaClient.on(RdnaClient.getTOTPPassword, (response) {
  print("Password required for TOTP: ${response.userID}");
});

document.addEventListener('getTOTPPassword', function(e) {
  console.log("Prompt password input for:", e.userID);
});

(void)getTOTPPassword:(NSString *)userID
       challengeMode:(RDNAChallengeOpMode)mode
        attemptsLeft:(int)attemptsLeft
             response:(RDNAChallengeResponse *)response
                error:(RDNAError *)error;

void getTOTPPassword(String userID, int challengeMode, int attemptsLeft,
    RDNAChallengeResponse challengeResponse, RDNAError error);

🛠️ API: setTOTPPassword

🧭 Overview

Used to submit the password provided by the user in response to the getTOTPPassword event. Upon validation, the SDK proceeds to generate the TOTP.

📥 Parameters

💻 Platform Usage

RdnaClient.setTOTPPassword("userEnteredPassword", (response) => {
  console.log("TOTP password response:", response);
});

await rdnaClient.setTOTPPassword("userPassword123");

com.uniken.rdnaplugin.RdnaClient.setTOTPPassword(
  () => console.log("Password submitted"),
  (err) => console.error("Password error", err),
  ["userPassword123"]
);

[client setTOTPPassword:@"userPassword123"];

rdnaClient.setTOTPPassword("userPassword123");

✅ On Success

• Password is validated.
• SDK proceeds to generate TOTP → onTOTPGenerated event.

❌ On Failure

• App should show retry prompt or fallback to other method if available.
• Check attemptsLeft field from getTOTPPassword event.

Error codes for getTOTPPassword

🧠 Key Point

REL-ID treats TOTP generation as a sensitive action, often requiring user confirmation even after login, especially when no biometric (LDA) is in place.