Pin

public final class Pin

Class that represents a PIN that protects smart card contents.

  • Returns the index of the PIN inside the card.

    Declaration

    Swift

    public func getIndex() -> Int

    Return Value

    the pin index.

  • Returns the associated token.

    Declaration

    Swift

    public func getToken() -> Token

    Return Value

    the parent token.

  • Returns the PIN label.

    Declaration

    Swift

    public func getLabel() -> String

    Return Value

    The PIN label or an empty string if the information is unavailable.

  • Returns if the PIN is initialized and ready to be used.

    Declaration

    Swift

    public func isInitialized() -> Bool

    Return Value

    true if the PIN has been initialized, false otherwise.

  • Returns if the PIN needs to be changed before use.

    Declaration

    Swift

    public func isToBeChanged() -> Bool

    Return Value

    true if the PIN needs to be changed before use, false otherwise.

  • Returns if the PIN is blocked.

    Declaration

    Swift

    public func isBlocked() -> Bool

    Return Value

    true if the PIN is blocked, false otherwise.

  • Returns if the PIN try counter is lower than the maximum (an unsuccessful verification attempt has been made).

    Declaration

    Swift

    public func isTryCountLow() -> Bool

    Return Value

    true if the PIN try counter is lower than the maximum, false otherwise.

  • Returns if the PIN try counter shows only one remaining attempt.

    Declaration

    Swift

    public func isLastTry() -> Bool

    Return Value

    true if the PIN try counter shows only one remaining attempt, false otherwise.

  • Returns if the PIN has been successfully verified (access to the private objects is granted).

    Declaration

    Swift

    public func isValidated() -> Bool

    Return Value

    true if the PIN has been successfully verified, false otherwise.

  • Returns the number of remaining tries for the PIN verification.

    Declaration

    Swift

    public func getRemainingTries() -> Int

    Return Value

    The number of remaining tries for the PIN verification or -1 if the information is unavailable.

  • Returns the number of maximum tries for the PIN verification.

    Declaration

    Swift

    public func getMaxTries() -> Int

    Return Value

    The number of maximum tries for the PIN verification or -1 if the information is unavailable.

  • Returns a bit field indicating availability of each PUK, with the LSB for 1st PUK. A bit at 1 indicates that the corresponding PUK is still available.

    Declaration

    Swift

    public func getPuksAvailable() -> Int

  • Returns a CredentialState object with the current token infos for the requestCredential(pinProperties:state:readerName:cardLabel:env:completionHandler:) function.

    Declaration

    Swift

    public func initCredentialState() -> CredentialState

  • Returns a NSDictionary which contains the credential properties for this PIN slot.

    The returned object is used in the requestCredential(pinProperties:state:readerName:cardLabel:env:completionHandler:) function in order to provide information that will be displayed in the PIN dialog.

    The returned NSDictionary has the following structure:

    • pinLabel: a String that represents the PIN label, can be obtained by using getLabel() function.

    • methods: a NSDictionary with the following attributes:

      • facialBio: true if the PIN supports the facial biometry process, false otherwise.
      • fingerBio: true if the PIN supports the fingerprint biometry process, false otherwise.

    Declaration

    Swift

    public func getCredentialProperties() -> NSDictionary

  • Verifies the PIN.

    Example:

    pin.login(value: "****") { error in
    if let error = error {
        print("login failed: " + error.localizedDescription)
    }
    else {
        // if login is succesfull you can get private key objects for instance
        token.getObjects(){ objects, error in
            if let error = error {
                print("error reason: " + error.localizedDescription)
            }
            else {
                // now `objects` contains also private keys
            }
        }
}

    Declaration

    Swift

    public func login(value: String?, completionHandler: @escaping (_ error: NSError?) -> Void)

    Parameters

    value

    The PIN value.
    completionHandler

    The completion handler to call when the login is complete. It takes the following parameter:

    • error NSError?: nil if the operation is completed successfully; otherwise an error encapsulates the reason of failure.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.

  • Verifies the PIN after getting CredentialValue object by using requestCredential(pinProperties:state:readerName:cardLabel:env:completionHandler:) function.

    Example:

    // getting first the `credential` object by using requestCredential function
pin.login(credential.?getValue()) { error in
    if let error = error{
        print("login failed: " + error.localizedDescription)
    }
    else {
        // if login is succesfull you can get private key objects for instance
        token.getObjects(){ objects, error in
            if let error = error {
                print("error reason: " + error.localizedDescription)
            }
            else {
                // now `objects` contains also private keys
            }
        }
}

    Declaration

    Swift

    public func login(value: CredentialValue?, completionHandler: @escaping (_ error: NSError?) -> Void)

    Parameters

    value
    completionHandler

    The completion handler to call when the login is complete. It takes the following parameter:

    • error NSError?: nil if the operation is completed successfully; otherwise an error encapsulates the reason of failure.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.

  • Reinitializes the PIN value (eventually unblocking it, if required). The operation can only be made against the user PIN, and requires the security officer PIN to be verified with loginSo(value:completionHandler:).

    Example:

    pinSO.loginSo(value: "********") { error in
    if let error = error {
        print("fail to login: " + error.localizedDescription)
    }
    else {
        pinUser.initPin("****") { error in
            if let error = error {
                print("fail to init pin : " + error.localizedDescription)
            }
            else {
                print("sucessfully init pin")
            }
        }
    }
}

    Declaration

    Swift

    public func initPin(newValue: String?, completionHandler: @escaping (_ error: NSError?) -> Void)

    Parameters

    newValue

    The new PIN value.
    completionHandler

    The completion handler to call when the init PIN is complete. It takes the following parameter:

    • error NSError?: nil if the operation is completed successfully; otherwise an error encapsulates the reason of failure.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.

  • Verifies the security officer (administrator or unblocking) PIN.

    Example:

    pinSO.loginSo(value: "********") { error in
    if let error = error {
        print("fail to login on SO user" + error.localizedDescription)
    }
    else {
        pinUser.initPin("****"){ error in
            if let error = error {
                print("fai to init pin : " + error.localizedDescription)
            }
            else {
                print("sucessfully init pin")
            }
        }
    }
}

    Declaration

    Swift

    public func loginSo(value: String?, completionHandler: @escaping (_ error: NSError?) -> Void)

    Parameters

    value

    The PIN value.
    completionHandler

    The completion handler to call when the login is complete. It takes the following parameter:

    • error NSError?: nil if the operation is completed successfully; otherwise an error encapsulates the reason of failure.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.

  • Changes the PIN value. The operation can only be made against the user PIN.

    Declaration

    Swift

    public func change(oldValue: String?, newValue: String?, completionHandler: @escaping (_ error: NSError?) -> Void)

    Parameters

    oldValue

    The old PIN value.
    newValue

    The new PIN value.
    completionHandler

    The completion handler to call when changing the PIN value is complete. It takes the following parameter:

    • error NSError?: nil if the operation is completed successfully; otherwise an error encapsulates the reason of failure.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.

  • Resets the verified status of the PIN.

    Declaration

    Swift

    public func logout(completionHandler: @escaping (_ error: NSError?) -> Void)

    Parameters

    completionHandler

    The completion handler to call when logout is complete. It takes the following parameter:

    • error NSError?: nil if the operation is completed successfully; otherwise an error encapsulates the reason of failure.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.

  • Gets the format constraints of the PIN as an Array of PinConstraint.

    See also

    PinConstraint

    Example :

    func checkPinMinLength(pin:Pin, pinValue: String) -> Bool {
    var isPinOk = false
    // make the call synchronous
    let group = DispatchGroup()
    group.enter()
    DispatchQueue.global(qos: .background).async {
        pin.getConstraints { constraints, error in
            if let constraints = constraints {
                for constraint in constraints {
                    // check if `pinValue` verifies this `constraint`
                }
            }
            else {
                print("fail to get constraints: " + error!.localizedDescription)
            }
        }
    }
    group.wait()
    return isPinOk
}

    Declaration

    Swift

    public func getConstraints(completionHandler: @escaping (_ constraints: Array<PinConstraint>?, _ error: NSError?) -> Void)

    Parameters

    completionHandler

    called as soon as we get the pin constraints. It takes the following parameters:

    • constraints Array<PinConstraint>?: An array of PinConstraint.
    • error NSError?: nil if the operation is completed successfully; otherwise an error encapsulates the reason of failure.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.

  • Opens a PIN dialog webview in order to enter PIN value or use facial biometry. It is then possible to perform a login operation with returned (encrypted) credential value.

    Example:

    let readerName: String = "..."; // or "null" to not display this information.
let cardLabel: String = "...";  // or "null" to not diplay this information.

let pinProperties: NSDictionary = ["pinLabel": "...",
    "methods": ["facialBio": false, "fingerBio": false]];

let state: CredentialState = CredentialState();

Pin.requestCredential(pinProperties: pinProperties, state: state, readerName: readerName, cardLabel: cardLabel,
    completionHandler: { credValue, error in
    pin.login(credential) {
        //...
    }
});

    Note

    PinDialog must be added in the contentView of the application in order to display the PIN dialog. The management of the PIN dialog is then automatic.

    Declaration

    Swift

    public static func requestCredential(
	pinProperties: NSDictionary,
	state: CredentialState,
	readerName: String?,
	cardLabel: String?,
	env: SCMEnvironment,
	completionHandler: @escaping (_ returnedData: CredentialValue?, _ error: NSError?) -> Void) -> Void

    Parameters

    pinProperties

    NSDictonnary representing the credential properties. See getCredentialProperties().
    state

    a credential state, see initCredentialState().
    readerName

    String value representing the reader used for reading token (NFC, Bluetooth, Lightning, …) set to nil otherwise. Can be found by using Token.getReader() method on parent token (getToken()).
    cardLabel

    String value representing the card label, set to nil otherwise. Can be found by using Token.getLabel() method on parent token.
    env

    the current SCMEnvironment to use.
    completionHandler

    The completion handler block to be called as soon as the credential has been set (PIN or Biometric). It takes the following parameters:

    • returnedData CredentialValue? credential value to pass in login(value:completionHandler:) method.
    • error NSError?: nil if the operation is completed successfully; otherwise an error that indicates why the PIN dialog display failed/has been dismissed.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.