diff --git a/README.md b/README.md index 0fa3981..b0b77f5 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,48 @@ -# Screenshots +# MISPbump +Simple and secure synchronisation of MISP instances -## Login +# What is MISPbump? +With MISPbump admins can easily synchronize MISP instances by exchanging relevant information via encrypted QR codes. -![Login](./screenshots/mispbump-login.png) +Note: only **use case 1** from the [documentation](https://www.circl.lu/doc/misp/sharing/) is supported. -## Home +# How does MISPbump work? +First of all: MISP admins login by providing the base URL of their instance and their authkey (automationkey). -Actions: **Profile View** (Menubar) and **New Sync** (Floating Action Button) +On a successfull login the admins profile and the linked organisation information will be downloaded automatically. +This information can be updated at any time from the profile view. -![Home (Empty)](./screenshots/mispbump-home-0.png) +From the main screen you can start a synchronisation process by pressing the dedicated button. -## Profile -Organisation information loaded automatically from your MISP instance +The synchronisation process consists of 3 steps: +1. **Key Exchange** + To provide a secure chanel for data exchange, the first step is to generate a shared secret with [Diffie–Hellman key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) ([Elliptic Curve](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman)). -Actions: **Delete and logout** (Menubar) and **Update Info** (Floating Action Button) + Public keys are exchanged via QR code. -![Profile](./screenshots/mispbump-profile.png) +1. **Synchronisation Information Exchange** + Contains the following information: + + Own Organisation: Name, UUID, description, nationality, sector, type and contacts + + Own User: Email + + Own MISP instance: base URL + + Generated: sync user authkey, sync user password + (your partner will create a sync user with these credentials) -## Sync + The Synchronisation information is encrypted with AES using the shared secret (from step 1). -Core functionality of MISPbump. - -**First Step:** Exchange keys to derive a shared secret - -![Profile](./screenshots/mispbump-sync-0.png) -![Profile](./screenshots/mispbump-sync-1.png) - -**Second Step:** Exchange encrypted sync information - -![Profile](./screenshots/mispbump-sync-2.png) -![Profile](./screenshots/mispbump-sync-3.png) - -## Sync information - -After a successfull exchange an entry for this organisation will appear. - -Actions: **Delete Sync information** (Menubar) and **Upload** (Floating Action Button in settings tab) - -**Credentials:** With these credentials you will be able to log in on the other MISP instance (SyncUser) - -![Profile](./screenshots/mispbump-sync-info-credentials.png) - -**Settings:** These are typical settings which are also available from the MISP web interface. - -![Profile](./screenshots/mispbump-sync-info-settings.png) - -## Upload - -Shows the status of the upload to your MISP instance. -If errors occure they will be displayed and the user can restart the process. - -![Profile](./screenshots/mispbump-upload-1.png) -![Profile](./screenshots/mispbump-upload-2.png) - -## Home with successfull sync - -![Home (Synced)](./screenshots/mispbump-home.png) + The sync process information will be saved securely on the device, that means the upload can be started any time in the future. -# What does this app? -1. Exchange public keys to make following communication private (via QR code) - + Diffie Hellman key exchange -2. Exchange encrypted information needed to sync two MISP instances -3. Upload information to MISP instance. +1. **Upload information to own MISP instance** + Uploading the information to the MISP instance is accomplished with MISP's REST API. -# MISPBump -![Alt text](./poster/mispbump.png) + Uploading consists of the following steps: + 1. Create organisation + 1. Create Sync User & add to organisation + 1. Create Sync Server & populate with information above + +After that the two MISP instances are connected. + +# Dependencies ++ [Retrofit](https://github.com/square/retrofit) ++ [ZXing](https://github.com/zxing/zxing) \ No newline at end of file diff --git a/screenshots/README.md b/screenshots/README.md new file mode 100644 index 0000000..dd1f0b4 --- /dev/null +++ b/screenshots/README.md @@ -0,0 +1,58 @@ +# Screenshots + +## Login + +![Login](./mispbump-login.png) + +## Home + +Actions: **Profile View** (Menubar) and **New Sync** (Floating Action Button) + +![Home (Empty)](./mispbump-home-0.png) + +## Profile +Organisation information loaded automatically from your MISP instance + +Actions: **Delete and logout** (Menubar) and **Update Info** (Floating Action Button) + +![Profile](./mispbump-profile.png) + +## Sync + +Core functionality of MISPbump. + +**First Step:** Exchange keys to derive a shared secret + +![Profile](./mispbump-sync-0.png) +![Profile](./mispbump-sync-1.png) + +**Second Step:** Exchange encrypted sync information + +![Profile](./mispbump-sync-2.png) +![Profile](./mispbump-sync-3.png) + +## Sync information + +After a successfull exchange an entry for this organisation will appear. + +Actions: **Delete Sync information** (Menubar) and **Upload** (Floating Action Button in settings tab) + +**Credentials:** With these credentials you will be able to log in on the other MISP instance (SyncUser) + +![Profile](./mispbump-sync-info-credentials.png) + +**Settings:** These are typical settings which are also available from the MISP web interface. + +![Profile](./mispbump-sync-info-settings.png) + +## Upload + +Shows the status of the upload to your MISP instance. +If errors occure they will be displayed and the user can restart the process. + +![Profile](./mispbump-upload-1.png) +![Profile](./mispbump-upload-2.png) + +## Home with successfull sync + +![Home (Synced)](./mispbump-home.png) \ No newline at end of file