NSURLProtectionSpace Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
NSURLProtectionSpace.h
Related sample code

Overview

An NSURLProtectionSpace object represents a server or an area on a server, commonly referred to as a realm, that requires authentication. The protection space defines a series of matching constraints that determine which credential should be provided.

For example, if a request provides your delegate with an NSURLAuthenticationChallenge object that requests a client username and password, your app should provide the correct username and password for the particular host, port, protocol, and realm, as specified in the challenge’s protection space.

Adopted Protocols

NSCopying

Tasks

Creating a Protection Space

Getting Protection Space Properties

Instance Methods

authenticationMethod

Returns the authentication method used by the receiver.

- (NSString *)authenticationMethod
Return Value

The authentication method used by the receiver. The supported authentication methods are listed in “NSURLProtectionSpace Authentication Methods.”

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

distinguishedNames

Returns an array of acceptable certificate-issuing authorities for client certificate authentication.

- (NSArray *)distinguishedNames
Return Value

An array of acceptable certificate-issuing authorities, or nil if the authentication method of the protection space is not client certificate.

Discussion

The returned issuing authorities are encoded with Distinguished Encoding Rules (DER).

Availability
  • Available in iOS 3.0 and later.
Declared In
NSURLProtectionSpace.h

host

Returns the receiver’s host.

- (NSString *)host
Return Value

The receiver's host.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSURLProtectionSpace.h

initWithHost:port:protocol:realm:authenticationMethod:

Initializes a protection space object.

- (id)initWithHost:(NSString *)host port:(NSInteger)port protocol:(NSString *)protocol realm:(NSString *)realm authenticationMethod:(NSString *)authenticationMethod
Parameters
host

The host name for the protection space object.

port

The port for the protection space object. If port is 0 the default port for the specified protocol is used, for example, port 80 for HTTP. Note that servers can, and do, treat these values differently.

protocol

The protocol for the protection space object. The value of protocol is equivalent to the scheme for a URL in the protection space, for example, “http”, “https”, “ftp”, etc.

realm

A string indicating a protocol specific subdivision of the host. realm may be nil if there is no specified realm or if the protocol doesn’t support realms.

authenticationMethod

The type of authentication to use. authenticationMethod should be set to one of the values in “NSURLProtectionSpace Authentication Methods” or nil to use the default, NSURLAuthenticationMethodDefault.

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

initWithProxyHost:port:type:realm:authenticationMethod:

Initializes a protection space object representing a proxy server.

- (id)initWithProxyHost:(NSString *)host port:(NSInteger)port type:(NSString *)proxyType realm:(NSString *)realm authenticationMethod:(NSString *)authenticationMethod
Parameters
host

The host of the proxy server for the protection space object.

port

The port for the protection space object. If port is 0 the default port for the specified proxy type is used, for example, port 80 for HTTP. Note that servers can, and do, treat these values differently.

proxyType

The type of proxy server. The value of proxyType should be set to one of the values specified in “NSURLProtectionSpace Proxy Types.”

realm

A string indicating a protocol specific subdivision of the host. realm may be nil if there is no specified realm or if the protocol doesn’t support realms.

authenticationMethod

The type of authentication to use. authenticationMethod should be set to one of the values in “NSURLProtectionSpace Authentication Methods” or nil to use the default, NSURLAuthenticationMethodDefault.

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

isProxy

Returns whether the receiver represents a proxy server.

- (BOOL)isProxy
Return Value

YES if the receiver represents a proxy server, NO otherwise.

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

port

Returns the receiver’s port.

- (NSInteger)port
Return Value

The receiver's port.

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

protocol

Returns the receiver’s protocol.

- (NSString *)protocol
Return Value

The receiver's protocol, or nil if the receiver represents a proxy protection space.

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

proxyType

Returns the receiver's proxy type.

- (NSString *)proxyType
Return Value

The receiver's proxy type, or nil if the receiver does not represent a proxy protection space. The supported proxy types are listed in “NSURLProtectionSpace Proxy Types.”

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

realm

Returns the receiver’s authentication realm

- (NSString *)realm
Return Value

The receiver’s authentication realm, or nil if no realm has been set.

Discussion

A realm is generally only specified for HTTP and HTTPS authentication.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSURLProtectionSpace.h

receivesCredentialSecurely

Returns whether the credentials for the protection space can be sent securely.

- (BOOL)receivesCredentialSecurely
Return Value

YES if the credentials for the protection space represented by the receiver can be sent securely, NO otherwise.

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

serverTrust

Returns a representation of the server’s SSL transaction state.

- (SecTrustRef)serverTrust
Return Value

The server’s SSL transaction state, or nil if the authentication method of the protection space is not server trust.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSURLProtectionSpace.h

Constants

NSURLProtectionSpace Protocol Types

These constants describe the supported protocols for a protection space, as returned by protocol.

NSString * const NSURLProtectionSpaceHTTP;
NSString * const NSURLProtectionSpaceHTTPS;
NSString * const NSURLProtectionSpaceFTP;
Constants
NSURLProtectionSpaceHTTP

The protocol type for HTTP.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLProtectionSpaceHTTPS

The protocol type for HTTPS.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLProtectionSpaceFTP

The protocol type for FTP.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLProtectionSpace Proxy Types

These constants describe the supported proxy types used in initWithProxyHost:port:type:realm:authenticationMethod: and returned by proxyType.

NSString *NSURLProtectionSpaceHTTPProxy;
NSString *NSURLProtectionSpaceHTTPSProxy;
NSString *NSURLProtectionSpaceFTPProxy;
NSString *NSURLProtectionSpaceSOCKSProxy;
Constants
NSURLProtectionSpaceHTTPProxy

The proxy type for HTTP proxies.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLProtectionSpaceHTTPSProxy

The proxy type for HTTPS proxies.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLProtectionSpaceFTPProxy

The proxy type for FTP proxies.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLProtectionSpaceSOCKSProxy

The proxy type for SOCKS proxies.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLProtectionSpace.h

NSURLProtectionSpace Authentication Methods

These constants describe the available authentication methods used in initWithHost:port:protocol:realm:authenticationMethod:, initWithProxyHost:port:type:realm:authenticationMethod: and returned by authenticationMethod.

NSString *NSURLAuthenticationMethodDefault;
NSString *NSURLAuthenticationMethodHTTPBasic;
NSString *NSURLAuthenticationMethodHTTPDigest;
NSString *NSURLAuthenticationMethodHTMLForm;
NSString *NSURLAuthenticationMethodNegotiate;
NSString *NSURLAuthenticationMethodNTLM;
NSString *NSURLAuthenticationMethodClientCertificate;
NSString *NSURLAuthenticationMethodServerTrust;
Constants
NSURLAuthenticationMethodDefault

Use the default authentication method for a protocol.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLAuthenticationMethodHTTPBasic

Use HTTP basic authentication for this protection space.

This is equivalent to NSURLAuthenticationMethodDefault for HTTP.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLAuthenticationMethodHTTPDigest

Use HTTP digest authentication for this protection space.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLAuthenticationMethodHTMLForm

Use HTML form authentication for this protection space.

The URL loading system never issues authentication challenges based on this authentication method. However, if your app authenticates by submitting a web form (or in some other protocol-neutral way), you can specify this protection space when you persist or look up credentials using the NSURLCredentialStorage class.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLAuthenticationMethodNegotiate

Negotiate whether to use Kerberos or NTLM authentication for this protection space.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLAuthenticationMethodNTLM

Use NTLM authentication for this protection space.

Available in iOS 2.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLAuthenticationMethodClientCertificate

Use client certificate authentication for this protection space.

This authentication method can apply to any protocol.

Available in iOS 3.0 and later.

Declared in NSURLProtectionSpace.h.

NSURLAuthenticationMethodServerTrust

Perform server trust authentication (certificate validation) for this protection space.

This authentication method can apply to any protocol, and is most commonly used for overriding SSL and TLS chain validation.

To learn more, read “Performing Authentication and Customizing Server Certificate Validation”.

Available in iOS 3.0 and later.

Declared in NSURLProtectionSpace.h.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLProtectionSpace.h