Skip to content

Commit

Permalink
Folds both READMEs into one with updated info
Browse files Browse the repository at this point in the history
  • Loading branch information
@thrasr
thrasr committed Jun 3, 2014
1 parent f3a98fe commit 589710e
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 209 deletions.
11 changes: 7 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -160,6 +165,4 @@ 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:
* 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!
218 changes: 13 additions & 205 deletions server/README
View file
Original file line number Diff line number Diff line change
@@ -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://<server-ip>: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://<server-ip>: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://<server-ip>: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!



0 comments on commit 589710e

Please sign in to comment.