LogoLogo
  • Platform Overview
  • 🗺️Guides
    • Getting Started
    • Users
      • Integrate the User SDK
      • Registration
      • Authentication
      • SDK Releases
      • API Reference
    • Entitlements
      • Administrative API
        • Integrating the Administrative API
        • Entitlement Definitions
        • Managing Entitlements Sets
        • Managing Entitlements Sequences
        • Managing User Entitlements
        • API Schema
      • End-user API
        • Integrate the Entitlements SDK
        • Redeeming Entitlements
        • Retrieving Entitlements
        • SDK Releases
        • API Reference
    • Sudos
      • Integrate the Sudo Profiles SDK
      • Sudo Entitlements
      • Manage Sudos
      • SDK Releases
      • API Reference
    • Telephony
      • Integrate the Telephony SDK
      • Manage Phone Numbers
      • Text Messaging
      • Voice Calling
      • Telephony Simulator
      • SDK Releases
      • API Reference
    • Email
      • Integrate the Email SDK
      • Email Entitlements
      • Manage Email Addresses
      • Sending & Receiving Email
      • Manage Email Folders
      • Draft Email Messages
      • Manage Email Address Blocklists
      • Email Address Public Information
      • Pagination
      • Caching
      • Configuration Data
      • Email Notifications
      • SDK Releases
      • API Reference
    • Decentralized Identity
      • Edge Agent
        • Relay SDK
          • Integrate the Relay SDK
          • Relay Entitlements
          • Manage Relay Postboxes
          • Manage Relay Messages
          • Receiving Messages
          • SDK Releases
        • Edge Agent SDK
          • Integrate the Edge Agent SDK
          • Agent Management
          • Manage Wallets
          • Establishing Connections
          • Manage Connections
          • Messaging
          • Manage DIDs
          • Accepting New Credentials
          • Manage Credentials
          • Present Credentials for Verification
          • Utilize Alternative Cryptography Providers
          • SDK Releases
          • Standards and Protocols
      • Cloud Agent
        • Cloud Agent Admin API
          • Integrate the Cloud Agent Admin API
          • Aries Interop Profile (AIP)
            • Connection Exchanges
            • Credential Exchanges
            • Proof Exchanges
          • Connections
          • Basic Messages
          • Credentials
            • Anoncreds Credentials
              • Schemas
              • Credential Definitions
            • W3C Credentials
          • Audit Logs
          • API Schema
          • Error Codes
          • Standards and Protocols
    • Virtual Cards
      • Integrate the Virtual Cards SDK
      • Virtual Cards Entitlements
      • Virtual Cards Transaction Velocity Constraints
      • Key Management
      • Manage Funding Sources
      • Manage Virtual Cards
      • Manage Transactions
      • Configuration Data
      • Pagination
      • Caching
      • SDK Releases
      • API Reference
    • Virtual Cards Simulator
      • Integrate the Virtual Cards Simulator SDK
      • Simulate Authorizations
      • Simulate Debits
      • Simulate Refunds
      • Simulate Reversals
      • Merchants and Currencies
      • SDK Releases
      • API Reference
    • Virtual Private Network
      • Integrate the VPN SDK
      • VPN Entitlements
      • Manage Servers
      • Manage Connection
      • Observe VPN Related Events
      • SDK Releases
      • API Reference
      • Frequently Asked Questions
    • Secure ID Verification
      • Integrate the Secure ID Verification SDK
      • List Supported Countries
      • Verify an Identity
      • Check Secure ID Verification Status
      • Use the Secure ID Verification Simulator
      • SDK Releases
      • API Reference
    • Password Manager
      • Integrate the Password Manager SDK
      • Accessing the Password Manager
      • Managing Password Vaults
      • Managing Password Vault Items
      • Vault Import and Export
      • Password Utilities
      • Password Manager Entitlements
      • Password Vault Security
      • SDK Releases
      • API Reference
    • Ad/Tracker Blocker
      • Integrate the Ad/Tracker Blocker SDK
      • Manage Rulesets
      • Blocking Ads and Trackers
      • Manage Exceptions
      • SDK Releases
      • API Reference
    • Site Reputation
      • Integrate the Site Reputation SDK
      • Use the Site Reputation SDK
      • SDK Releases
      • API Reference
  • 💡Concepts
    • Sudo Digital Identities
  • 🧱Development
    • Versioning
  • 🏢Administration
    • Admin Console Roles
  • ❓Get Help
    • Request a Demo
    • Report an Issue
Powered by GitBook
On this page
  • Setting Up the Password Manager Client
  • Registering to Use the Password Manager
  • Unlocking the Password Manager
  • Locking the Password Manager
  • Accessing the Secret Code
  • Generating the Rescue Kit PDF
  • Changing the Master Password
  • Deregistering from the Password Manager
  1. Guides
  2. Password Manager

Accessing the Password Manager

Setting up and managing access to the Password Manager

Setting Up the Password Manager Client

The first step in accessing the Password Manager is to check the registration status by calling the getRegistrationStatus method.

import { RegistrationStatus } from '@sudoplatform/sudo-password-manager'

const status = await client.getRegistrationStatus()
switch (status) {
  case RegistrationStatus.Unregistered:
    // call client.register()
    break
  case RegistrationStatus.SecretCodeRequired:
    // provide the secret code
    // using client.unlock(password, secretCode)
    break
  case RegistrationStatus.Registered:
    // the vault may be unlocked
    // using client.unlock(password)
    break
}
var client: PasswordManagerClient!

client.getRegistrationStatus { (result) in
    switch result {
    case .success(let status):
        switch status {
        case .registered:
            break
        case .notRegistered:
            break
        case .missingSecretCode:
            break
        }
    case .failure(let error):
        break
    }
}
// val client: SudoPasswordManagerClient

launch {
    try {
        val status = withContext(Dispatchers.IO) {
            client.getRegistrationStatus()
        }
        when(status) {
            PasswordManagerRegistrationStatus.REGISTERED -> {}
            PasswordManagerRegistrationStatus.NOT_REGISTERED -> {}        
            PasswordManagerRegistrationStatus.MISSING_SECRET_CODE -> {}
        }
    } catch (e: SudoPasswordManagerException) {
        // Handle/notify user of exception
    }
}

If the client is successful in fetching the registration status, a PasswordManagerRegistrationStatus will be returned. Inspect this value to determine what to do next to finish the setup of the Password Manager.

  • If the registration status is registered, the next step is unlocking the Password Manager before accessing items.

  • If the registration status is notRegistered, register the user by calling the register method and passing in the user's master password.

  • If the registration status is missingSecretCode, the user has already registered on another device. The Password Manager requires the user's master password and secret code. The user can find their secret code on their rescue kit PDF which was downloaded during onboarding.

Registering to Use the Password Manager

To register as a new user of the Password Manager, call the register method and pass in the user's master password. If successful, the client will be registered and the Password Manager will be unlocked and ready to create new vaults.

const masterPassword = 'P@ssw0rd!'

try {
    await client.register(masterPassword)
} catch {
    // handle/notify user of any registration errors
}
var client: PasswordManagerClient!

client.register(masterPassword: "Can'tCrackThis") { (result) in
    switch result {
        case .success:
            break
        case .failure(let error):
            break
    }
}
// val client: SudoPasswordManagerClient

launch {
    try {
        withContext(Dispatchers.IO) {
            client.register("P@SSw0rd!")
        }
    } catch (e: SudoPasswordManagerException) {
        // Handle/notify user of exception
    }
}

Unlocking the Password Manager

To access the Password Manager, it must first be unlocked by calling the unlock method and passing in the user's master password. This method also accepts the user's secret code, which is only required if the registration status returned by getRegistrationStatus is missingSecretCode.

An error will be returned by unlock if the secret code is not provided to unlock and not present on the user's device.

const masterPassword = 'P@ssw0rd!'

try {
    // if the client is already registered:
    await client.unlock(masterPassword)

    // otherwise, if the secret code is required:
    const secretCode = '012345-6789a-bcdef-01234-56789-abcdef'
    await client.unlock(masterPassword, secretCode)
} catch {
    // handle/notify user of any unlock errors
}
var client: PasswordManagerClient!

client.unlock(masterPassword: "P@ssw0rd!", secretCode: nil) { (result) in
    switch result {
        case .success:
            break
        case .failure(let error):
            break
    }
}
// val client: SudoPasswordManagerClient

launch {
    try {
        withContext(Dispatchers.IO) {
             val secretCode = client.getSecretCode()
             client.unlock("P@SSw0rd!", secretCode)
        }
    } catch (e: SudoPasswordManagerException) {
        // Handle/notify user of exception
    }
}

Once the Password Manager is unlocked, you can access create/access vaults and their contents.

Locking the Password Manager

You can use the isLocked method to synchronously determine if the Password Manager is locked. If isLocked returns false, then the next call to a method that accesses the Password Manager will not fail due to it being locked.

const isLocked = client.isLocked()
if (client.isLocked()) {
    // the password manager is locked.
    // use the unlock() method before accessing vaults.
} else {
    // the password manager is unlocked.
}
var client: PasswordManagerClient!

if client.isLocked() {
    // the password manager is locked.
    // use the unlock() method before accessing vaults.
} else {
    // the password manager is unlocked.
}
// val client: SudoPasswordManagerClient

if (client.isLocked()) {                        
     // the password manager is locked.
     // use the unlock() method before accessing vaults.
} else {
     // the password manager is unlocked.
}

You can use the lock method to lock the Password Manager. Use this method in response to user action or after a period of user inactivity.

client.lock()
// client.isLocked() will now return true.
var client: PasswordManagerClient!

client.lock()
// client.isLocked() will now return true.
// val client: SudoPasswordManagerClient

launch {
    try {
        withContext(Dispatchers.IO) {
            client.lock()
        }
        // client.isLocked() will now return true.
    } catch (e: SudoPasswordManagerException) {
        // Handle/notify user of exception
    }
}

Accessing the Secret Code

Both the master password and secret code must be present to unlock the Password Manager. The secret code is automatically generated during registration and stored on the user's device. To unlock an existing Password Manager for the first time on a new device, you must pass the secret code and master password into the unlock method. If the secret code is already stored on the user's device, you do not need to provide it in subsequent calls to the unlock method.

You can retrieve the secret code stored on the user's device using the showSecretCode method. You should take steps to ensure that the user does not lose their secret code. If they do, they will be unable to unlock their Password Manager vaults.

try {
    // assuming the client is already registered:
    const secretCode = await client.showSecretCode()
    console.log(secretCode)
} catch (error) {
    if (error instanceof VaultSecretCodeNotFound) {
        // the secret code has not been stored on this device.
    }
}
var client: PasswordManagerClient!

let secretCode = client.getSecretCode()
// returns an optional String
// val client: SudoPasswordManagerClient

val secretCode = client.getSecretCode()

Generating the Rescue Kit PDF

The Rescue Kit provides a way for users to save and print their secret code with the option to handwrite their master password and email address. This is part of the data recovery in case the user forgets or loses their keys. They should also store this in a safe location.

To generate the Rescue Kit PDF from the SDK you can provide your own PDF template or by default, it will use the Sudo Platform template.

// Default using the included Sudo Platform Template
const pdfBuffer = await client.renderRescueKit()

// Optional argument for a custom template.
const pdfTemplate = fs.readFileSync('./template.pdf')
const pdfBuffer = await client.renderRescueKit({
  pdfTemplate: pdfTemplate,
})
var client: PasswordManagerClient!
let document: PDFDocument? = client.renderRescueKit()
// val client: SudoPasswordManagerClient

val doc: PdfDocument = client.renderRescueKit(context)
// write file to cache directory or wherever you wish
val rescueKitFile = File(context.applicationContext.cacheDir, "RescueKit.pdf")
try {
    doc.writeTo(FileOutputStream(rescueKitFile))
} catch (e: SudoPasswordManagerException) {
    // handle error
}

Note that the Secret Code text is added in a specific location on the PDF. The custom template will need to use the same placement.

Changing the Master Password

To change the master password the Password Manager must be unlocked first. After the Password Manager is unlocked, use the changeMasterPassword method.

try {
    const newPassword = 'new-p4ssword'

    await client.changeMasterPassword(newPassword)
} catch (error) {
    // handle/notify user of any password change errors
}
var client: PasswordManagerClient!

guard client.isLocked() == false else { fatalError() }

client.changeMasterPassword(currentPassword: "P@ssw0rd1", newPassword: "N3WPassW0rd") { (result) in
    switch result {
    case .success:
        break
    case .failure(let error):
        break
    }
}
// val client: SudoPasswordManagerClient

launch {
    try {
        val currentPassword = "P@SSw0rd!"
        val newPassword = "N3WPassW0rd"
        withContext(Dispatchers.IO) {
             client.changeMasterPassword(currentPassword, newPassword)
        }
    } catch (e: SudoPasswordManagerException) {
        // Handle/notify user of exception
    }
}

Deregistering from the Password Manager

To deregister a user from the Password Manager and delete all created vaults and vault items, use the deregister method.

try {
    await client.deregister()
} catch (error) {
    // handle failure to deregister
}
var client: PasswordManagerClient!
try? client.deregister { (result) in
    switch result {
    case .success(let deregisteredUserID):
        break
    case .failure(let error):
        break
    }
}
// val client: SudoPasswordManagerClient

launch {
    try {
        withContext(Dispatchers.IO) {
             client.deregister()
        }
    } catch (e: SudoPasswordManagerException) {
        // Handle/notify user of exception
    }
}

To reset all local state saved by the Password Manager, such as secret codes that are stored on the user's device, use the reset method. Note that if the user has not backed up their secret code, they will be unable to subsequently log into the Password Manager and their vaults will be inaccessible.

client.reset()
/* Begins an asynchronous best-effort attempt to clear local data. */
var client: PasswordManagerClient!

client.reset()
// val client: SudoPasswordManagerClient

launch {
    try {
        withContext(Dispatchers.IO) {
             client.reset()
        }
    } catch (e: SudoPasswordManagerException) {
        // Handle/notify user of exception
    }
}
PreviousIntegrate the Password Manager SDKNextManaging Password Vaults

Last updated 28 days ago

🗺️
Password Manager Rescue Kit Example