Accessing the Password Manager

Search…
Setting Up the Password Manager Client
The first step in accessing the Password Manager is to check the registration status by calling the getRegistrationStatus function.
TypeScript
Swift
Kotlin
1
import { RegistrationStatus } from '@sudoplatform/sudo-password-manager'
2
​
3
const status = await client.getRegistrationStatus()
4
switch (status) {
5
  case RegistrationStatus.Unregistered:
6
    // call client.register()
7
    break
8
  case RegistrationStatus.SecretCodeRequired:
9
    // provide the secret code
10
    // using client.unlock(password, secretCode)
11
    break
12
  case RegistrationStatus.Registered:
13
    // the vault may be unlocked
14
    // using client.unlock(password)
15
    break
16
}
Copied!
1
var client: PasswordManagerClient!
2
​
3
client.getRegistrationStatus { (result) in
4
    switch result {
5
    case .success(let status):
6
        switch status {
7
        case .registered:
8
            break
9
        case .notRegistered:
10
            break
11
        case .missingSecretCode:
12
            break
13
        }
14
    case .failure(let error):
15
        break
16
    }
17
}
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
launch {
4
    try {
5
        val status = withContext(Dispatchers.IO) {
6
            client.getRegistrationStatus()
7
        }
8
        when(status) {
9
            PasswordManagerRegistrationStatus.REGISTERED -> {}
10
            PasswordManagerRegistrationStatus.NOT_REGISTERED -> {}        
11
            PasswordManagerRegistrationStatus.MISSING_SECRET_CODE -> {}
12
        }
13
    } catch (e: SudoPasswordManagerException) {
14
        // Handle/notify user of exception
15
    }
16
}
Copied!
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 function, 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 function, passing 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.
TypeScript
Swift
Kotlin
1
const masterPassword = '[email protected]!'
2
​
3
try {
4
    await client.register(masterPassword)
5
} catch {
6
    // handle any registration errors
7
}
Copied!
1
var client: PasswordManagerClient!
2
​
3
client.register(masterPassword: "Can'tCrackThis") { (result) in
4
    switch result {
5
        case .success:
6
            break
7
        case .failure(let error):
8
            break
9
    }
10
}
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
launch {
4
    try {
5
        withContext(Dispatchers.IO) {
6
            client.register("[email protected]!")
7
        }
8
    } catch (e: SudoPasswordManagerException) {
9
        // Handle/notify user of exception
10
    }
11
}
Copied!
Unlocking the Password Manager
To access the Password Manager, it must first be unlocked by calling the unlock function, passing in the user's master password. This function also accepts the user's secret code, which is only required if the registration status returned by getRegistrationStatus is missingSecretCode.
Note. An error will be returned by unlock if the secret code is not provided to unlock and not present on the user's device.
TypeScript
Swift
 Kotlin
1
const masterPassword = '[email protected]!'
2
​
3
try {
4
    // if the client is already registered:
5
    await client.unlock(masterPassword)
6
​
7
    // otherwise, if the secret code is required:
8
    const secretCode = '012345-6789a-bcdef-01234-56789-abcdef'
9
    await client.unlock(masterPassword, secretCode)
10
} catch {
11
    // handle any unlock errors
12
}
Copied!
1
var client: PasswordManagerClient!
2
​
3
client.unlock(masterPassword: "[email protected]!", secretCode: nil) { (result) in
4
    switch result {
5
        case .success:
6
            break
7
        case .failure(let error):
8
            break
9
    }
10
}
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
launch {
4
    try {
5
        withContext(Dispatchers.IO) {
6
             val secretCode = client.getSecretCode()
7
             client.unlock("[email protected]!", secretCode)
8
        }
9
    } catch (e: SudoPasswordManagerException) {
10
        // Handle/notify user of exception
11
    }
12
}
Copied!
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 function that accesses the Password Manager will not fail due to it being locked.
TypeScript
Swift
Kotlin
1
const isLocked = client.isLocked()
2
if (client.isLocked()) {
3
    // the password manager is locked.
4
    // use the unlock() method before accessing vaults.
5
} else {
6
    // the password manager is unlocked.
7
}
Copied!
1
var client: PasswordManagerClient!
2
​
3
if client.isLocked() {
4
    // the password manager is locked.
5
    // use the unlock() method before accessing vaults.
6
} else {
7
    // the password manager is unlocked.
8
}
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
if (client.isLocked()) {                        
4
     // the password manager is locked.
5
     // use the unlock() method before accessing vaults.
6
} else {
7
     // the password manager is unlocked.
8
}
Copied!
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.
TypeScript
Swift
Kotlin
1
client.lock()
2
// client.isLocked() will now return true.
Copied!
1
var client: PasswordManagerClient!
2
​
3
client.lock()
4
// client.isLocked() will now return true.
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
launch {
4
    try {
5
        withContext(Dispatchers.IO) {
6
            client.lock()
7
        }
8
        // client.isLocked() will now return true.
9
    } catch (e: SudoPasswordManagerException) {
10
        // Handle/notify user of exception
11
    }
12
}
Copied!
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 function. 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 function.
You can retrieve the secret code stored on the user's device using the showSecretCode function. 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.
TypeScript
Swift
 Kotlin
1
try {
2
    // assuming the client is already registered:
3
    const secretCode = await client.showSecretCode()
4
    console.log(secretCode)
5
} catch (error) {
6
    if (error instanceof VaultSecretCodeNotFound) {
7
        // the secret code has not been stored on this device.
8
    }
9
}
Copied!
1
var client: PasswordManagerClient!
2
​
3
let secretCode = client.getSecretCode()
4
// returns an optional String
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
val secretCode = client.getSecretCode()
Copied!
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.
TypeScript
Swift
Kotlin
1
// Default using the included Sudo Platform Template
2
const pdfBuffer = await client.renderRescueKit()
3
​
4
// Optional argument for a custom template.
5
const pdfTemplate = fs.readFileSync('./template.pdf')
6
const pdfBuffer = await client.renderRescueKit({
7
  pdfTemplate: pdfTemplate,
8
})
Copied!
1
var client: PasswordManagerClient!
2
let document: PDFDocument? = client.renderRescueKit()
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
val doc: PdfDocument = client.renderRescueKit(context)
4
// write file to cache directory or wherever you wish
5
val rescueKitFile = File(context.applicationContext.cacheDir, "RescueKit.pdf")
6
try {
7
    doc.writeTo(FileOutputStream(rescueKitFile))
8
} catch (e: SudoPasswordManagerException) {
9
    // handle error
10
}
Copied!
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 function.
TypeScript
Swift
 Kotlin
1
try {
2
    const newPassword = 'new-p4ssword'
3
​
4
    await client.changeMasterPassword(newPassword)
5
} catch (error) {
6
    // handle any password change errors
7
}
Copied!
1
var client: PasswordManagerClient!
2
​
3
guard client.isLocked() == false else { fatalError() }
4
​
5
client.changeMasterPassword(currentPassword: "[email protected]", newPassword: "N3WPassW0rd") { (result) in
6
    switch result {
7
    case .success:
8
        break
9
    case .failure(let error):
10
        break
11
    }
12
}
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
launch {
4
    try {
5
        val currentPassword = "[email protected]!"
6
        val newPassword = "N3WPassW0rd"
7
        withContext(Dispatchers.IO) {
8
             client.changeMasterPassword(currentPassword, newPassword)
9
        }
10
    } catch (e: SudoPasswordManagerException) {
11
        // Handle/notify user of exception
12
    }
13
}
Copied!
Deregistering from the Password Manager
To deregister a user from the Password Manager and delete all created vaults and vault items, use the deregister function.
TypeScript
Swift
 Kotlin
1
try {
2
    await client.deregister()
3
} catch (error) {
4
    // handle failure to deregister
5
}
Copied!
1
var client: PasswordManagerClient!
2
try? client.deregister { (result) in
3
    switch result {
4
    case .success(let deregisteredUserID):
5
        break
6
    case .failure(let error):
7
        break
8
    }
9
}
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
launch {
4
    try {
5
        withContext(Dispatchers.IO) {
6
             client.deregister()
7
        }
8
    } catch (e: SudoPasswordManagerException) {
9
        // Handle/notify user of exception
10
    }
11
}
Copied!
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 function. 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.
TypeScript
Swift
 Kotlin
1
client.reset()
2
/* Begins an asynchronous best-effort attempt to clear local data. */
Copied!
1
var client: PasswordManagerClient!
2
​
3
client.reset()
Copied!
1
// val client: SudoPasswordManagerClient
2
​
3
launch {
4
    try {
5
        withContext(Dispatchers.IO) {
6
             client.reset()
7
        }
8
    } catch (e: SudoPasswordManagerException) {
9
        // Handle/notify user of exception
10
    }
11
}
Copied!
Integrate the Password Manager SDK
Managing Password Vaults
Last modified 4mo ago
Copy link
Contents
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