From dd374300f1032212052e720fd5342519b7810dc0 Mon Sep 17 00:00:00 2001 From: Felix Prahl-Kamps Date: Mon, 15 Jul 2019 18:01:42 +0200 Subject: [PATCH 1/2] improve readme --- README.md | 86 +++++++++++++++---------------------------- screenshots/README.md | 58 +++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 56 deletions(-) create mode 100644 screenshots/README.md diff --git a/README.md b/README.md index 0fa3981..fac42fd 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,42 @@ -# 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 users 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 (unencrypted QR code) +1. Synchronisation Information Exchange (with shared secret encrypted QR code) +1. Upload information to own MISP instance -Actions: **Delete and logout** (Menubar) and **Update Info** (Floating Action Button) +#### 1. Key Exchange +[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)), where the public part is exchanged via a QR code. +The result is a shared secret which will be used to encrypt the information passed via QR code in step 2. -![Profile](./screenshots/mispbump-profile.png) +#### 2. Synchronisation Information Exchange +Local information like Organisation name, UUID, description and User information is encrypted with a from step 1 derived key. +The information can now be securely exchanged via QR code. -## Sync +#### 3. Upload information to MISP instance +Uploading the information to the MISP instance is accomplished with MISP's REST API. -Core functionality of MISPbump. +Uploading consists of the following steps: +1. Create organisation +1. Create Sync User & add to organisation +1. Create Sync Server & populate with information above -**First Step:** Exchange keys to derive a shared secret +After that the two MISP instances are connected. -![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) - - -# 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. - -# MISPBump -![Alt text](./poster/mispbump.png) +# 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 From 7b673e2a6e3ebfe7cbfec200e5219241fdd91aa1 Mon Sep 17 00:00:00 2001 From: Felix Prahl-Kamps Date: Tue, 16 Jul 2019 13:38:05 +0200 Subject: [PATCH 2/2] improve readme --- README.md | 38 ++++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index fac42fd..b0b77f5 100644 --- a/README.md +++ b/README.md @@ -9,31 +9,37 @@ Note: only **use case 1** from the [documentation](https://www.circl.lu/doc/misp # How does MISPbump work? First of all: MISP admins login by providing the base URL of their instance and their authkey (automationkey). -On a successfull login the users profile and the linked organisation information will be downloaded automatically. +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. From the main screen you can start a synchronisation process by pressing the dedicated button. The synchronisation process consists of 3 steps: -1. Key Exchange (unencrypted QR code) -1. Synchronisation Information Exchange (with shared secret encrypted QR code) -1. Upload information to own MISP instance +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)). -#### 1. Key Exchange -[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)), where the public part is exchanged via a QR code. -The result is a shared secret which will be used to encrypt the information passed via QR code in step 2. + Public keys are exchanged via QR code. -#### 2. Synchronisation Information Exchange -Local information like Organisation name, UUID, description and User information is encrypted with a from step 1 derived key. -The information can now be securely exchanged via QR code. +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) -#### 3. Upload information to MISP instance -Uploading the information to the MISP instance is accomplished with MISP's REST API. + The Synchronisation information is encrypted with AES using the shared secret (from step 1). -Uploading consists of the following steps: -1. Create organisation -1. Create Sync User & add to organisation -1. Create Sync Server & populate with information above + The sync process information will be saved securely on the device, that means the upload can be started any time in the future. + + +1. **Upload information to own MISP instance** + Uploading the information to the MISP instance is accomplished with MISP's REST API. + + 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.