AdvancedURLConnections

Read Me About AdvancedURLConnections ==================================== 1.1 AdvancedURLConnections demonstrates various advanced networking techniques with NSURLConnection. Specifically, it demonstrates how to respond to authentication challenges, how to modify the default server trust evaluation (for example, to support a server with a self-signed certificate), and how to provide client identities. AdvancedURLConnections requires features that were introduced in iOS 3.0. Packing List ------------ The sample contains the following items: o Read Me About AdvancedURLConnections.txt -- This file. o AdvancedURLConnections.xcodeproj -- An Xcode project for the sample. o Resources -- The project nib, images, and so on. o Ancillary Code -- A directory full of code that's not directly relevant to the main function of this sample. o AdvancedGetController.[h,m,xib] -- A view controller that manages the Get tab. This is a relatively dull application of NSURLConnection. What's interesting here is how it passes the authentication challenges off to the challenge handlers. o ChallengeHandler.[h,m] -- An abstract base class for handling NSURLConnection authentication challenges. o ChallengeHandlers -- A directory containing a number of concrete subclasses of ChallengeHandler for handling specific types of authentication challenges. o UI Building Blocks -- A directory containing general purpose user interface elements used by other parts of the program, most notably the various challenge handlers. o CredentialsController.[h,m,xib] -- A view controller that manages the Credentials tab. This lets you manage credentials so as to test various features implemented by the AdvancedGetController. o DebugController.[h,m,xib] -- A view controller that manages the Debug tab. o Credentials.[h,m] -- A singleton model object that vends credentials such as certificates and identities. o DebugOptions.[h,m] -- A singleton model object that vends our debugging preferences. Using the Sample ---------------- Testing all of the functionality within AdvancedURLConnections requires some complex server setup (see "Server Configuration", below). However, you can test some basic functionality without setting up a server at all. 1. Run the program on a device or simulator. 2. Switch to the Get tab. 3. Tap in the URL field and pick the first item on the pick list ("http://www.cacert.org/images/cacert4.png"). The program will download and display an image. 4. Tap in the URL field and pick the second item on the pick list ("https://www.cacert.org/images/cacert4.png"). The download will fail because CAcert's root certificate is not trusted by default. 5. Switch to the Credentials tab. 6. Tap in the URL field and pick the first item on the pick list ("http://www.cacert.org/certs/root.der"). The program will download the CAcert's root certificate and offer to import it. Tap Import to do so. 7. Switch to the Debug tab. 8. Tap on "Trust Imported Certificates" in the "TLS Server Validation" section of the table. 9. Now switch back to the Get tab. 10. Tap the Get button. This time the download succeeds because the program now trusts CAcert's root certificate. IMPORTANT: The above will work on both the simulator and a real device. However, some features of this sample only work on a real device. See the "Caveats" section, below, for details. Building the Sample ------------------- The sample was built using Xcode 3.2.3 on Mac OS X 10.6.4 with iPhone SDK 4.0. You should be able to just open the project and choose Build from the Build menu. The resulting program should be compatible with all devices running iOS 3.2 and later. The bulk of my testing was done with an iPod touch (second generation) running iOS 4.0. How It Works ------------ To get started with this sample you should have a basic understanding of how the NSURLConnection API works. If you're not already familiar with downloading data via NSURLConnection, you should look at the SimpleURLConnections sample code. <http://developer.apple.com/iphone/library/samplecode/SimpleURLConnections/index.html> The differences between the AdvancedGetController and the equivalent code in SimpleURLConnections is quite small. The critical change is that AdvancedGetController implements the authentication challenge delegate methods (-connection:canAuthenticateAgainstProtectionSpace: and -connection:didReceiveAuthenticationChallenge:) using the ChallengeHandler class and its various concrete subclasses. The ChallengeHandler class maintains a registry of subclasses that are capable of handling challenges. The registry is keyed off the authentication method (NSString) associated with the protection space (NSURLProtectionSpace) associated with the challenge (NSURLAuthenticationChallenge). AdvancedGetController uses this in two ways: o -[AdvancedGetController connection:canAuthenticateAgainstProtectionSpace:] calls +[ChallengeHandler supportsProtectionSpace:] to determine whether there's a handler for a specific challenge. o -[AdvancedGetController connection:didReceiveAuthenticationChallenge:] calls +[ChallengeHandler handlerForChallenge:parentViewController:] to instantiate a challenge handler for the challenge. It then holds on to the challenge handler while the challenge is running. When the challenge handler is done, it calls its -challengeHandlerDidFinish: delegate method. AdvancedGetController implements that method and, in response, resolves the challenge (it calls -[ChallengeHandler resolveChallenge], which applies the credentials to the challenge) and then forgets about the current challenge and waits for the next one (or for the connection to start running normally). Each concrete subclass of ChallengeHandler is responsible for handling one specific type of challenge. The current handlers include: o AuthenticationChallengeHandler -- This handles HTTP authentication challenges (authentication methods NSURLAuthenticationMethodDefault, NSURLAuthenticationMethodHTTPBasic and NSURLAuthenticationMethodHTTPDigest) from both origin servers and proxies. o ClientIdentityChallengeHandler -- This handles HTTPS client identity challenges (authentication method NSURLAuthenticationMethodClientCertificate), which occur when the server requires that the client supply an identity. o ServerTrustChallengeHandler -- This handles HTTPS server trust challenges (authentication method NSURLAuthenticationMethodServerTrust) which allows the client to override the default HTTPS TLS server trust evaluation (for example, to allow a specific self-signed certificate). The first two challenge handlers have an associated view controller in the "UI Building Blocks" directory. These do the actual work of running the UI presented in response to the challenge. The challenge handler itself is basically glue code that attaches these view controllers to the AdvancedGetController. AdvancedGetController can't use these view controllers directly because not all challenge handling UI is done by way of a view controller; for example, the ServerTrustChallengeHandler does all of its work using UIAlertViews. Server Configuration -------------------- Testing AdvancedURLConnections is tricky because it requires you to have access to a server that presents all of the authentication challenges handled by the program. I did the bulk of my testing with the personal Web Sharing built in to Mac OS X 10.6.x. Web Sharing is based on Apache HTTP Server, a full-featured web server that you can tweak for testing purposes. The following is a summary of the tweaks that I did. WARNING: These suggestions are for testing purposes only and may result in security vulnerabilities. Do not apply them to a production web server, or to a web server that's accessible to untrusted clients. A. enable password authentication -- To password protect a directory, I created a "protected" directory within "/Library/WebServer/Documents" and added the following to "/etc/apache2/