(async) changeCredentialsAndReEncrypt(oldContext, newUserName, newPassword, onReEncrypt) → {Promise.<WearContext>}
Returns a context derived from new credentials and calls a specified callback that will perform re-encryption. The function’s logic is meant as a safeguard to avoid bricking user data when credentials change. If app code follows implementation instructions, this function will succeed or fail atomically, leaving user data in an accessible state.
Parameters:
Name | Type | Description |
---|---|---|
oldContext |
WearContext | Context containing key under which data is currently encrypted. oldContext will be closed and be unusable if this function returns successfully. |
newUserName |
string | New user name, which would commonly be the same as previous user name, but doesn’t have to be. |
newPassword |
string | Along with new user name, this comprises the credentials from which a new key will be derived. |
onReEncrypt |
ReEncryptCallback | Callback to app-supplied function which will perform re-encryption of user data. |
Returns:
Promise resolving to new context generated from new credentials if everything was successful.
- Type
- Promise.<WearContext>
close(context)
Prevent any further encryption/decryption with the passed-in context. Useful for preventing attacks based on physical access to the user’s device, e.g. user leaves browser open on an unlocked, unattended laptop. A natural time to call this is whenever a user logs out. If you generated multiple contexts that were stored in separate variables, then call `close()` on each. If the user closes the tab or browser before you can call open(), there is no risk as the context is already cleared from memory.
Parameters:
Name | Type | Description |
---|---|---|
context |
WearContext | From a previous call to open(). |
dangerouslyDeInitialize()
Clears any information used to verify credentials or generate credential keys. Read the warning below before calling this. WARNING: After this call, you won’t be able to generate the same key from credentials. If you’ve got user data encrypted with it, that data will be bricked.
(async) decryptBytes(context, encryptedData) → {Promise.<Uint8Array>}
Decrypts string to a byte array.
Parameters:
Name | Type | Description |
---|---|---|
context |
WearContext | From a previous call to open(). The credentials that generated the context must match credentials provided earlier in session where encryptedData was encrypted. |
encryptedData |
string | Must have been generated with a previous call to `encryptBytes()`. |
Returns:
Promise resolving to Unencrypted data.
- Type
- Promise.<Uint8Array>
(async) decryptObject(context, encryptedData, reviver) → {Promise.<object>}
Decrypts ciphertext string to an object. If the object is not entirely representable in JSON, you’ll need to pass a reviver function to handle deserialization that matches a replacer function previously passed to `encryptObject()` for the same data. To understand if your object is JSON-representable, call `JSON.parse(JSON.stringify(yourObject))` and see if it returns the same `yourObject` value. WEaR adds support for (de)serializing the following primitive values: null, Infinity, -Infinity, and NaN.
Parameters:
Name | Type | Description |
---|---|---|
context |
WearContext | From a previous call to open(). The credentials that generated the context must match credentials provided earlier in session where encryptedData was encrypted. |
encryptedData |
string | Must have been generated with a previous call to `encryptObject()`. |
reviver |
function | Optional function to deserialize values correctly. See JSON.parse() documentation |
Returns:
Promise resolving to Unencrypted data.
- Type
- Promise.<object>
(async) encryptBytes(context, bytes) → {Promise.<string>}
Encrypts byte array to a string that you can use for writing to persistent storage.
Parameters:
Name | Type | Description |
---|---|---|
context |
WearContext | From a previous call to open(). |
bytes |
Uint8Array | Value to encrypt. |
Returns:
Promise resolving to base64-encoded string of encrypted data.
- Type
- Promise.<string>
(async) encryptObject(context, object, replacer) → {Promise.<string>}
Encrypts object to a ciphertext string that you can use for writing to persistent storage. If the object is not entirely representable in JSON, you’ll need to pass a replacer function to handle serialization, and pass a reviver function later to `decryptObject()` to symmetrically perform deserialization. To understand if your object is JSON-representable, call `JSON.parse(JSON.stringify(yourObject))` and see if it returns the same `yourObject` value. WEaR adds support for (de)serializing the following primitive values: null, Infinity, -Infinity, and NaN.
Parameters:
Name | Type | Description |
---|---|---|
context |
WearContext | From a previous call to open(). |
object |
object | Value to encrypt. |
replacer |
function | Optional function to serialize values correctly. See JSON.stringify() documentation |
Returns:
Promise resolving to ciphertext string.
- Type
- Promise.<string>
isInitialized() → {boolean}
Checks to see if a context was previously opened via open(). This can be useful to present appropriate UI in the app for either request existing credentials (e.g. “log in”) or accept new credentials (e.g. “create account”).
Returns:
True if context was previously opened, or false if not.
- Type
- boolean
(async) open(userName, password) → {Promise.<WearContext>}
Returns a context that is needed for passing to other APIs or null if passed credentials are incorrect. A natural time to call this is right after user has entered credentials and you’ve successfully performed any authentication that your app requires. open() is idempotent and you can call it multiple times.
Parameters:
Name | Type | Description |
---|---|---|
userName |
string | Uniquely identifies user. |
password |
string | Password for user. |
Returns:
Promise resolving to context that can be passed to other APIs. Treat this opaquely. DO NOT store in any place but memory.
- Type
- Promise.<WearContext>