CFHTTPAuthentication Reference

Derived from
Framework
CoreServices
Companion guide
Declared in
CFHTTPAuthentication.h
CFHTTPMessage.h

Overview

The CFHTTPAuthentication opaque type provides an abstraction of HTTP authentication information.

Functions by Task

Creating an HTTP authentication

CFHTTP Authentication Functions

This section describes the CFNetwork authentication functions that are used to manage authentication information associated with a request. The functions work with a CFHTTPAuthentication object, which is created from an HTTP response that failed with a 401 or 407 error code.

When you have analyzed the CFHTTPAuthentication object and acquired the necessary credentials to perform the authentication, call CFHTTPMessageApplyCredentials or CFHTTPMessageApplyCredentialDictionary to perform the authentication.

Getting the CFHTTPAuthentication type ID

Functions

CFHTTPAuthenticationAppliesToRequest

Returns a Boolean value that indicates whether a CFHTTPAuthentication object is associated with a CFHTTPMessage object.

Boolean CFHTTPAuthenticationAppliesToRequest (
   CFHTTPAuthenticationRef auth,
   CFHTTPMessageRef request
);
Parameters
auth

The CFHTTPAuthentication object to examine.

request

Request that auth is to be tested against.

Return Value

TRUE if auth is associated with request, otherwise FALSE.

Discussion

If this function returns TRUE, you can use auth to provide authentication information when using request.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationCopyDomains

Returns an array of domain URLs to which a given CFHTTPAuthentication object can be applied.

CFArrayRef CFHTTPAuthenticationCopyDomains (
   CFHTTPAuthenticationRef auth
);
Parameters
auth

The CFHTTPAuthentication object to examine.

Return Value

A CFArray object that contains the domain URL’s to which auth should be applied. Ownership follows the Create Rule.

Discussion

This function is provided for informational purposes only.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationCopyMethod

Gets the strongest authentication method that will be used when a CFHTTPAuthentication object is applied to a request.

CFStringRef CFHTTPAuthenticationCopyMethod (
   CFHTTPAuthenticationRef auth
);
Parameters
auth

The CFHTTPAuthentication object to examine.

Return Value

A string containing the authentication method that will be used auth is applied to a request. If more than one authentication method is available, the strongest authentication method is returned. Ownership follows the Create Rule.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationCopyRealm

Gets an authentication information’s namespace.

CFStringRef CFHTTPAuthenticationCopyRealm (
   CFHTTPAuthenticationRef auth
);
Parameters
auth

The CFHTTPAuthentication object to examine.

Return Value

The namespace, if there is one; otherwise NULL. Ownership follows the Create Rule.

Discussion

Some authentication methods provide a namespace, and it is usually used to prompt the user for a name and password.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationCreateFromResponse

Uses an authentication failure response to create a CFHTTPAuthentication object.

CFHTTPAuthenticationRef CFHTTPAuthenticationCreateFromResponse (
   CFAllocatorRef alloc,
   CFHTTPMessageRef response
);
Parameters
alloc

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

response

Response indicating an authentication failure; usually a 401 or a 407 response.

Return Value

CFHTTPAuthentication object that can be used for adding credentials to future requests. Ownership follows the Create Rule.

Discussion

This function uses a response containing authentication failure information to create a reference to a CFHTTPAuthentication object. You can use the object to add credentials to future requests. You can query the object to get the following information:

When you have determined what information will be needed to perform the authentication and accumulated that information, call CFHTTPMessageApplyCredentials or CFHTTPMessageApplyCredentialDictionary to perform the authentication.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationGetTypeID

Gets the Core Foundation type identifier for the CFHTTPAuthentication opaque type.

CFTypeID CFHTTPAuthenticationGetTypeID ();
Return Value

The Core Foundation type identifier for the CFHTTPAuthentication opaque type.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationIsValid

Returns a Boolean value that indicates whether a CFHTTPAuthentication object is valid.

Boolean CFHTTPAuthenticationIsValid (
   CFHTTPAuthenticationRef auth,
   CFStreamError *error
);
Parameters
auth

The CFHTTPAuthentication object to examine.

error

Pointer to a CFStreamError structure, whose fields, if an error has occurred, are set to the error and the error’s domain.

Return Value

TRUE if auth contains enough information to be applied to a request.

If this function returns FALSE, the CFHTTPAuthentication object may still contain useful information, such as the name of an unsupported authentication method.

Discussion

If this function returns TRUE for auth, the object is good for use with functions such as CFHTTPMessageApplyCredentials and CFHTTPMessageApplyCredentialDictionary. If this function returns FALSE, auth is invalid, and authentications using it will not succeed.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationRequiresAccountDomain

Returns a Boolean value that indicates whether a CFHTTPAuthentication object uses an authentication method that requires an account domain.

Boolean CFHTTPAuthenticationRequiresAccountDomain (
   CFHTTPAuthenticationRef auth
);
Parameters
auth

The CFHTTPAuthentication object to examine.

Return Value

TRUE if auth uses an authentication method that requires an account domain, otherwise FALSE.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationRequiresOrderedRequests

Returns a Boolean value that indicates whether authentication requests should be made one at a time.

Boolean CFHTTPAuthenticationRequiresOrderedRequests (
   CFHTTPAuthenticationRef auth
);
Parameters
auth

The CFHTTPAuthentication object to examine.

Return Value

TRUE if auth requires ordered requests, otherwise FALSE.

Discussion

Some authentication methods require that future requests must be performed in an ordered manner. If this function returns TRUE, clients can improve their chances of authenticating successfully by issuing requests one at a time as responses come back from the server.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

CFHTTPAuthenticationRequiresUserNameAndPassword

Returns a Boolean value that indicates whether a CFHTTPAuthentication object uses an authentication method that requires a username and a password.

Boolean CFHTTPAuthenticationRequiresUserNameAndPassword (
   CFHTTPAuthenticationRef auth
);
Parameters
auth

The CFHTTPAuthentication object to examine.

Return Value

TRUE if auth requires a username and password when it is applied to a request; otherwise, FALSE.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

Data Types

CFHTTPAuthenticationRef

An opaque reference representing HTTP authentication information.

typedef struct __CFHTTPAuthentication *CFHTTPAuthenticationRef;
Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPAuthentication.h

Constants

CFHTTP Authentication Scheme Constants

Specifies the authentication scheme when adding authentication information to a CFHTTP request message object.

const CFStringRef kCFHTTPAuthenticationSchemeBasic;
const CFStringRef kCFHTTPAuthenticationSchemeDigest;
const CFStringRef kCFHTTPAuthenticationSchemeNegotiate;
const CFStringRef kCFHTTPAuthenticationSchemeNTLM;
Constants
kCFHTTPAuthenticationSchemeBasic

Specifies basic authentication consisting of a user name and a password.

Available in iOS 2.0 and later.

Declared in CFHTTPMessage.h.

kCFHTTPAuthenticationSchemeDigest

Reserved.

Available in iOS 2.0 and later.

Declared in CFHTTPMessage.h.

kCFHTTPAuthenticationSchemeNegotiate

Specifies the Negotiate authentication scheme.

Available in iOS 2.0 and later.

Declared in CFHTTPMessage.h.

kCFHTTPAuthenticationSchemeNTLM

Specifies the NTLM authentication scheme.

Available in iOS 2.0 and later.

Declared in CFHTTPMessage.h.

Discussion

The authentication scheme constants are used to specify the authentication scheme when calling CFHTTPMessageAddAuthentication.

CFStream HTTP Authentication Error Constants

Authentication error codes that may be returned when trying to apply authentication to a request.

enum CFStreamErrorHTTPAuthentication{
   kCFStreamErrorHTTPAuthenticationTypeUnsupported = -1000,
   kCFStreamErrorHTTPAuthenticationBadUserName = -1001,
   kCFStreamErrorHTTPAuthenticationBadPassword = -1002
};
typedef enum CFStreamErrorHTTPAuthentication CFStreamErrorHTTPAuthentication;
Constants
kCFStreamErrorHTTPAuthenticationTypeUnsupported

Specified authentication type is not supported.

Available in iOS 2.0 and later.

Declared in CFHTTPAuthentication.h.

kCFStreamErrorHTTPAuthenticationBadUserName

User name is in a format that is not suitable for the request. Currently, user names are decoded using kCFStringEncodingISOLatin1.

Available in iOS 2.0 and later.

Declared in CFHTTPAuthentication.h.

kCFStreamErrorHTTPAuthenticationBadPassword

Password is in a format that is not suitable for the request. Currently, passwords are decoded using kCFStringEncodingISOLatin1.

Available in iOS 2.0 and later.

Declared in CFHTTPAuthentication.h.

CFHTTPMessageApplyCredentialDictionary Keys

Constants for keys in the dictionary passed to CFHTTPMessageApplyCredentialDictionary.

const CFStringRef kCFHTTPAuthenticationUsername;
const CFStringRef kCFHTTPAuthenticationPassword;
const CFStringRef kCFHTTPAuthenticationAccountDomain;
Constants
kCFHTTPAuthenticationUsername

Username to use for authentication.

Available in iOS 2.0 and later.

Declared in CFHTTPAuthentication.h.

kCFHTTPAuthenticationPassword

Password to use for authentication.

Available in iOS 2.0 and later.

Declared in CFHTTPAuthentication.h.

kCFHTTPAuthenticationAccountDomain

Account domain to use for authentication.

Available in iOS 2.0 and later.

Declared in CFHTTPAuthentication.h.