Added canned access policies

Remove GET/ACL constructors
Added lots of comments
General cleanup

 //
 //  ASIS3Request.h
-//  Mac
 //
 //  Created by Ben Copsey on 30/06/2009.
 //  Copyright 2009 All-Seeing Interactive. All rights reserved.
 //
+// A (basic) class for accessing data stored on Amazon's Simple Storage Service (http://aws.amazon.com/s3/)
+// It uses the REST API, with canned access policies rather than full support for ACLs (though if you build/parse them yourself you can still use ACLs)
 
 #import <Foundation/Foundation.h>
 #import "ASIHTTPRequest.h"
 
+// See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/index.html?RESTAccessPolicy.html for what these mean
+extern NSString *const ASIS3AccessPolicyPrivate; // This is the default in S3 when no access policy header is provided
+extern NSString *const ASIS3AccessPolicyPublicRead;
+extern NSString *const ASIS3AccessPolicyPublicReadWrote;
+extern NSString *const ASIS3AccessPolicyAuthenticatedRead;
+
 @interface ASIS3Request : ASIHTTPRequest {
+
+	// Your S3 access key. Set it on the request, or set it globally using [ASIS3Request setSharedAccessKey:]
+	NSString *accessKey;
+	
+	// Your S3 secret access key. Set it on the request, or set it globally using [ASIS3Request setSharedSecretAccessKey:]
+	NSString *secretAccessKey;
+	
+	// Name of the bucket to talk to
 	NSString *bucket;
+	
+	// path to the resource you want to access on S3. Leave empty for the bucket root
 	NSString *path;
+	
+	// The string that will be used in the HTTP date header. Generally you'll want to ignore this and let the class add the current date for you, but the accessor is used by the tests
 	NSString *dateString;
+	
+	// The mime type of the content for PUT requests
+	// Set this if having the correct mime type returned to you when you GET the data is important (eg it will be served by a web-server)
+	// Will be set to 'application/octet-stream' otherwise in iPhone apps, or autodetected on Mac OS X
 	NSString *mimeType;
-	NSString *accessKey;
-	NSString *secretAccessKey;
+	
+	NSString *accessPolicy;
 }
 
 #pragma mark Constructors
 
+// Create a request, building an appropriate url
 + (id)requestWithBucket:(NSString *)bucket path:(NSString *)path;
+
+// Create a PUT request using the file at filePath as the body
 + (id)PUTRequestForFile:(NSString *)filePath withBucket:(NSString *)bucket path:(NSString *)path;
-+ (id)GETRequestWithBucket:(NSString *)bucket path:(NSString *)path;
-+ (id)listRequestWithBucket:(NSString *)bucket prefix:(NSString *)prefix maxResults:(int)maxResults marker:(NSString *)marker;
-+ (id)ACLRequestWithBucket:(NSString *)bucket path:(NSString *)path;
 
+// Create a list request
++ (id)listRequestWithBucket:(NSString *)bucket prefix:(NSString *)prefix maxResults:(int)maxResults marker:(NSString *)marker;
 
+// Generates the request headers S3 needs
+// Automatically called before the request begins in startRequest
 - (void)generateS3Headers;
-- (void)setDate:(NSDate *)date;
 
+// Uses the supplied date to create a Date header string
+- (void)setDate:(NSDate *)date;
 
+// Only works on Mac OS, will always return 'application/octet-stream' on iPhone
 + (NSString *)mimeTypeForFileAtPath:(NSString *)path;
 
 #pragma mark Shared access keys
+
+// Get and set the global access key, this will be used for all requests the access key hasn't been set for
 + (NSString *)sharedAccessKey;
 + (void)setSharedAccessKey:(NSString *)newAccessKey;
 + (NSString *)sharedSecretAccessKey;
 + (void)setSharedSecretAccessKey:(NSString *)newAccessKey;
 
-#pragma mark S3 Authentication helpers
-+ (NSData *)HMACSHA1withKey:(NSString *)key forString:(NSString *)string;
-+ (NSString *)base64forData:(NSData *)theData;
 
 @property (retain) NSString *bucket;
 @property (retain) NSString *path;
@@ -49,4 +77,5 @@
 @property (retain) NSString *mimeType;
 @property (retain) NSString *accessKey;
 @property (retain) NSString *secretAccessKey;
+@property (assign) NSString *accessPolicy;
 @end

 //
 //  ASIS3Request.m
-//  Mac
 //
 //  Created by Ben Copsey on 30/06/2009.
 //  Copyright 2009 All-Seeing Interactive. All rights reserved.
@@ -9,11 +8,32 @@
 #import "ASIS3Request.h"
 #import <CommonCrypto/CommonHMAC.h>
 
+NSString* const ASIS3AccessPolicyPrivate = @"private";
+NSString* const ASIS3AccessPolicyPublicRead = @"public-read";
+NSString* const ASIS3AccessPolicyPublicReadWrote = @"public-read-write";
+NSString* const ASIS3AccessPolicyAuthenticatedRead = @"authenticated-read";
+
 static NSString *sharedAccessKey = nil;
 static NSString *sharedSecretAccessKey = nil;
 
+// Private stuff
+@interface ASIHTTPRequest ()
+	+ (NSData *)HMACSHA1withKey:(NSString *)key forString:(NSString *)string;
+	+ (NSString *)base64forData:(NSData *)theData;
+@end
+
 @implementation ASIS3Request
 
+- (void)dealloc
+{
+	[bucket release];
+	[path release];
+	[dateString release];
+	[mimeType release];
+	[accessKey release];
+	[secretAccessKey release];
+	[super dealloc];
+}
 
 + (id)requestWithBucket:(NSString *)bucket path:(NSString *)path
 {
@@ -33,25 +53,11 @@ static NSString *sharedSecretAccessKey = nil;
 	return request;
 }
 
-+ (id)GETRequestWithBucket:(NSString *)bucket path:(NSString *)path
-{
-	ASIS3Request *request = [ASIS3Request requestWithBucket:bucket path:path];
-	[request setRequestMethod:@"GET"];
-	return request;
-}
-
-+ (id)ACLRequestWithBucket:(NSString *)bucket path:(NSString *)path
-{
-	ASIS3Request *request = [ASIS3Request requestWithBucket:bucket path:[NSString stringWithFormat:@"%@?acl",path]];
-	[request setRequestMethod:@"GET"];
-	return request;
-}
 
 + (id)listRequestWithBucket:(NSString *)bucket prefix:(NSString *)prefix maxResults:(int)maxResults marker:(NSString *)marker
 {
 	ASIS3Request *request =  [[[ASIS3Request alloc] initWithURL:[NSURL URLWithString:[NSString stringWithFormat:@"http://%@.s3.amazonaws.com/?prefix=/%@&max-keys=%hi&marker=%@",bucket,prefix,maxResults,marker]]] autorelease];
 	[request setBucket:bucket];
-	[request setRequestMethod:@"GET"];
 	return request;
 }
 
@@ -60,6 +66,9 @@ static NSString *sharedSecretAccessKey = nil;
 // NSTask does seem to exist in the 2.2.1 SDK, though it's not in the 3.0 SDK. It's probably best if we just use a generic mime type on iPhone all the time.
 #if TARGET_OS_IPHONE
 	return @"application/octet-stream";
+	
+// Grab the mime type using an NSTask to run the 'file' program, with the Mac OS-specific parameters to grab the mime type
+// Perhaps there is a better way to do this?
 #else
 	NSTask *task = [[NSTask alloc] init];
 	[task setLaunchPath: @"/usr/bin/file"];
@@ -86,37 +95,51 @@ static NSString *sharedSecretAccessKey = nil;
 
 - (void)generateS3Headers
 {
+	// If an access key / secret access keyu haven't been set for this request, let's use the shared keys
 	if (![self accessKey]) {
 		[self setAccessKey:[ASIS3Request sharedAccessKey]];
 	}
 	if (![self secretAccessKey]) {
 		[self setAccessKey:[ASIS3Request sharedSecretAccessKey]];
 	}
+	// If a date string hasn't been set, we'll create one from the current time
 	if (![self dateString]) {
 		[self setDate:[NSDate date]];
 	}
+	[self addRequestHeader:@"Date" value:[self dateString]];
+	
+	// Ensure our formatted string doesn't use '(null)' for the empty path
 	if (![self path]) {
 		[self setPath:@""];
 	}
+
 	
-	[self addRequestHeader:@"Date" value:[self dateString]];
+	NSString *canonicalizedResource = [NSString stringWithFormat:@"/%@/%@",[self bucket],[self path]];
 	
-	[self addRequestHeader:@"x-amz-acl" value:@"private"];
-
+	// Add a header for the access policy if one was set, otherwise we won't add one (and S3 will default to private)
+	NSString *canonicalizedAmzHeaders = @"";
+	if ([self accessPolicy]) {
+		[self addRequestHeader:@"x-amz-acl" value:[self accessPolicy]];
+		canonicalizedAmzHeaders = [NSString stringWithFormat:@"x-amz-acl:%@\n",[self accessPolicy]];
+	}
+	
+	// Jump through hoops while eating hot food
 	NSString *stringToSign;
-	NSString *canonicalizedResource = [NSString stringWithFormat:@"/%@/%@",[self bucket],[self path]];
-	NSString *canonicalizedAmzHeaders = @"x-amz-acl:private";
 	if ([[self requestMethod] isEqualToString:@"PUT"]) {
 		[self addRequestHeader:@"Content-Type" value:[self mimeType]];
-		stringToSign = [NSString stringWithFormat:@"PUT\n\n%@\n%@\n%@",[self mimeType],dateString,canonicalizedResource];
+		stringToSign = [NSString stringWithFormat:@"PUT\n\n%@\n%@\n%@%@",[self mimeType],dateString,canonicalizedAmzHeaders,canonicalizedResource];
 	} else {
-		stringToSign = [NSString stringWithFormat:@"%@\n\n\n%@\n%@",[self requestMethod],dateString,canonicalizedResource];
+		stringToSign = [NSString stringWithFormat:@"%@\n\n\n%@\n%@%@",[self requestMethod],dateString,canonicalizedAmzHeaders,canonicalizedResource];
 	}
-	NSLog(@"%@",stringToSign);
 	NSString *signature = [ASIS3Request base64forData:[ASIS3Request HMACSHA1withKey:[self secretAccessKey] forString:stringToSign]];
 	NSString *authorizationString = [NSString stringWithFormat:@"AWS %@:%@",[self accessKey],signature];
 	[self addRequestHeader:@"Authorization" value:authorizationString];
-	
+}
+
+- (void)startRequest
+{
+	[self generateS3Headers];
+	[super startRequest];
 }
 
 #pragma mark Shared access keys
@@ -203,4 +226,5 @@ static NSString *sharedSecretAccessKey = nil;
 @synthesize mimeType;
 @synthesize accessKey;
 @synthesize secretAccessKey;
+@synthesize accessPolicy;
 @end

 //
 //  ASIS3RequestTests.h
-//  Mac
+//  asi-http-request
 //
 //  Created by Ben Copsey on 12/07/2009.
 //  Copyright 2009 All-Seeing Interactive. All rights reserved.

 //
 //  ASIS3RequestTests.m
-//  Mac
+//  asi-http-request
 //
 //  Created by Ben Copsey on 12/07/2009.
 //  Copyright 2009 All-Seeing Interactive. All rights reserved.
@@ -57,9 +57,9 @@
 	GHAssertTrue(success,@"Failed to generate the correct authorisation header for a list request");
 	
 	// Test fetch ACL
-	path = @"";
+	path = @"?acl";
 	dateString = @"Tue, 27 Mar 2007 19:44:46 +0000";
-	request = [ASIS3Request ACLRequestWithBucket:bucket path:path];
+	request = [ASIS3Request requestWithBucket:bucket path:path];
 	[request setDateString:dateString];
 	[request setSecretAccessKey:secretAccessKey];
 	[request setAccessKey:accessKey];