PKCS12UserIdentityDiscovery

public class PKCS12UserIdentityDiscovery : UserIdentityObtaining

PKCS #12 User Identity Discovery


Usage

  1. Create PKCS12UserIdentityDiscovery
  2. Create UserIdentityObserver
  3. Start request to Resource URL

Create PKCS12UserIdentityDiscovery

let resourceType = <#File extension#>
let resourceInBundle = <#Filename#>
let passphrase = <#Passphrase#>
do {
    let userIdentityDiscovery = try PKCS12UserIdentityDiscovery(resourceInBundle: resourceInBundle, resourceType: resourceType, passphrase: passphrase)
} catch let error {
    // Handle error of not existing resource
    return
}

Create UserIdentityObserver

Another convenient way is to pass the PKCS12UserIdentityDiscovery instance to a UserIdentityObserver. See also UserIdentityObserver()

// create the observer
let userIdentityObserver = UserIdentityObserver(userIdentityDiscovery: userIdentityDiscovery, identityStore: self)

// register it to SAPURLSession
let sapURLSessionForResource = SAPURLSession(delegate: self)
sapURLSessionForResource.register(userIdentityObserver)

Start request to Resource URL

let request = URLRequest(url: <#resourceURL#>)
let dataTask = sapURLSessionForResource.dataTask(with: request) { data, response, error in
    // Handle the error and the response
}
dataTask.resume()

Implement UserIdentityStoring protocol

The UserIdentityObserver uses this protocol to store and retrieve the identity. The implementer has to store the identity in a secure way. The identity received by the PKCS12UserIdentityDiscovery. The URL can be used to distinguish identities if the application uses more resource servers.

func store(identity: Data, for url: URL?) throws -> Void {
    // save the identity to a secure storage
}

func identity(for url: URL?) throws -> Data? {
    // return the identity from the secure storage
}

func delete(for url: URL?) throws {
    // delete the identity from the secure storage
}

General flow obtaining user identity

Certificate discovery is automatic when using a UserIdentityObserver that is registered to a SAPURLSession. The UserIdentityObserver can be used with the PKCS12UserIdentityDiscovery to obtain the certificate from

  • Data or
  • path or
  • resource in bundle
  1. The application initiates a request to the resource server which requires a user identity resulting in a challenge in the SAPURLSession.
  2. The UserIdentityObserver calls the application using the UserIdentityStoring protocol. If there is no valid identity, the observer calls the PKCS12UserIdentityDiscovery to obtain a certificate.
  3. The resource is transformed by the PKCS12UserIdentityDiscovery to a PKCS #12 Data which will be passed to the caller as the result.
  4. This Data is passed to UserIdentityObserver.
  5. The UserIdentityObserver calls the UserIdentityStoring delegate and passes the Data to it.
    This Data should be stored securely and provided later if the component needs an identity.
  6. The original request to the resource server restarts automatically so the next time the server challenges for an identity, it is accessible.

Component to retrieve a User certificate from the device

  • Convenience initializer of PKCS12UserIdentityDiscovery. It creates the path form the given parameters.

    Throws

    error if the path is not valid

    Declaration

    Swift

    public convenience init(resourceInBundle: String, resourceType: String, passphrase: String, bundle: Bundle = Bundle.main) throws

    Parameters

    resourceInBundle

    resource name in bundle

    resourceType

    type of the resource - extension

    passphrase

    String to open the PKCS #12 Data

    bundle

    bundle where the resource is located. Default: main bundle.

  • Convenience initializer of PKCS12UserIdentityDiscovery. The init reads PKCS #12 Data from the path.

    Throws

    error if the path is not reachable

    Declaration

    Swift

    public convenience init(path: String, passphrase: String) throws

    Parameters

    path

    path of the PKCS #12 file

    passphrase

    String to open the PKCS #12 Data

  • Convenience initializer of PKCS12UserIdentityDiscovery. The init reads PKCS #12 Data from the file URL.

    Throws

    error if the URL is not readable

    Declaration

    Swift

    public convenience init(fileURL: URL, passphrase: String) throws

    Parameters

    fileURL

    file URL of the PKCS #12 file

    passphrase

    String to open the PKCS #12 Data

  • Initializer of PKCS12UserIdentityDiscovery.

    Declaration

    Swift

    public init(data: Data, passphrase: String)

    Parameters

    data

    Data that contains the PKCS #12 data

  • Obtain the user identity.

    Declaration

    Swift

    public func obtainUserIdentity(completionHandler: @escaping (Data?, Error?) -> Void)

    Parameters

    completionHandler

    Result with Data and Error. The Data is the PKCS #12 formatted SecIdentity.