Merge pull request #4 from thrasr/master

Updates certificates process, color coded devices and commands, and timeout capabilities

README.md

@@ -7,23 +7,47 @@ Instructions and code for setting up a simple iOS Mobile Device Management (MDM)
  * Publicly accessible Linux/Unix server
  * Apple Enterprise Account
  * Apple Developer Account
+ * Python 2.7
  * openssl command-line
  * Java SDK (java/javac)
  * Apple's iPhone Configuration Utility
-    * (OS X Version)[http://support.apple.com/kb/dl1465]
-    * (Windows Version)[http://support.apple.com/kb/DL1466]
+    * [OS X Version](http://support.apple.com/kb/dl1465)
+    * [Windows Version](http://support.apple.com/kb/DL1466)
 
 # Certificate Setup
 
-First in the **scripts** directory, modify **server.cnf** replacing **<SERVER_IP>** with your server's IP address. Next run **make_certs.sh**, be careful to read the directions at the top of each step (Usually specifying the 'Common Name' needed).  Hopefully this works properly and generates 90% of what you need.
+### Instructions
+
+ 1. Run **make_certs.sh**, which can be found in the **/scripts** directory.
+   * Carefully read the directions given for each step and follow the instructions
+   * This should generate several certificates needed to move forward to the next step.  See the Explanation section for more details.
+ 2. Go to Apple's [iOS Provisioning Portal](Apple Member Center). Upload **customer.csr** in the **/scripts** folder on the iOS Provisioning Portal.
+   * You will be given the option to download a .cer file.  Do so and name this file something along the lines of YOUR_MDM.cer.  
+   * Run the following openssl command in your terminal and then move the generated mdm.pem file to **/vendor-signing/com/softhinker** (it should replace an empty file of the same name).
+
+    openssl x509 -inform der -in YOUR_MDM.cer -out mdm.pem
+
+ 3. Find **Test.java** in the **/vendor-signing/com/softhinker** folder.  On line 95, replace the word *test* with the PEM password that you used when running make_certs.sh.
+   * Replace only the word test so that your password is still in quotes.
+ 4. Run the **vendor-signing.sh** script found in the **/scripts** directory.
+   * There now should be a file named plist_encoded located in **/vendor-signing**.
+ 5. Go to [Apple's Push Certificates Portal](https://identity.apple.com/pushcert/) and upload the plist_encoded file.  Download the certificate as **PushCert.pem** and place it within the **/server** directory.
+   * Notice the (i) icon beside the renew option.  If you click it there will be a long string of text ending in **UID=com.apple.mgmt...**, make sure to copy that string starting at **com** since you will need it later.
+
+![Apple Portal](images/certPortal.png)
+
+
+### Explanation
+
+In the scripts directory, there exists a server.cnf.  This is used for certificate generation and the first step of the script will place the server IP address in the correct place.
 
 In the vendor-signing directory, under com/softhinker, you will notice several certificates are included:
  * customer.der
    * Must be replaced
    * Generated from **make_certs.sh**
    * Accept defaults for all other values (Including **Challenge password**)
  * intermediate.pem 
-   * Automatically replace by make_certs
+   * Automatically replace by **make_certs.sh**
    * Apple's WWDR intermediate certificate
  * mdm.pem
    * Must be replaced
@@ -32,20 +56,14 @@ In the vendor-signing directory, under com/softhinker, you will notice several c
    * Download the file, should be in .cer format
    * Convert to pem: **openssl x509 -inform der -in YOUR_MDM.cer -out mdm.pem**
  * root.pem
-   * Automatically replace by make_certs
+   * Automatically replace by **make_certs.sh**
    * Apple's root certificate
  * vendor.p12
    * Must be replaced
    * Generated from **make_certs.sh**
 
-Now that all certificates are in place, find **Test.java** under vendor-signing/com/softhinker. On line 95, change <code>password = "test";</code> to use your password specified during **make_certs.sh** step 1.  
-
-Run **vendor-signing.sh** under the scripts directory. You should now have **plist_encoded.plist** in the **vendor-signing** directory.  Upload this to [Apple's Push Certificates Portal](https://identity.apple.com/pushcert/).  If all was successfull you will see a screen similar to below:
-
-![Apple Portal](images/certPortal.png)
-
+After generating certificates and placing your PEM password in line 95 of Test.java, the vendor-signing.sh script will be run.  This script takes several scripts we have already generated and creates a plist for use with apple's push certificates portal.
 
-Notice the (i) icon besides renew.  If you click it there will be a long string of text ending in **UID=com.apple.mgmt...**, make sure to copy that string starting at **com** since you will need it later.  Finally download the certificate, save as **PushCert.pem** in the **server** directory.
 
 # Enrollment profile
 
@@ -76,10 +94,12 @@ After you are finished, highlight the entry in the table, and click **Export**.
 
 Save in the **mdm-server/server/** directory as **Enroll**.  You should now have an **Enroll.mobileconfig** file.
 
+Finally, some versions of IPCU don't include the correct settings for all versions of iOS.  Open the Enroll.mobileconfig file in a text editor.  Find the **AccessRights** key.  Make sure the value is 8191 (some versions of ICPU will use 2047, if you see this, change it to 8191) and then save.
+
 
 # Server Setup
 
-The server code is a direct copy from [Intrepidus Group's blackhat presentation](https://intrepidusgroup.com/).  Copy over the **mdm-server/server** directory you put the enrollment profile and certificates in to your server.  You will need to install the following:
+The server code based on and heavily takes from [Intrepidus Group's blackhat presentation](https://intrepidusgroup.com/).  Copy over the **mdm-server/server** directory you put the enrollment profile and certificates in to your server.
 
 You must have the following installed on the server:
   * Openssl
@@ -96,28 +116,31 @@ Network Settings
   * Inbound access to port 8080
   * iOS device must also have outbound access to gateway.push.apple.com:5223
 
-If everything is setup appropriately, simply navigate to the **scripts** directory and run **./daemonScript.sh**.
+If everything is setup appropriately, simply navigate to the **/server** directory and run <code>python server.py</code>.
 
 On the device navigate to: **https://YOUR_HOST:8080/**
 Once there you need to, in order: 
- 1. Tap here to install the CA Cert (for Server/Identity)
- 2. Tap here to enroll in MDM 
- 3. Select Command (Device Lock is a good one to test)
+ 1. Tap *here* to install the CA Cert (for Server/Identity)
+ 2. Tap *here* to enroll in MDM (the device should appear after this step) 
+ 3. Select Command (DeviceLock is a good one to test) and check your device.  Click Submit to send the command.
+ 4. If everything works, you're good to go!  As of right now some of the commands aren't fully implemented.  Feel free to experiment with different commands!
 
 ---
-![Device Enrollment Steps](images/deviceEnroll.png)
+![Device Enrollment Steps](images/deviceEnroll.jpg)
 ---
 
 You can now run those commands from any web browser, a successfull command will often looks something like the following:
 
 ---
 ![Command Success](images/commandSuccess.png)
 ---
-You may have to hit the **refresh** link, if the output doesn't look recent.
+
+Click the "Response" button to see the plist response from apple.
+
 
 # Client Reporting
 
-The MDM server also has REST endpoints for reporting issues and geolocation data from the enrolled clients.  The API can be imported into any project as follows:
+The MDM server also has REST endpoints for reporting issues and geolocation data from the enrolled clients.  This functionality may be used at a later point in time by a security app. The API can be imported into any project as follows:
 
 * Click on the top level Project item and add files ("option-command-a")
 * Navigate to client-reporting/
@@ -144,9 +167,27 @@ The library provides the following functions:
 This client API can be coupled with the [iMAS security-check controls]([email protected]:project-imas/security-check.git) to provide accurate reporting of jailbreak and debugger detection.  
 
 
-Some sticking points that folks may run into:
-* Modify "scripts/server.cnf" to have your server's IP address in place of <SERVER_IP>. 
-* Be careful to follow the prompts for each step of make_certs.sh, you do need to put things for common name when asked.
-* I just updated make_certs.sh to to grab the Apple certs needed directly (Requires curl), it looks like they were missing from the repo (0 length).
+Apologies for the long and complex setup, we hope to eventually make things easier and simpler.  Please post questions to github if you get stuck and we'll do our best to help.  Enjoy!
+
+
+
+# LICENSE AND ATTRIBUTION
+
+Copyright 2013-2014 The MITRE Corporation, All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+
+This project also uses code from various sources under various licenses.
+
+[The original code from the Intrepidus Group's python server is under the BSD License found here.](server/LICENSE)
+
+[The Softhinker certificate signing code is under the Apache License found here.](vendor-signing/LICENSE)
 
+[The website's Bootstrap code is under the MIT License found here.](server/static/dist/LICENSE)
 
+Finally we use some free [glyphicons](http://glyphicons.com/) that are included with bootstrap.

scripts/make_certs.sh

@@ -1,10 +1,19 @@
 #!/bin/sh
 
+echo ""
+echo "Setting up server.cnf."
+echo "Please enter the IP address of your server."
+read IP
+sed -i -e "s/<SERVER_IP>/$IP/g" server.cnf
+echo "Done."
+echo ""
+
 echo ""
 echo "Setting up certificates for MDM server testing!"
 echo ""
 echo "1. Creating Certificate Authority (CA)"
 echo " ** For 'Common Name' enter something like 'MDM Test CA'"
+echo " ** Create and a remember the PEM pass phrase for use later on"
 echo ""
 openssl req -new -x509 -extensions v3_ca -keyout cakey.key -out cacert.crt -days 365
 
@@ -16,7 +25,7 @@ openssl genrsa 2048 > server.key
 openssl req -new -key server.key -out server.csr 
 
 echo ""
-echo "3. Signing the server key with the CA. You'll the CA passphrase from step 1."
+echo "3. Signing the server key with the CA. You'll use the PEM pass phrase from step 1."
 echo ""
 openssl x509 -req -days 365 -in server.csr -CA cacert.crt -CAkey cakey.key -CAcreateserial -out server.crt -extfile ./server.cnf -extensions ssl_server
 
@@ -30,8 +39,8 @@ openssl genrsa 2048 > identity.key
 openssl req -new -key identity.key -out identity.csr
 
 echo ""
-echo "5. Signing the identity key with the CA. You'll the CA passphrase from step 1."
-echo " ** Give it a passphrase. You'll need to include that in the IPCU profile."
+echo "5. Signing the identity key with the CA. You'll the PEM pass phrase from step 1."
+echo " ** Create an export passphrase. You'll need to include it in the IPCU profile."
 echo ""
 openssl x509 -req -days 365 -in identity.csr -CA cacert.crt -CAkey cakey.key -CAcreateserial -out identity.crt
 openssl pkcs12 -export -out identity.p12 -inkey identity.key -in identity.crt -certfile cacert.crt
@@ -40,23 +49,30 @@ openssl pkcs12 -export -out identity.p12 -inkey identity.key -in identity.crt -c
 
 echo ""
 echo "6. Copying keys and certs to server folder"
-cp server.key ../server/Server.key
-cp server.crt ../server/Server.crt
-cp cacert.crt ../server/CA.crt
+# Move relevant certs to the /server/ directory
+mv server.key ../server/Server.key
+mv server.crt ../server/Server.crt
+mv cacert.crt ../server/CA.crt
+mv identity.crt ../server/identity.crt
 cp identity.p12 ../server/Identity.p12
 
 echo "7. Generating keys and certs for plist generation"
+echo ""
 openssl req -inform pem -outform der -in identity.csr -out customer.der
-cp Identity.p12 vendor.p12
-cp identity.csr customer.csr
+# Rename identity.csr to be used with the iOS Provisioning Portal
+mv identity.csr customer.csr
 
+echo ""
 echo "8. Getting Apple certificates online"
-
-curl https://developer.apple.com/certificationauthority/AppleWWDRCA.cer -o AppleWWDRCA.cer
+curl https://developer.apple.com/certificationauthority/AppleWWDRCA.cer -ko AppleWWDRCA.cer
 curl http://www.apple.com/appleca/AppleIncRootCertificate.cer -o AppleIncRootCertificate.cer
 
 openssl x509 -inform der -in AppleWWDRCA.cer -out intermediate.pem
 openssl x509 -inform der -in AppleIncRootCertificate.cer -out root.pem
 
-cp intermediate.pem ../vendor-signing/com/softhinker/intermediate.pem
-cp root.pem ../vendor-signing/com/softhinker/root.pem
+# Move relevant files for use in softhinker vendor-signing
+# Need to manually generate and move mdm.pem
+mv intermediate.pem ../vendor-signing/com/softhinker/intermediate.pem
+mv root.pem ../vendor-signing/com/softhinker/root.pem
+mv identity.p12 ../vendor-signing/com/softhinker/vendor.p12
+mv customer.der ../vendor-signing/com/softhinker/customer.der