NSURLCredential Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.2 and later.
Companion guide
Declared in
NSURLCredential.h

Overview

NSURLCredential is an immutable object representing an authentication credential consisting of authentication information specific to the type of credential and the type of persistent storage to use, if any.

The URL loading system supports three types of credentials: password-based user credentials, certificate-based user credentials, and certificate-based server credentials (used when verifying the server’s identity).

When you create a credential, you can specify that it should be used for a single request, persisted temporarily (until your app quits), or persisted permanently (in the keychain).

Tasks

Creating a Credential

Getting Credential Properties

Class Methods

credentialForTrust:

Creates and returns an NSURLCredential object for server trust authentication with a given accepted trust.

+ (NSURLCredential *)credentialForTrust:(SecTrustRef)trust
Parameters
trust

The accepted trust.

Discussion

Before creating a server trust credential, it is the responsibility of the delegate of an NSURLConnection object or an NSURLDownload object to evaluate the trust. Do this by calling SecTrustEvaluate, passing it the trust obtained from the serverTrust method of the server’s NSURLProtectionSpace object. If the trust is invalid, the authentication challenge should be cancelled with cancelAuthenticationChallenge:.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURLCredential.h

credentialWithIdentity:certificates:persistence:

Creates and returns an NSURLCredential object for client certificate authentication with a given identity and a given array of client certificates using a given persistence setting.

+ (NSURLCredential *)credentialWithIdentity:(SecIdentityRef)identity certificates:(NSArray *)certArray persistence:(NSURLCredentialPersistence)persistence
Parameters
identity

The identity for the credential.

certArray

An array of one or more SecCertificateRef objects representing certificates for the credential.

persistence

The persistence setting for the credential.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURLCredential.h

credentialWithUser:password:persistence:

Creates and returns an NSURLCredential object for internet password authentication with a given user name and password using a given persistence setting.

+ (NSURLCredential *)credentialWithUser:(NSString *)user password:(NSString *)password persistence:(NSURLCredentialPersistence)persistence
Parameters
user

The user for the credential.

password

The password for user.

persistence

The persistence setting for the credential.

Return Value

An NSURLCredential object with user name user, password password, and using persistence setting persistence.

Discussion

If persistence is NSURLCredentialPersistencePermanent the credential is stored in the keychain.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLCredential.h

Instance Methods

certificates

Returns an array of SecCertificateRef objects representing the certificates of the credential if it is a client certificate credential.

- (NSArray *)certificates
Return Value

The certificates of the credential, or nil if this is not a client certificate credential.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURLCredential.h

hasPassword

Returns a Boolean value that indicates whether the receiver has a password.

- (BOOL)hasPassword
Return Value

YES if the receiver has a password, NO otherwise.

Discussion

This method does not attempt to retrieve the password.

If this credential's password is stored in the user’s keychain, password may return nil even if this method returns YES, since getting the password may fail, or the user may refuse access.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLCredential.h

identity

Returns the identity of this credential if it is a client certificate credential.

- (SecIdentityRef)identity
Return Value

The identity of the credential, or NULL if this is not a client certificate credential.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURLCredential.h

initWithIdentity:certificates:persistence:

Returns an NSURLCredential object for client certificate authentication initialized with a given identity and a given array of client certificates using a given persistence setting.

- (id)initWithIdentity:(SecIdentityRef)identity certificates:(NSArray *)certArray persistence:(NSURLCredentialPersistence)persistence
Parameters
identity

The identity for the credential.

certArray

An array of one or more SecCertificateRef objects representing certificates for the credential.

persistence

The persistence setting for the credential.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURLCredential.h

initWithTrust:

Returns an NSURLCredential object for server trust authentication initialized with a given accepted trust.

- (id)initWithTrust:(SecTrustRef)trust
Parameters
trust

The accepted trust.

Discussion

Before creating a server trust credential, it is the responsibility of the delegate of an NSURLConnection object or an NSURLDownload object to evaluate the trust. Do this by calling SecTrustEvaluate, passing it the trust obtained from the serverTrust method of the server’s NSURLProtectionSpace object. If the trust is invalid, the authentication challenge should be cancelled with cancelAuthenticationChallenge:.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURLCredential.h

initWithUser:password:persistence:

Returns an NSURLCredential object initialized with a given user name and password using a given persistence setting.

- (id)initWithUser:(NSString *)user password:(NSString *)password persistence:(NSURLCredentialPersistence)persistence
Parameters
user

The user for the credential.

password

The password for user.

persistence

The persistence setting for the credential.

Return Value

An NSURLCredential object initialized with user name user, password password, and using persistence setting persistence.

Discussion

If persistence is NSURLCredentialPersistencePermanent the credential is stored in the keychain.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLCredential.h

password

Returns the receiver’s password.

- (NSString *)password
Return Value

The receiver’s password.

Discussion

If the password is stored in the user’s keychain, this method may result in prompting the user for access.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLCredential.h

persistence

Returns the receiver’s persistence setting.

Return Value

The receiver’s persistence setting.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLCredential.h

user

Returns the receiver’s user name.

- (NSString *)user
Return Value

The receiver’s user name.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLCredential.h

Constants

NSURLCredentialPersistence

These constants specify how long the credential will be kept.

typedef NS_ENUM(NSUInteger, NSURLCredentialPersistence) {
   NSURLCredentialPersistenceNone,
   NSURLCredentialPersistenceForSession,
   NSURLCredentialPersistencePermanent,
   NSURLCredentialPersistenceSynchronizable
};
Constants
NSURLCredentialPersistenceNone

Credential should not be stored.

Available in OS X v10.2 and later.

Declared in NSURLCredential.h.

NSURLCredentialPersistenceForSession

Credential should be stored only for this session.

Available in OS X v10.2 and later.

Declared in NSURLCredential.h.

NSURLCredentialPersistencePermanent

Credential should be stored in the keychain.

Available in OS X v10.2 and later.

Declared in NSURLCredential.h.

NSURLCredentialPersistenceSynchronizable

Credential should be stored permanently in the keychain, and in addition should be distributed to other devices based on the owning AppleID.

Available in OS X v10.8 and later.

Declared in NSURLCredential.h.

Discussion

In iOS, credentials are stored in the app’s keychain, and can be accessed only by that app (and other apps in the same keychain access group, where applicable).

In OS X, credentials are stored in the user’s keychain. The credential’s initial access control list (ACL) allows access only by that app. However, other apps can see that a password exists for a given host, port, and realm combination, and can request that the user grant permission to use that credential.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLCredential.h