...
- createProfile: This API creates user's wallet profile and returns info of profile created (ID and any other information needed by client). It returns error if wallet profile is already created or if profile creation fails.
Here are the arguments that can be used to create user profile- username: unique loginname to identity user. This parameter will also be used as db namespace,
- authURIremoteKMS options:
- key server URL: webkms key server URI
- local KMS options:
- passphrase: secret in case of localkms
(Note: in case of localkms a masterkey will be generated and will be encrypted by user's secret)- . VC wallet will create `hkdf` masterlocker(secret lock service) using this passphrase to encrypt master key.
- secret lock service: (for SDK binding only), If client doesn't want to share passphrase then client can provide secret lock service which will be used by VCwallet to encrypt master key.
- getProfile: Takes a username string and returns profile info containing profile ID or any other information needed for client.
...
- updateProfile: Client can change its KMS settings anytime by using update profile. Wallet contents will be preserved, but client may lose its keys depending on KMS setting updates.
For example, client changes its passphrase in case of localkms or secret service.
Open & Close wallet APIs (need naming suggestions):
Since profile KMS requires locking/unlocking features, it is not a good idea to expect user kms secret/token in each wallet api calls due to below reasons.
...
Solution: client has to unlock the wallet before calling any wallet interface APIs and lock the wallet back when he/she is done. Wallet will also auto lock if unused for certain amount of time (token expiry).
This leads to introduction of 2 more APIs given below:
- unlock: accepts user `secret/token` used to create profile, creates kms instance, keeps it in cache (with expiry) and returns a token which can be used for any subsequent operations.
This token will be used by VC wallet to fetch kms instance from cache and also will be used to correlate user profileOpen wallet:- In case of local KMS,
- Supply passphrase or secret lock service to 'Open wallet API' to unlock master lock and initialize aries local KMS instance.
- This KMS instance will be kept in cache till the expiry duration provided by client.
- This token has to be supplied by client while calling each VC wallet APIs. Once token expires cache gets cleared and kms instance will be destroyed, then client has to unlock it again to get new token and initialize kms instance again.
- Calling unlock on already unlocked wallet will return error "Profile already unlocked", if client loses/compromises token then he/she has to lock the wallet to destroy kms instance and has to open wallet again to get new token.
- In case of remote KMS,
- Supply auth token to unlock the wallet which will initialize aries remote KMS instance. Auth token will be part of remotekms instance's header function which will be remembered for all KMS operation till token expires.
- This KMS instance will be kept in cache till the expiry duration provided by client.
- This token has to be supplied by client while calling each VC wallet APIs. Once token expires cache gets cleared and kms instance will be destroyed, then client has to unlock it again to get new token and re-initialize kms instance.
- Calling unlock on already unlocked wallet will return error "Profile already unlocked", if client loses/compromises token then he/she has to lock the wallet to destroy kms instance and has to open wallet again to get new token.
- In case of local KMS,
- Close wallet: Can be called by user to lock the wallet back, recommended during wallet logout. Wallet will be closed by itself when previously issued token expires. Calling close on already closed wallet will not return any error.