From 589710ef005a61cdf9bd5e893393418a5acb673a Mon Sep 17 00:00:00 2001 From: thrasr Date: Tue, 3 Jun 2014 18:14:19 +0000 Subject: [PATCH] Folds both READMEs into one with updated info --- README.md | 11 ++- server/README | 218 +++----------------------------------------------- 2 files changed, 20 insertions(+), 209 deletions(-) diff --git a/README.md b/README.md index cb100be..82bdbb5 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,11 @@ Instructions and code for setting up a simple iOS Mobile Device Management (MDM) 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 text so that your password is still in quotes. + * 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. @@ -92,6 +94,8 @@ 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 @@ -119,6 +123,7 @@ 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 (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.jpg) @@ -160,6 +165,4 @@ The library provides the following functions: This client API can be coupled with the [iMAS security-check controls](git@github.com:project-imas/security-check.git) to provide accurate reporting of jailbreak and debugger detection. -Some sticking points that folks may run into: -* Be careful to follow the prompts for each step of make_certs.sh, you do need to put things for common name when asked. -* Check the readme file under the server directory for additional notes (this will eventually be integrated into a single readme). +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! diff --git a/server/README b/server/README index fa221e2..1e6e815 100644 --- a/server/README +++ b/server/README @@ -1,230 +1,38 @@ -Here's a very simple, bare-bones, works-enough-to-test-and-play server for -iOS Mobile Device Management. - -This file outlines some of the steps to set it up. Additional documentation, -and explanation of the protocol itself, is located in the Black Hat -whitepaper elsewhere in this repository. +For more documentation, please see the README file located in the root directory of this repository. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - Requirements - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -software: -* python 2.7 -* python libraries: - * web.py: http://webpy.org/ - * M2Crypto: http://chandlerproject.org/bin/view/Projects/MeTooCrypto - * PyOpenSSL: https://pypi.python.org/pypi/pyOpenSSL -* OpenSSL (to create certs) -* Iphone Configuration Utility (free from Apple) - -credentials: -* Apple Push Notification Service (APNS) certificate, from Apple - -network configuration: -* Outbound access from server to gateway.push.apple.com (tcp port 2195) -* Outbound access from device to gateway.push.apple.com (tcp port 5223) -* Inbound access from device to port 8080 on your test server - - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - Files + Important Files -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- [required, included] -Example.mobileconfig Sample profile to install (disables certain apps, etc.) -favicon.ico Because "favicon.ico not found" in logs annoy me +favicon.ico Replace with your website's icon server.py The server itself device.py A device class to support the server -xactn.log Log of commands and responses [empty] +xactn.log Log of commands and responses [initially empty] -certs/make_certs.sh Script using OpenSSL to create the various certs and - keys you'll need (aside from the APNS cert) +certs/make_certs.sh Script to create the various certs and + keys you'll need (uses OpenSSL) -[required, need to get from Apple] +[required, need to get/create manually] PushCert.pem Certificate and private key (no passphrase) for APNS - See README in /mdm-server/ for more instructions + See README in root directory for more instructions +Enroll.mobileconfig Use IPCU to create profile with MDM payload, + used to enroll devices -[required, you need to make with make_cert.sh] + +[required, created by make_cert.sh] CA.crt CA certificate used to sign the server cert [load onto device] Server.key Private key (no passphrase) for SSL server Server.crt Certificate for SSL server Identity.p12 Device identity cert (for MDM enrollment profile) -Enroll.mobileconfig Use IPCU to create profile with MDM payload, - used to enroll devices [optional, to test installing custom apps] +Example.mobileconfig Sample profile to install (disables certain apps, etc.) MyApp.ipa Bundle for a custom iOS app MyApp.mobileprovision Mobile provisioning profile for the custom app Manifest.plist Simple manifest for custom app [Manifest.plist.template provided] - - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - Setup - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -1. Get an APNS certificate - -Used to be you needed to be in the enterprise developer program to get this. -Now I believe you can acquire one through the normal iOS dev program, or -you can install Lion Server and get one through there. - -Once you have the certificate, you need to convert it to a plain .PEM file -containing the certificate and private key. To avoid having to type the -private key password every time you send a message to the device, you'll need -to remove the passphrase as well. (obviously, you need to protect the key -extra-special after that.) - -When I did this on my Mac, here's what I did (your mileage may vary, esp. -if you're not doing this on a Mac): - - 1. Locate the certificate in Keychain Access - 2. Export to a .p12 file - 3. Convert to .pem - "openssl pkcs12 -in OrigPushCert.p12 -out PushCert.pem" - 4. Strip the passphrase - "openssl rsa -in PushCert.pem -out PushKeyNoPass.pem" - 5. Open PushCert.pem in a text editor - 6. Replace the encrypted "RSA Private Key" section with contents - of PushKeyNoPass.pem - 7. Save it out - -This should give you a "PushCert.pem" file containing the APNS certificate and -private key, with no passphrase. Again, exercise appropriate precautions to -ensure this doesn't get posted on the web somewhere. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -2. Create server and identity certificates - -If you have a valid, signed certificate you can use, use it. Simpler that way. - -Otherwise, we'll have to create a CA, use it to sign a server certificate, and -install that CA cert onto the device you want to test wtih. - -Change into the certs folder, and run the "make_certs.sh" script. - -This will: - - 1. Create a new CA. For Common Name, call it something like "MDM Test CA." - - 2. Create a server certificate and key. For Common Name, you need to use - the name of the server as it will appear in the MDM profile. If you use - a DNS-resolvable name, that goes here. If you're going to just use the - IP address, that goes here. (like '192.168.1.1') - - 3. Create an identity certificate and key, and save it to a .p12 file. - You'll need to give the .p12 an export password. Include this .p12 - and the password in the "Credentials" payload for the IPCU profile you'll - create below, then select the Identity payload in the MDM payload. - - 4. Finally, it'll copy everything back up a folder next to the server.py - script. - -There's a fair amount of voodoo in all this, hopefully it'll work fine for you. -If it doesn't, Google Early and Often. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -3. Create an MDM enrollment profile - -You'll need the iPhone Configuration Utility (IPCU), a free download from -Apple. Launch that, and create a new profile. You'll have to first enter -some generic information in the "General" payload, then go to the MDM payload -and create a new entry: - - * For the Server field, enter the URL for your server - (ex: https://192.168.1.1:8080/server) - * For the Check In field, do the same (but change to /checkin) - (ex: https://192.168.1.1:8080/checkin) - * The Topic field needs the be the User ID listed in Subject Name section - of the APNS push certificate - (ex: com.apple.mgmt.XServer.d74790cb-66a3-48bc-9d02-945d91500db9) - * Leave the rest as default (check all the things you want to manage, etc.) - -Finally, you'll need to add an Identity certificate in the Certificates -payload section. This can be an end-user cert created above (alongside the -server cert), or something else from a CA chain that'll be trusted by the -device. If you used the script in step 2, then add the "Identity.p12" file -you created. You'll want to enter the passphrase you created for the .p12 -file into the Certificate payload, otherwise you'll have to enter it on the -device every time you re-enroll. (and you may be re-enrolling a lot. :) ) - -Save this configuration. In IPCU, go to File -> Export, select "none" for -security (no signing, no encryption), then Next, and give it a filename. -Copy the file to the server folder as "Enroll.mobileconfig." - -Now, it gets tricky. The latest version of IPCU (3.4) does NOT include the -proper settings for installing and managing applications. So you need to: - - * Edit the Enroll.mobileconfig file (in your favorite appropriate editor) - * Find the "AccessRights" key (probably near the top of PayloadConent) - * Change the value from 2047 (default for all rights) to 8191 (all for iOS5) - * Save it and exit - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -4. Install the CA cert to the device - -If you're using self-signed server and identity certificates, then the device -will need to have the certificate for the self-signed CA installed, otherwise -it won't trust the connection to the server. - -The easiest way to do this is by launching the server, and on the device, -surfing in Mobile Safari to: - - https://:8080/ca - -If Safari refuses access to this server because it's untrusted (this'll depend -on device settings -- it might just warn you), then you should edit the server -code and comment out the CherryPy lines (importing CherryPy, and the two -loading up the certs). Then restart the server, and connect again using -just straight http (no TLS). - -Don't forget to change it back, as the MDM service requires TLS as of iOS 5. - - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -5. Enroll the device in MDM - -On the device, surf in Mobile Safari to: - - https://:8080/enroll - -and the MDM enrollment profile should be downloaded and installed. Once you've -agreed to all the appropriate dialogs, open up the server in a window on -your desktop (https://:8080/) and select a command from the -drop-down. "Device Information" is a good one to test, as is "DeviceLock." - -If those work, you're good to do. Messages (in and out) should be written -to xactn.log, and credentials (for push notification and remote passcode -clearing) will be stored in creds.py. Protect both of those files, as they -contain sensitive information (like the unlock token, which is a keybag that -will allow you to unlock the device). - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -6. Experiment, and enjoy! - -That's it. Or, hopefully, it will be. :) - -Again, this is a very simple, bare-bones, virtually-no-error-handling kind of -experimental server. So don't expect it to be perfect. But hopefully it'll be -enough for you to begin experimenting with MDM, so you can better understand -how it works and what limitations (and features) it may have. - -If you want to try installing different profiles, just build them in IPCU, -export them to a .mobileconfig file, and copy that over the provided -Example.mobileconfig file. Then the "Install Profile" command will send that -new profile to the testing device. - -Thanks for playing! - - -