{"id":19017353,"url":"https://github.com/mervyn-mccreight/coinflip","last_synced_at":"2026-06-21T15:32:01.857Z","repository":{"id":87130306,"uuid":"46985770","full_name":"mervyn-mccreight/coinflip","owner":"mervyn-mccreight","description":"Implement a non-server dependent coin flipper client as part of a IT-Security project in university.","archived":false,"fork":false,"pushed_at":"2018-11-18T03:48:31.000Z","size":3538,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-21T17:50:00.837Z","etag":null,"topics":["coinflip","game-of-chances","security","sra"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mervyn-mccreight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-11-27T14:58:41.000Z","updated_at":"2018-11-18T03:49:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"58357c61-4bf8-4537-a4f1-d63c4f4e1aa5","html_url":"https://github.com/mervyn-mccreight/coinflip","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/mervyn-mccreight/coinflip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mervyn-mccreight%2Fcoinflip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mervyn-mccreight%2Fcoinflip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mervyn-mccreight%2Fcoinflip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mervyn-mccreight%2Fcoinflip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mervyn-mccreight","download_url":"https://codeload.github.com/mervyn-mccreight/coinflip/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mervyn-mccreight%2Fcoinflip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34616509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coinflip","game-of-chances","security","sra"],"created_at":"2024-11-08T19:46:43.113Z","updated_at":"2026-06-21T15:32:01.839Z","avatar_url":"https://github.com/mervyn-mccreight.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# coinflip\n\n## Summary\nImplement a non-server dependent coin flipper client as part of a IT-security project in university.\nThis program follows a [protocol](#protocol) developed during the IT-security project.\nThis projects provides an executable JAR-File to either run the initial-sending (client) or initial-retrieving part of the coinflip-protocol exchange.\n\n## Background\nThis program has been developed during an IT-security project in university. The project was lead by [Prof. Dr. Gerd Beuster](https://www.researchgate.net/profile/Gerd_Beuster).\n\n### Project goal\nThe goal of the project was to develop a protocol for online games of chances. Most of the current protocols for such games needs the player to trust the server.\nDuring the project we developed a protocol, where the clients could play a game of chances against each others without the need to trust a server for the evaluation.\nTo proof the concept of the protocol, we took the simplest game of changes - a coinflip - and developed a client using our protocol to play coinflips against each other.\n\n### Protocol\n#### Commutative public-key algorithm\nThe protocol we developed needs a _commutative_ public-key algorithm to work. A public-key algorithm is commutative, if the following equation holds.  \n\n![Commutative public-key algorithm](https://latex.codecogs.com/gif.latex?%5Cdpi%7B100%7D%20%5Clarge%20D_%7BK1%7D%28E_%7BK2%7D%28E_%7BK1%7D%28M%29%29%29%20%3D%20E_%7BK2%7D%28M%29%5C%5C%5C%5C%20where%5C%20D_K%5C%20describes%5C%20an%5C%20decryption%5C%20with%5C%20key%5C%20K%5C%5C%20and%5C%20E_K%5C%20describes%5C%20an%5C%20encryption%5C%20with%5C%20key%5C%20K%5C%5C%20and%5C%20M%5C%20describes%5C%20an%5C%20arbitrary%5C%20message.)\n\nwhich basically means, that the following is possible:\n1. Encrypt M with K1\n2. Encrypt the result with K2\n3. Decrypting the result with K1 obtain M encrypted with K2\n\n#### Definition of the protocol\nImagine we have two players who want to play a secure online coinflip against each other, without the need to trust a server to do correct randomness for the coinflip result.\nIn the following we name these two players _Alice_ and _Bob_.\n\n1. _Alice_ generates two messages. _M1_ represents _Heads_ and _M2_ represents _Tails_. She adds a random string only she knows to both messages.\n2. _Alice_ generates a key-pair _A_\n3. _Alice_ sends __E_A(M1)__ and __E_A(M2)__ to _Bob_ in random order. _Bob_ __must not__ know the order.\n4. _Bob_ picks one oif the messages. We call this message __E_A(M)__.\n5. _Bob_ generates a key-pair _B_.\n6. _Bob_ encrypts the picked message __E_A(M)__ with his key, which results in __E_B(E_A(M))__ and sends this to _Alice_.\n7. _Alice_ decrypts the message _Bob_ sent during _6_, which results to __E_B(M)__ and sends this to _Bob_.\n8. _Bob_ decrypts the message, which results in _M_. This represents the __result of the coinflip__. _Bob_ sends _M_ to _Alice_.\n9. _Alice_ checks if the attached random-string is still correct.\n10. _Alice_ and _Bob_ reveal their secret keys to each other.\n11. _Alice_ and _Bob_ check the correctness of each others computation.\n\nFollowing this protocol, we are now able to perform a secure online coinflip __without__ the need to have a server in which we have to trust not sending manipulated results.\n\n\nWhat you need to compile \u0026 run the project\n-------\n0. open-jdk8 (the client/server does not run with oracle-java8, because of the unsigned bouncy castle fork)\n0. Maven\n\nStructure needed to run the jar\n-------\nThe jar needs to have to be in the same directory as the directory \"ssl-data\".\nThe \"ssl-data\" directory contains key stores used to establish secure TLS-connections to other clients.\nThe \"config\" directory contains a configuration file.\nThe needed directory structure:\n```\n.\n+-- \u003ccoinflip-jar-file\u003e.jar\n+-- config\n|   +-- config.json\n+-- ssl-data\n|   +-- client\n|   +-- keystore\n|   +-- memc_keystore.jks\n|   +-- root\n|   +-- server\n```\n\nThe needed files are provided in the repository.\n\nConfiguration\n-------\nThe client is dependent on a configuration file. It is in JSON format. For now it contains the address of the broker-service.\nExample configuration:\n```\n{\n  \"brokerAddress\": \"\u003cbroker-host\u003e:\u003cport\u003e\"\n}\n```\n\n\nBuilding\n-------\nThis project uses Maven as a building-tool.\nAll dependencies are resolved automatically (including the dependency to a release of [the projects own bouncy castle fork with SRA](https://github.com/timpauls/bc-java)).\nTo get the executable JAR-File run\n```\nmvn clean package\n```\ninside the project main directory.\nThe output jar will be in the \u003cproject-dir\u003e/target folder, named \"coinflip-1.0-SNAPSHOT-full.jar\"\nPlease ensure to use the jar with the \"-full\" suffix, since this jar contains all the dependencies.\n\nAvailable Modes\n-------\n0. a console client\n0. an interactive server\n0. a non-interactive server\n0. a GUI client\n\nRunning\n-------\nTo run the console-client execute\n```\njava -jar \u003cpath-to-jar\u003e --client \u003chostname\u003e:\u003cport\u003e\n```\nthe hostname can either be an ip, or a domain-name.\n\nTo run the interactive-server execute\n```\njava -jar \u003cpath-to-jar\u003e --server \u003cport\u003e \u003cservername\u003e\n```\nwhere the port specifies the port the server is listening on. To stop the server type \"exit\" to the upcoming server-shell and press \"ENTER\".\n\nTo run the silent-server (non-interactive) execute\n```\njava -jar \u003cpath-to-jar\u003e --server-silent \u003cport\u003e \u003cservername\u003e\n```\nwhere the port specifies the port the server is listening on.\n\nTo run the GUI-client execute\n```\njava -jar \u003cpath-to-jar\u003e --gui\n```\n\nTesting\n--------\nTo run the tests use\n```\nmvn clean test\n```\nin the projects base directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmervyn-mccreight%2Fcoinflip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmervyn-mccreight%2Fcoinflip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmervyn-mccreight%2Fcoinflip/lists"}