objective-c - How does (NSURLCredential *) proposedCredential in iOS work?

Question

Morning

I've been working on creating a iOS application that uses stored credentials in NSURLCredentialStorage for a specific protectionspace. I've now gotten to the point where I'm using proposedCredential to fetch the stored credentials.

My problem is that it is returning null, and I can't seem to find any good explanation on what proposedCredential actually does and why it isn't returning what I think it should.

This is what I'm doing:

First I define a NSURLProtectionSpace, give credentials and store them in the NSURLCredentialStorage. I've already checked that this is being done before I'm referencing proposedCredential and that the credentials that I'm passing on are correct.

NSURLProtectionSpace *protectionSpaceOne = [[NSURLProtectionSpace alloc] 
                                           initWithHost:xyz 
                                              port: 80 
                                              protocol:NSURLProtectionSpaceHTTP 
                                              realm:nil 
                                              authenticationMethod:NSURLAuthenticationMethodDefault];

  //credential is initiated elsewhere.
[[NSURLCredentialStorage sharedCredentialStorage] setDefaultCredential:credential forProtectionSpace:protectionSpaceOne]; 

-(void)connection:(NSURLConnection *)connection didRecieveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge{
   //Has the authentication failed before?
   if([challenge previousFailureCount]>0){
      //Why?
      NSError *error = [challenge error];
       //Here I respond to the failure count
       [[challenge sender]cancelAuthenticationCallenge:challenge];
   }

   NSURLCredential *proposedCredential = [challenge proposedCredential];

}

Could someone tell me what proposedCredential actually does, what it compares together to figure out if there is a credential that it should pass on, and what it is that I'm possibly missing from the code?

For reference, I've been reading the Apple doc, specifically this, this, and this

All help would be appreciated.