WIP: Character migrate/backup/import and Web API

[fartwhif]

Authentication:

The Web API uses basic access authentication and to access some of the data resources requires a valid account username and password for the underlying ACEmulator server.

If using CURL then the -k option is needed since certificates are self-signed. For authenticated resources CURL needs -u myusername:mypassword.

If a resource is marked Anonymous then authorization isn't needed. If you attempt to access a resource that isn't marked Anonymous without supplying valid credentials then you will get a 401 Unauthorized response.

Authenticated requests assume the accesslevel of the account authenticated as a series of claims.

If a resource is marked Requires: [Admin], that means unless your account includes the Admin claim then you won't be able to access the resource and you will get a 403 Forbidden response.

If a resource is marked RequiresAny: [Admin,Advocate,Developer,Envoy,Player,Sentinel] then unless your authenticated account claims at least one of the required claims you won't be able to access the resource and you will get a 403 Forbidden response.

Web API

documentation

The Web API server listens at the base ACE port + 2, TCP, TLS, HTTPS, JSON, REST, depends on CryptoManager within ACE.Server project that Generates and saves self-signed certificates when it can't find them. One for WebApi, and one for signing character transfers, in C:\Users\<user>\AppData\Roaming\ACEmulator_<WorldName>\Certificates on Windows or /home/<user>/.config/ACEmulator_<WorldName>/Certificates on Linux. Place or replace webapi.pfx with a "valid" web server certificate if needed. Self-Hosting using NancyFX/OWIN/Kestrel in its own project that depends on and wraps around ACE.Server. WebSockets is a future possibility. To run ACE with web API capability start the batch file: \Source\ACE.Server.WebApi\bin\x64\Debug\netcoreapp2.1\start_server+webapi.bat

To enable and run ACEmulator with WebAPI:

1. Change the applicable setting to true in the configuration file, it should look like this after:

    "WebApi": {
        "Enabled": true
    },

2. Build the solution.
3. Run the file start_server+webapi.bat in the output folder, which should be located somewhere like: \Source\ACE.WebApiServer\bin\x64\Debug\netcoreapp2.1

A postman collection is included in the source: WebApi.postman_collection.json - just import that into postman for a working test suite.

Warning

If the world name in the server configuration is changed then the current transfers and certificate are lost unless the files are moved to the new location. To mitigate this move or copy the contents of C:\Users\<user>\AppData\Roaming\ACEmulator_<OldWorldName>\ to C:\Users\<user>\AppData\Roaming\ACEmulator_<NewWorldName>\ replacing <user> with the applicable username, and <OldWorldName> and <NewWorldName> with applicable names. For linux the path will usually be: /home/<user>/.config/ACEmulator_<WorldName>/. If your world name contains special characters then the folder names will have them stripped out, allowed world name to folder name characters are: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.

Migrations:

1. Via Web API, a request is made to migrate a character to another server.
2. Character snapshot is packaged and character is placed in a "frozen" state.
3. Requester makes an API call to get the list of characters, of which is the migrating character in frozen state.

• At any time before the next step is initiated, or if the target server rejects the source server, an API request can be made to the source server to unfreeze the character and cancel the migration.

4. Requester makes a request to the target server (the character's new home).
5. Target server makes sure source server is trusted before downloading and rejects the request if it doesn't.
6. Target server downloads packaged snapshot from source server.
7. Source server permanently deletes character upon package download completion.
8. Target server performs cryptographic verification of the snapshot, and rejects it if it's been forged.
9. Target server adds the character to the requester's account.

Note: Allowing migrations from itself enables cross account transfers and character renaming.

Backups:

Via Web API, a request is made to backup a character.
Character snapshot is packaged and returned in the response to the requester.

Imports:

with imports enabled the exploitation flood gates are essentially open

requester makes a request to the target server API including in the request the snapshot package encoded in base64 and the new character name.
target server adds the character to the requester's account.

Recommended settings for flawless contract groups:

allow backup: yes

allow migrate: yes

allow import: no

Limitations:

• ACE specific data constructs such as character options are not exported/imported. This is to keep it as compatible as possible with LSD.

Disclaimer

The migration feature requires the assumption that all server operators involved are non defectors. A defector is someone in the trust group who does malicious or negligent action of any kind. Providing a system that works for flawless trust groups is easy, but as soon as an attempt is made to eliminate the human element and commission the possibility of defectors the entire system breaks. Manual approval process and/or central "antivirus" server may be something that someone might want to come up with in the future, but that's NOT what this is meant for. As a server operator, DO NOT blame anyone but yourself upon defection(s) when using this system. NOBODY BUT YOURSELF IS LIABLE

[Mag-nus]

Lots of great stuff. Left some notes where I think changes should be made.

I think the config.json -> config.js should be in a separate PR.

Also, if the start_server.bat changes are to be committed, they too should be in a separate PR. These are both very big changes that should be isolated.

[Mag-nus]

Character Backup/Export/Import:

[Definitions]

Player - Person that exists in real life
Character - In-game avatar created/controlled by the player
Source - Server that the character in question resides on at the start of the action
Target - Server or location that the caracter in question resides on at the end of the action

Backup - Action involving a user storing a local copy of a character
Transfer - Action involving a user migrating a character from a source to a target in which after the action, the character is no longer available on the source.
Copy - Action involving a user copying a character from a source to a target in which after the action, the character is available on both locations.

[Objectives]

• Allow players to backup their characters
• Allow server operators to maintain a trust network to transfer characters safely, and without external manipulation
• Allow players (developers, sandbox, etc..) to copy their characters to an untrusted target.

[Facts]

A server maintains a private RSA key and distributes their public RSA key.

• These keys can be provided by the server owner via the config file
• If the user is unable to provide their own keys, ACE can generate them automatically
• The private key is used to sign character packages to provide proof of origin
• The private key should not be shared, and should be kept secure
• The public key should be available via the api and is used to verify authenticity
• A server operator can use the same RSA key pairs for multiple servers in their control

A server can maintain separate options for import vs export.

• In most cases, import will be more restrited than export.

[Character Snapshot Format]

• Should be the same format no matter what the export scenario
• Includes the entire player biota as it exists in the database
• TODO: Describe serilization process.
• Character records are not included (these describe UI settings, etc..)
• Includes a copy of the public key
• TODO: Describe signature process
• Entire payload should be compressed in a zip named with the following format: YYYY-MM-DD HH:MM:SS [Server Name] - [Character Name].zip
• Compressed .zip payload should be able to be opened using windows explorer.

[Requirements]

• Character must be in logged off state on source server, and must be owned by player

[Backup]

• Allows a player to backup a character onto their local storage

Configured by:

• bool AllowCharacterBackup

Process:

• User opens up a web browser to the source api server and nagivates to backup character
• The "Character Snapshot" is downloaded
• This can be consumed from a web browser, plugin, or application

[Export/Import]

• Allows a player to copy a character onto a target server
• Allows a player to transfer a character from the source server to the target server
• Preventing exploit is managed by configuration using trusted servers

Configured by:

• List TrustedServers
• bool AllowUntrustExport
• bool AllowUntrustImport

Process inside trust:

1. Via Web API, player makes a request on the source server to start a character transfer
   1a. A unique token is generated for this request
   1b. A character transfer request record is created
   1c. Character is placed into a "frozen" state
   1d. Character snapshot is packaged
   1e. Unique token is supplied as a result
2. Via Web API, player makes a request to the target server to complete the character transfer

• Player must include source server: address, user name, user password, unique token
• Player may provide new character name. If none provided, existing character name is used as default
  2a. Character slot count and name collision checks are run. On failure, request is rejected (with error message)
  2b. If source server is not listed as trust, request is rejected (with error message)
  2c. Target queries source and downloads packaged snapshot
  2c.1. Source server verifies target is in trusted list
  2d. Cryptographic verification of the snapshot is performed. On failure, request is rejected (with error message)
  2e. Target server adds the character to the players account in a (locked pending deletion) state
  == AT ANY POINT BEFORE NOW, CHARACTER CAN STILL BE UNLOCKED ON SOURCE ==
  2f. Target queries source server to delete character identified by token.
  2f.1. Source server verifies target is in trusted list
  2f.2. Source server permanently deletes character and responds with result
  2g. If deletion success, character is unlocked

Process outside trust (untrust):

1. Via Web API, player makes a request on the source server to start a character copy
   1a. A unique token is generated for this request
   1b. A character transfer request record is created
   1c.
   1d. Character snapshot is packaged
   1e. Unique token is supplied as a result
2. Via Web API, player makes a request to the target server to complete the character copy

• Player must include source server: address, user name, user password, unique token
• Player may provide new character name. If none provided, existing character name is used as default
  2a. Character slot count and name collision checks are run. On failure, request is rejected (with error message)
  2b.
  2c. Target queries source and downloads packaged snapshot
  2d. Cryptographic verification of the snapshot is performed. On failure, request is rejected (with error message)
  2e. Target server adds the character to the players account
  2f.
  2g.

Difference between trust and untrust:
Untrust removes 1c
Untrust removes 2b
Untrust changes 2c
Untrust changes 2e
Untrust removes 2f
Untrust removes 2g

[fartwhif]

TO-DO:

• add friends list status getter
• add server pop limit to server info

[fartwhif]

Re-cloning ACE because I broke my old one. Copied all of these comments and backed up the branches I want to restore. Closing this. I will open a new one for webapi after the initial commit.