Skip to content

Latest commit

 

History

History
91 lines (68 loc) · 4.63 KB

user.md

File metadata and controls

91 lines (68 loc) · 4.63 KB

User registration

Create a new user in the Enceeper service. The following constrains are in place for the provided JSON:

  • the email key is required and must be a valid email address
  • the auth.srp6a.salt key is required
  • the auth.srp6a.verifier key is required
  • all the auth.srp6a.xxx keys are reserved and must not be used
  • all the auth.enceeper.xxx keys are reserved and must not be used
  • the auth.keys.pub key is required and must contain the public key of the user to facilitate key sharing
  • You can place anything inside the auth object and it will be stored by the Enceeper service
  • The overall size of the auth object must not exceed the 12Kbytes limit
Type Value
URL /user
Method POST
Input {
 "email": "[email protected]",
 "auth": {
  "srp6a": {
   "salt": "hex salt",
   "verifier": "hex verifier"
  },
  ...
  "keys": {
   "pub": "the public key of the user used in key sharing",
   ...
  },
  ...
 }
}
Output -

The Enceeper service is utilizing the SRP6a protocol for user registration and authentication. In the future we may support additional protocols (i.e. SPAKE2).

Initiate auth procedure

The client will provide the user email and the Enceeper service will bootstrap the SRP6a protocol. The ref must be used in the Authenticate user API call below, in order to restore the information created in this procedure.

Type Value
URL /user/challenge
Method POST
Input {
 "email": "[email protected]"
}
Output {
 "srp6a": {
  "B": "hex B value",
  "salt": "hex salt",
  "ref": "string ref"
 }
}

Authenticate user

This API call verifies the proof of the SRP6a protocol with the provided information:

  • The ref taken from the above procedure
  • The A and M1 SRP6a protocol values

and if sucessfull it will provide back the following details:

  • The server proof srp6a.M2 to be checked by the client
  • The enceeper.authToken to be used for susequent API calls in the X-Enceeper-Auth HTTP header
  • The enceeper.plan object outlining the plan details of the user account
  • The auth details provided to the Enceeper service during registration

In the current implementation of the Enceeper App and the Enceeper JS library the following additional JSON keys are utilized inside the auth object:

  • The scrypt.salt contains the salt for the scrypt algorithm
  • The keys.kek contains the Key Encryption Key (itself is encrypted)
  • The keys.pub contains the public key of the user for key sharing (plaintext)
  • The keys.prv contains the private key of the user for key sharing (encrypted)
Type Value
URL /user/login
Method POST
Input {
 "srp6a": {
  "A": "hex A value",
  "M1": "client proof",
  "ref": "string ref"
 }
}
Output {
 "srp6a": {
  "M2": "server proof"
 },
 "enceeper": {
  "authToken": "the auth token"
  "plan": { the plan details }
 },
 ...
}

Edit user

Update user details. For the auth object the same constrains are in place as described above in the User registration section.

Type Value
URL /user
Method PUT
Input {
 "auth": {
  "srp6a": {
   "salt": "hex salt",
   "verifier": "hex verifier"
  },
  ...
  "keys": {
   "pub": "the public key of the user used in key sharing",
   ...
  },
  ...
 }
}
Output -

Retrieve web auth token

The server must never receive your password. So in order to authenticate you to Enceeper via a web browser this special API call will create a unique One Time Password (OTP) for you to use and access your plan and billing details.

Type Value
URL /user/webauth
Method GET
Input -
Output {
 "token": "the web auth token"
}

Delete user

Type Value
URL /user
Method DELETE
Input -
Output -