3. Design Requirements¶

3.1. Usernames and Passwords¶

1. Usernames

   1. The client SHOULD assume that each user has a unique username.

   2. Usernames are case-sensitive: Bob and bob are different users.

   3. Usernames can be any length greater than zero (they CANNOT be empty).

2. Passwords

   1. The client MUST NOT assume each user has a unique password. Like the real world, users may happen to choose the same password.

   2. The client MAY assume each user’s password generally is a good source of entropy. However, the attackers possess a precomputed lookup table containing hashes of common passwords downloaded from the internet.

3.2. User Sessions¶

1. The client application MUST allow many different users to use the application at the same time. For example, Bob and Alice can each run the client application on their own devices at the same time.

2. The client MUST support a single user having multiple active sessions at the same time. All file changes MUST be reflected in all current user sessions immediately (i.e. without terminating the current session and re-authenticating).

   For example:

   • User bob runs the client application on his laptop and calls GetUser() to create session bob_laptop.

   • User bob runs the client application on his tablet and calls GetUser() to create session bob_tablet.

   • Using the bob_laptop session, bob stores a file file1.txt. Session bob_tablet must be able to download file1.txt.

   • Using the bob_laptop session, bob appends to file1.txt. Session bob_tablet must be able to download the updated version.

   • Using the bob_laptop session, bob accepts an invitation to access a file and calls the file file2.txt in his personal namespace. Session bob_tablet must be able to load the corresponding file file2.txt.

3. The client DOES NOT need to support concurrency. Globally, across all users and user-sessions, all operations in the client application will be done serially.

3.3. Cryptography and keys¶

1. Each public key SHOULD be used for a single purpose, which means that each user is likely to have more than one public key.

2. A single user MAY have multiple entries in Keystore. However, the number of keys per user MUST be a small constant; it MUST NOT depend on the number of files stored or length of any file, how many users a file has been shared with, or the number of users already in the system.

3. The following SHOULD be avoided because they are dangerous design patterns that often lead to subtle vulnerabilities. We test for them and treat any instance of them as a breach of confidentiality/integrity.

   1. reusing the same key for multiple purposes (e.g. encryption, authentication, key- derivation, etc); and

   2. authenticate-then-encrypt; and

   3. decrypt-then-verify.

3.4. No Persistent Local State¶

1. The client MUST NOT save any data to the local file system. If the client is restarted, it must be able to pick up where it left off given only a username and password. Any data requiring persistent storage MUST be stored in either Keystore or Datastore.

3.5. Files¶

Any breach of IND-CPA security constitutes loss of confidentiality.

1. The client MUST ensure confidentiality and integrity of file contents.

2. The client MUST ensure the integrity of filenames.

3. The client MUST prevent adversaries from learning filenames and the length of filenames. The client MAY use and store filenames in a deterministic manner.

4. The client MUST prevent the revoked user adversary from learning anything about future writes or appends to the file after their access has been revoked.

5. The client MAY leak any information except filenames, lengths of filenames, and file contents. For example, the client design MAY leak the size of file contents or the number of files associated with a user.

6. Filenames MAY be any length, including zero (empty string).

7. The client MUST NOT assume that filenames are globally unique.

   For example, user bob can have a file named foo.txt and user alice can have a file named foo.txt. There is a single instance of the Datastore server that is used by all users, but the client application MUST keep each user’s file namespace independent from one another.

3.6. Sharing and Revoking¶

1. The client MUST enforce authorization for all files. The only users who are authorized to access a file using the client include: (1) the owner of the file; and (2) users who have accepted an invitation to access the file and that access has not been revoked.

2. The client MUST allow any user who is authorized to access the file to take the following actions on the file:

   • read the file contents;

   • overwrite the file contents;

   • append additional content to the file;

   • share the file with other users.

   For example, all of the users listed in Figure 1 are authorized to take the listed actions on the file.

3. Changes to the contents of a file MUST be available to all users who are authorized to access the file. In other words, changes to the contents of a file MUST NOT change who the file is shared with.

4. The client MUST enforce that there is only a single copy of a file. Sharing the file MAY NOT create a copy of the file.

5. The client MUST ensure the confidentiality and integrity of the secure file share invitations created by CreateInvitation().

6. The client MAY assume that CreateInvitation() will never be called on recipients who are already authorized to access the file.

   Any sharing behavior that does not result in a well-formed tree structure is undefined behavior and will not be tested. In a well-formed tree structure, each node has a single parent and there are no cycles.

   For example, in Figure 1, Nilufar’s attempts to share with Marco or Alice in steps 5 and 6 would be undefined behavior, since both users are already authorized to access the file. Neither of these share attempts would result in a well-formed tree and are thus undefined behavior.

7. The client MUST enforce that the file owner is able to revoke access from users who they directly shared the file with.

   Any other revocation (i.e. owners revoking users who they did not directly share with, or revocations by non-owners) is undefined behavior and will not be tested.

   For example, in Figure 1, Alice is the only user who MUST be able to revoke access, and she MUST be able to revoke access from Bob and Nilufar. If any user other than Alice attempts to revoke access, or Alice attempts to revoke access from any user other than Bob or Nilufar, this is undefined behavior and will not be tested.

8. The client MUST enforce that when the owner revokes a user’s access, any other users with whom the revoked user previously shared the file also lose access.

   For example, in Figure 1, if Alice revokes access from Bob, then all of the following users MUST lose access: Bob, Olga, and Marco. As the file owner, Alice always maintains access. Nilufar maintains access because Bob did not grant Nilufar access to the file (Alice did).

9. The client MUST prevent any revoked user from using the client API to take any action on the file from which their access was revoked. However, recall from Threat Model that a revoked user may become malicious and use the Datastore API directly.

10. The client MUST allow the access to be revoked from another user even if the other user does not have an active user session created by GetUser() (i.e. the user is currently offline).

11. Re-sharing a file with a revoked user is undefined behavior and will not be tested.

3.7. Efficiency¶

1. The client MUST allow users to efficiently append new content to previously stored files.

   We measure efficiency in terms of the bandwidth used by the AppendToFile() operation (the total size of the data uploaded and downloaded via calls to DatastoreGet() and DatastoreSet()).

   The bandwidth of the AppendToFile() operation MUST scale linearly with only the size of data being appended and the number of users the file is shared with, and nothing else. Logarithmic and constant scaling in other terms is fine.

   For example, appending 100 B to a 10 TB file should not use 10 TB of bandwidth. The 1,000th and 10,000th append operations to the same file should not use significantly more bandwidth than the 1st append operation. This is not an exhaustive list of restrictions.

2. AppendToFile() is the only function that has an explicit requirement for efficiency. However, the client MUST implement other functions such that they do not time out the autograder (e.g. they cannot be grossly inefficient).

   You can submit to Gradescope as often as you like to verify whether your tests finish within the allotted time (usually about ~10 minutes max).

3.8. Golang¶

1. The client application code MUST NOT use global variables (except for basic constants).

2. Your Go functions MUST return an error if malicious action prevents them from functioning properly. Do not panic, do not segfault; return an error.

3. Return nil as the error if and only if an operation succeeds. Return a value other than nil as the error if and only if an operation fails.