iOS Developer Library

Developer

Foundation Framework Reference NSURLCredential Class Reference

Options
Deployment Target:

On This Page
Language:

NSURLCredential

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. More...

Inheritance


Import Statement


import Foundation @import Foundation;

Availability


Available in iOS 2.0 and later.
  • Creates and returns an NSURLCredential object for server trust authentication with a given accepted trust.

    Declaration

    Swift

    init(forTrust trust: SecTrust!) -> NSURLCredential

    Objective-C

    + (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:.

    Import Statement

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Objective-C

    + (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.

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • 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.

    Declaration

    Swift

    init(identity identity: SecIdentity, certificates certArray: [AnyObject], persistence persistence: NSURLCredentialPersistence) -> NSURLCredential

    Objective-C

    + (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.

    Import Statement

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • 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.

    Declaration

    Swift

    init(identity identity: SecIdentity!, certificates certArray: [AnyObject], persistence persistence: NSURLCredentialPersistence)

    Objective-C

    - (instancetype)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.

    Import Statement

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(trust trust: SecTrust!)

    Objective-C

    - (instancetype)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:.

    Import Statement

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(user user: String, password password: String, persistence persistence: NSURLCredentialPersistence)

    Objective-C

    - (instancetype)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.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • user user Property

    The receiver’s user name. (read-only)

    Declaration

    Swift

    var user: String? { get }

    Objective-C

    @property(readonly, copy) NSString *user

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The certificates of the credential, if it is a client certificate credential. (read-only)

    Declaration

    Swift

    var certificates: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *certificates

    Discussion

    The certificates are SecCertificateRef objects representing the certificates of the credential. nil if this is not a client certificate credential.

    Import Statement

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • A Boolean value that indicates whether the receiver has a password. (read-only)

    Declaration

    Swift

    var hasPassword: Bool { get }

    Objective-C

    @property(readonly) BOOL hasPassword

    Discussion

    YEStrue if the receiver has a password, NOfalse otherwise.

    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 YEStrue—getting the password may fail, or the user may refuse access.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • password password Property

    The receiver’s password. (read-only)

    Declaration

    Swift

    var password: String? { get }

    Objective-C

    @property(readonly, copy) NSString *password

    Discussion

    You should only access this property if you need the actual password value. If you only need to know if there is a password, use hasPassword. Accessing this property may result in prompting the user for access—for example, if the password is stored in the user’s keychain.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    hasPassword

  • identity identity Property

    The identity of this credential if it is a client certificate credential. (read-only)

    Declaration

    Swift

    var identity: SecIdentity? { get }

    Objective-C

    @property(readonly) SecIdentityRef identity

    Discussion

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • The receiver’s persistence setting. (read-only)

    Declaration

    Swift

    var persistence: NSURLCredentialPersistence { get }

    Objective-C

    @property(readonly) NSURLCredentialPersistence persistence

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

Data Types

  • These constants specify how long the credential will be kept.

    Declaration

    Swift

    enum NSURLCredentialPersistence : UInt { case None case ForSession case Permanent case Synchronizable }

    Objective-C

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

    Constants

    • None

      NSURLCredentialPersistenceNone

      Credential should not be stored.

      Available in iOS 2.0 and later.

    • ForSession

      NSURLCredentialPersistenceForSession

      Credential should be stored only for this session.

      Available in iOS 2.0 and later.

    • Permanent

      NSURLCredentialPersistencePermanent

      Credential should be stored in the keychain.

      Available in iOS 2.0 and later.

    • Synchronizable

      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 iOS 6.0 and later.

    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.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.