CFHTTPAuthentication Reference

Derived from	CFType
Framework	CoreServices
Companion guide	CFNetwork Programming 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 OS X v10.4 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 OS X version 10.4 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 OS X version 10.4 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 OS X version 10.4 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:

whether it can be used and re-used to authenticate with its corresponding server [CFHTTPAuthenticationIsValid]
the authentication method that will be used when it is used to perform an authentication [CFHTTPAuthenticationCopyMethod]
whether it is associated with a particular CFHTTPMessageRef [CFHTTPAuthenticationAppliesToRequest
whether a user name and a password will be required when it is used to perform an authentication [CFHTTPAuthenticationRequiresUserNameAndPassword]
whether an account domain will be required when it is used to perform an authentication [CFHTTPAuthenticationRequiresAccountDomain]
whether authentication requests should be sent one at a time to the corresponding server [CFHTTPAuthenticationRequiresOrderedRequests]
the namespace (if any) that the domain uses to prompt for a name and password [CFHTTPAuthenticationCopyRealm]
the domain URLs the instance applies to [CFHTTPAuthenticationCopyDomains]

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 OS X version 10.4 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 OS X version 10.4 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 OS X version 10.4 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 OS X version 10.4 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 OS X version 10.4 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 OS X version 10.4 and later.

Declared In

CFHTTPAuthentication.h

Data Types

CFHTTPAuthenticationRef

An opaque reference representing HTTP authentication information.

typedef struct __CFHTTPAuthentication *CFHTTPAuthenticationRef;

Availability

Available in OS X version 10.4 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 OS X v10.1 and later.

Declared in CFHTTPMessage.h.

kCFHTTPAuthenticationSchemeDigest

Reserved.

Available in OS X v10.1 and later.

Declared in CFHTTPMessage.h.

kCFHTTPAuthenticationSchemeNegotiate

Specifies the Negotiate authentication scheme.

Available in OS X v10.5 and later.

Declared in CFHTTPMessage.h.

kCFHTTPAuthenticationSchemeNTLM

Specifies the NTLM authentication scheme.

Available in OS X v10.5 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 and later.

Declared in CFHTTPAuthentication.h.

kCFHTTPAuthenticationPassword

Password to use for authentication.

Available in OS X v10.4 and later.

Declared in CFHTTPAuthentication.h.

kCFHTTPAuthenticationAccountDomain

Account domain to use for authentication.

Available in OS X v10.4 and later.

Declared in CFHTTPAuthentication.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.