Skip to content

Request formats

Jump to bottom
Marco Stellin edited this page Jan 4, 2017 · 87 revisions

Requests

REGISTER GROUP

This won't be done for the course, but including server addresses lets group servers change addresses without notifying the users and also provides the possibility for easy to use web clients in the future (although a web client brings with it the need to trust the main server not to send malicious code to the browser)

Group server owner C0 registers the group server and proxy with the Main server.

Groupt server -> Main server

POST: /register-group

{ "group_name": "MyGroup",
"group_key": "C0", # The signing public key of the owner "group_signature": "{MyGroup, C0}!C0" }

Notes:

> **Response: 201 Created**
>

{ "group_uuid": "G1", "main_signature": "{G1, MyGroup, C0}!M"} # proves the main server received the correct group information. }

Notes: A way to securely update server addresses should be possible but it's not in the scope of this project


### Possible errors
- 400 Bad request: Wrong format
- 401 Unauthorized: Signature verification failed


## USER INVITE
Users C1 invites user C2 to G1 (group 1).
 
> **C1 -> Group server**
>
> **POST: /invite-user**
>```
{
    "group_uuid": "G1",  # not necessary but makes group servers that serve multiple groups possible.
    "user": "C1",
    "invitee": "C2",
    "invite_email": "c2@y.com",
    "user_signature": "{G1, C1, C2, c2@y.com}!C1"
}
# Notes:

Response: 202 Accepted

{
    "group_server_signature": {G1, C1, C2, c2@y.com}!G
}
# Notes: An invitation e-mail with a secret code is sent to c2@y.com

Possible errors

  • 400 Bad request: Wrong format
  • 401 Unauthorized: Signature verification failed
  • 403 Forbidden: User isn't in the group, can't invite
  • 409 Conflict: User C2 already exists in G1

GET GROUP INFO

THIS REQUEST PROBABLY WON'T BE IMPLEMENTED FOR THE COURSE, SINCE IT'S NOT STRICTLY NECESSARY.

It lets group servers change addresses without notifying the users and also provides the possibility for easy to use web clients in the future (although a web client brings with it the need to trust the main server not to send malicious code to the browser)

C2 goes to the main server to get the relevant information about the group.

Group server -> Main server

POST: /get-group-info

{ "group_name": "MyGroup",
"owner": "C0", # The signing public key of the owner "group_address": "mygroup.com", "proxy_address": "mygroup.com/proxy", "owner_signature": "{MyGroup, C0, group_address, proxy_address,}!C0" }

Notes:

> **Response: 201 Created**
>

{ "group_uuid": "G1", "group_name": "MyGroup",
"owner": "C0", "group_address": "mygroup.com", "proxy_address": "mygroup.com/proxy", "main_signature": "{G1, MyGroup, C0, group_address, proxy_address,}!M"} # proves the main server received the correct group information. }

Notes: A way to securely update server addresses should be possible but it's not in the scope of this project


### Possible errors
- 400 Bad request: Wrong format
- 401 Unauthorized: Signature verification failed


## GROUP SERVER JOIN
User C2 has a secret code for an invite to G1 from C1.

> **C2 -> Group server**
>
> **POST: /join-group**
>```
{ 
    "group_uuid": "G1", # not necessary but makes group servers that serve multiple groups possible.
    "user": "C2",
    "secret_code": "1234", 
    "user_signature": "{G1, C2, 1234}!C2" # is signing the secret code useful?
}
# Notes:

Response: 201 Created

{
    "inviter": "C1",
    "user": "C2",
    "user_email": "c2@y.com",
    "inviter_signature": "{G1, C1, C2, c2@y.com}!C1"
    "group_server_signature": {inviter_sig}!G # proves that the user existed on the group server.
}
# Notes: C2 can prove both that C1 invited him and that G accepted him into the group.

Possible errors

  • 400 Bad request: Wrong format or one or more C1 in G1 or C2 in G1 do not exist
  • 401 Unauthorized: Signature verification failed
  • 403 Forbidden: The secret code is incorrect
  • 409 Conflict: C2 already exists in G1

MAIN SERVER JOIN

Before accepting the registration of the user in the group server, the group server contact the main server to confirm that the user is registered successfully. Upon reception of the response from the main server, the user is registered.

Group Server -> Main server

POST: /join-group

{ "group_uuid": "G1", "user": "C2", "group_signature": "{G1, C2}!G" # A signature from the group server to allow the user to join on the main server }

Notes:

> **Response: 201 Created**
>

{ "group_uuid": "G1", "user": "C2" "main_signature": "{G1, C2}!M" }


### Possible errors
- 400 Bad request: Wrong format or one or more C1 in G1 or C2 in G1 do not exist
- 401 Unauthorized: Signature verification failed
- 409 Conflict: C2 already exists in G1 


## CONFIRM JOIN
User C2 received a correct response from the main server after a JOIN request and wants to confirm he is sucessfuly registerd in both the group server and the main server.

> **C2 -> Group server**
>
> **POST: /confirm-join**
>```
{ 
    "group_uuid": "G1",
    "user": "C2",
    "user_signature": "{G1, C2, group_server_signature}!C2"
}
# Notes:

Response: 200 OK

{
    "group_uuid": "G1",
    "user": "C2",
}
# Notes: Not sure if it's worth it for the group server to sign that he accepted the confirmation

Possible errors

  • 400 Bad request: Wrong format or one or more C1 in G1 or C2 in G1 do not exist
  • 401 Unauthorized: Signature verification failed
  • 409 Conflict: C2 already confirmed

ISSUE UOMe

User C1 issues UOMe to C2 in group G1.

C1 -> Proxy server -> Main server

POST: /issue-uome

{ "group_uuid": "G1", # because the main server handles multiple different groups "user": "C1", # users are identified by their public signing keys "borrower": "C2", "value": 1000, # uome values are in cents and must be positive "description": "reason", # a textual description of why the UOMe was issued "user_signature": "{G1, C1}!C1" # authentication signature }

Notes: the salt was removed since it serves no purpose in this request.

> **Response: 201 Created**

{ "uome_uuid": "#1234", "signature": "{#1234, G1, C1, C2, 1000, reason}!M" }

Notes: the UOMe data and signature is sent so C1 can prove that uome_uuid has those values


### Possible errors
- 400 Bad request: Wrong format or one or more of G1, C1 in G1 or C2 in G1 do not exist
- 401 Unauthorized: Signature verification failed
- 403 Forbidden: User is not permitted to do this

## CONFIRM UOMe
User C1 confirms issued UOMe to C2 in group G1.

> **C1 -> Proxy server -> Main server**
>
> **POST: /confirm-uome**
>```
{
    "group_uuid": "G1",
    "user": "C1",
    "uome_uuid": "#1234",
    "user_signature": "{G1, C1, C2, 1000, reason, #1234}!C1" 
}
# Notes: the salt was removed since it serves no purpose in this request.

Response: 200 OK

{
    "group_uuid": "G1",
    "user": "C1"
}

Possible errors

  • 400 Bad request: Wrong format
  • 401 Unauthorized: Signature verification failed
  • 404 Not Found: there is no pending UOMe with the given ID
  • 409 Conflict: UOMe ID has already been confirmed

CANCEL UOMe

User C1 cancels UOMe #1234 for group G1 with C2.

C1 -> Proxy server -> Main server

POST: /cancel-uome

{ "group_uuid": "G1", # because the main server handles multiple different groups "user": "C1", # users are identified by their public signing keys "uome_uuid": "#1234", "signature": "{G1, C1, #1234}!C1" }

Notes:

> **Response: 200 OK**

{ "signature": "{G1, C1, #1234}!M" }

Notes: the UOMe data and signature is sent so C1 can prove that the uome with that uuid and data has been deleted


### Possible errors
- 400 Bad request: Wrong format or one or more of G1, C1 in G1 or C2 in G1 do not exist
- 401 Unauthorized: Signature verification failed
- 403 Forbidden: User is not permitted to do this
- 404 Not Found: The UOMe uuid does not exist.  

## PENDING UOMes
User C2 checks his pending UOMe's for group G1.

> **C2 -> Proxy server -> Main server**
>
> **POST: /get-pending-uomes**
>```
{
    "group_uuid": "G1",       # because the main server handles multiple different groups
    "user": "C2",             # users are identified by their public signing keys
    "signature": "{G1, C2}!C2" 
}
# Notes:

Response: 200 OK

{
    "issued_by_user": [
        [G1, C2, C3, value, description, uome_signature, uome_uuid],  # [group_uuid, lender/issuer, borrower, ...]
        ...
    ],
    "waiting_for_user": [
        [G1, C1, C2, value, description, uome_signature, uome_uuid],  # [group_uuid, lender/issuer, borrower, ...]
        ...
    ],     
    "main_signature": "{G1, C2, issued_by_user, waiting_for_user}!M"
}
# Notes: The signatures should sign the json string versions of the lists. The lists themselves should not be JSON encoded since the whole request already will be.

Possible errors

  • 400 Bad request: Wrong format or one or more of G1, C1 in G1 or C2 in G1 do not exist
  • 401 Unauthorized: Signature verification failed

ACCEPT UOMe

User C2 accepts UOMe #1234 issued by C1

C2 -> Proxy server -> Main server

POST: /accept-uome

{ "group_uuid": "G1", "user": "C2", "uome_uuid": "#1234", "user_signature": "{G1, C1, C2, 1000, reason, #1234}!C2" }

> **Response: 200 OK**
>

{ "signature": "{G1, C2, #1234}!M" }

### Possible errors
- 400 Bad request: Wrong format or one or more of G1, C1 in G1 or C2 do not exist
- 401 Unauthorized: Signature verification failed
- 403 Forbidden: User is not permitted to do this

## CHECK TOTALS
User C1 checks his simplified debts for group G1.
> **C1 -> Proxy server -> Main server**
>
> **POST: /get-totals**
>```
{
    "group_uuid": "G1",
    "user": "C1",
    "user_signature": "{G1, C1, "check-totals"}!C1"
}

Response: 200 OK

{
    "user_balance": 100,
    "suggested_transactions": {"C2": 50, ...},
    "main_signature": "{G1, C1, 100, suggested_transactions}!M"
}

Possible errors

  • 400 Bad request: Wrong format or one or more of G1 or C1 in G1 do not exist
  • 401 Unauthorized: Signature verification failed
  • 403 Forbidden: User is not permitted to do this

GET EMAIL-KEY MAP

User C1 asks the group server for the email-key mapping of its own group (G1).

C1 -> Group server

POST: /email-key-map

{ "group_uuid": "G1", "user": "C1", "request_type": "email-key-map", "signature": "{C1, "email-key-map"}!C1" }

> **Response: 200 OK**
>

{ "C2": "C.y@m.com", ... }

### Possible errors
- 400 Bad request: Wrong format or one or more of G1 or C1 in G1 do not exist
- 401 Unauthorized: Signature verification failed
- 403 Forbidden: User is not permitted to do this
  1. Problem and Solution Concept
  2. Introduction
  3. Usage Scenario
  4. What are groups?
  5. Architecture
  6. Goals and Principals
  7. Keeping Information Private
  8. User Authentication
  9. Non-Repudiation
  10. Protocol
  11. User Registration
  12. Group Server Registration
  13. Managing UOMes
  14. Other Requests
  15. Implementation
  16. Web Technologies
  17. SQL Injection
  18. Security Technologies
  19. TLS/HTTPS
  20. RSA
  21. Client application
  22. Request Formats
  23. Main/Group Server Setup
  24. Proxy Server Setup
Clone this wiki locally