Update documentation and version for release (#38)

* update documentation for release

* update podspec

* fix typos in documentation

Author: imakhalova

Changelog.md

@@ -1,13 +1,33 @@
 # YubiKit Changelog
 
+#### 3.1.0 (3.0.0 -> 3.1.0)
+
+- Raw commands service `YKFKeyRawCommandService` now allows to specify timeouts on each command using `YKFKeyCommandConfiguration` in case if user wants to speed up communication with YubiKey or getting timeouts on execution of specific command. 
+
+- Reduced default timeout between sending command to YubiKey and receiving response from YubiKey in order to be more performant over Lightning.
+
+- This SDK version now provides  `YKFKeyChallengeResponseService` which allows to calculate HMAC-SHA1 on pre-programmed YubiKey. Read more about usage of [Challenge-response](./docs/chr.md)
+
+- Added `YKFKeyMGMTService` which allows to check whether application is available on YubiKey. And can enable or disable interfaces/application on YubiKey (if they are available). Read more about usage of [management service](./docs/mgmt.md)
+
+- Fixes OATH credential parser for credentials that contain "\" or ":". 
+
+- Added `YKFKeyOATHService` method `selectOATHApplication` that provides response on selection of OATH applet. It contains firmware version which can be used as one of the methods to detect firmware version over NFC.
+
+- Improvements in YubiKitDemo application: U2F and FIDO2 in Other demo section now support NFC-Enabled YubiKeys.
+---
+
 #### 3.0.0 (3.0.0-Preview2 -> 3.0.0)
 
-- Improvements to NFC API: ability to cusomize NFC alert message at any point of time it's visible, an error in case if NFC session was closed without successful invalidation (including cancellation), allows to handle multiple tags during one open nfc session and do not close session if key was removed from NFC reader.
+- Improvements to NFC API: ability to customize NFC alert message at any point of time it's visible, an error in case if NFC session was closed without successful invalidation (including cancellation), allows to handle multiple tags during one open nfc session and do not close session if key was removed from NFC reader.
+
 - Added ability for application to subscribe for logger events and customize/create it's own logger (e.g. sent logs to the file)
+---
 
 #### 3.0.0-Preview2 [3.0.0-Preview1 -> 3.0.0-Preview2]
 
 - Adds support for OATH protocol over NFC on devices running iOS 13 or newer. Also wraps and simplifies raw APDU communication with NFC-Enabled YubiKeys.
+---
 
 #### 3.0.0-Preview1 [2.0.1 -> 3.0.0-Preview1]
 

README.md

@@ -34,7 +34,7 @@ Add YubiKit to your [Podfile](https://guides.cocoapods.org/using/the-podfile.htm
 ```ruby
 use_frameworks!
 
-pod 'YubiKit', '~> 3.0.0'
+pod 'YubiKit', '~> 3.1.0'
 
 ```
 If you want to have latest changes, replace the last line with:
@@ -45,13 +45,16 @@ pod 'YubiKit', :git => 'https://github.com/Yubico/yubikit-ios.git'
 
 ```
 
-Once YubiKit is added to your `Podfile`, run `pod install` and open the `*.xcworkspace` with Xcode.
+Once YubiKit is added to your `Podfile`, run `pod install` and open the `*.xcworkspace` with Xcode. 
 
-Continue SDK setup by skipping over `Manual Setup` to `Enable Custom Lightning Protocol`.
+Then import the YubiKit module and you can use it's classes and methods.
+```
+import YubiKit
+```
 
----
+Continue SDK setup by skipping over `Manual Setup` to `Enable Custom Lightning Protocol`.
 
-**[Manual Setup]**
+<details><summary><strong>Manual Setup</strong></summary><p>
 
 Download or Clone YubiKit SDK source
 1.  [Download](https://github.com/Yubico/yubikit-ios/releases/) the latest YubiKit SDK (.zip) to your desktop `or` 
@@ -81,7 +84,8 @@ Click + and add the ``libYubiKit.a``
 
 6. If your target project is written in Swift, you need to provide a bridge to the YubiKit library by adding ``#import <YubiKit/YubiKit.h>`` to your bridging header. If a bridging header does not exist within your project, you can add one by following this [documentation](https://developer.apple.com/library/content/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html).
 
-<details><summary><strong>Additional instructions</strong></summary><p>
+</details>
+
 ---
 
 **Enable Custom Lightning Protocol**
@@ -142,10 +146,9 @@ Open info.plist and add the following usage:
 'Privacy - Camera Usage Description' - "This application needs access to Camera for reading QR codes."
 
 </p>
-</details>
 
 ## Documentation
-YubiKit headers are documented and the documentation is available either by reading the header file or by using the QuickHelp from Xcode (Option + Click symbol). Use this documentation for a more detailed explanation of all the methods, properties, and parameters from the API. If you are interested in implementation details for a specific category like U2F, FIDO2, or OATH, checkout the [./docs](./docs/) section.
+YubiKit headers are documented and the documentation is available either by reading the header file or by using the QuickHelp from Xcode (Option + Click symbol). Use this documentation for a more detailed explanation of all the methods, properties, and parameters from the API. If you are interested in implementation details for a specific category like U2F, FIDO2, or OATH, check out the [./docs](./docs/) section.
 
 ## Using the Library
 
@@ -200,6 +203,8 @@ List of services is documented below with it's own specifics and samples:
 
 - [Challenge-response](./docs/chr.md) - Provides a method to use HMAC-SHA1 challenge-response.
 
+- [MGMT](./docs/mgmt.md) - Provides ability to enable or disable available application on YubiKey
+
 
 ## Customize the Library
 YubiKit allows customizing some of its behavior by using `YubiKitConfiguration` and `YubiKitExternalLocalization`.

YubiKit.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name     = 'YubiKit'
-  s.version  = '3.0.0'
+  s.version  = '3.1.0'
   s.license  = 'Apache 2.0'
   s.summary  = 'YubiKit is an iOS library provided by Yubico to interact with YubiKeys on iOS devices.'
   s.homepage = 'https://github.com/Yubico/yubikit-ios'

YubiKit/YubiKit.xcodeproj/project.pbxproj

@@ -10,6 +10,7 @@
 		811F91F023848D5E002158ED /* YKFKeyOATHCalculateAllRequest.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 95A4566F21777D0E00AD5A94 /* YKFKeyOATHCalculateAllRequest.h */; };
 		81311F3A23AAFA4A00765522 /* YKFKeyChallengeResponseService.m in Sources */ = {isa = PBXBuildFile; fileRef = 81311F3923AAFA4A00765522 /* YKFKeyChallengeResponseService.m */; };
 		813271EC240F265B0084E105 /* YKFKeyMGMTService.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 814813E923EA381F0003893B /* YKFKeyMGMTService.h */; };
+		813FF86E241C6E4D00F5CD1E /* YKFKeyCommandConfiguration.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 951446A221874CC2002BB3C5 /* YKFKeyCommandConfiguration.h */; };
 		814813CF23EA37F60003893B /* YKFMGMTReadAPDU.m in Sources */ = {isa = PBXBuildFile; fileRef = 814813C923EA37F60003893B /* YKFMGMTReadAPDU.m */; };
 		814813D023EA37F60003893B /* YKFSelectMGMTApplicationAPDU.m in Sources */ = {isa = PBXBuildFile; fileRef = 814813CA23EA37F60003893B /* YKFSelectMGMTApplicationAPDU.m */; };
 		814813D123EA37F60003893B /* YKFMGMTWriteAPDU.m in Sources */ = {isa = PBXBuildFile; fileRef = 814813CD23EA37F60003893B /* YKFMGMTWriteAPDU.m */; };
@@ -264,6 +265,7 @@
 			dstPath = "include/$(PRODUCT_NAME)";
 			dstSubfolderSpec = 16;
 			files = (
+				813FF86E241C6E4D00F5CD1E /* YKFKeyCommandConfiguration.h in CopyFiles */,
 				813271EC240F265B0084E105 /* YKFKeyMGMTService.h in CopyFiles */,
 				81FD3B99240488F6004C4FE9 /* YKFKeyVersion.h in CopyFiles */,
 				81F94D9123F4DF4400475A70 /* YKFMGMTInterfaceConfiguration.h in CopyFiles */,

YubiKitDemo/YubiKitDemo/UI/About/AboutViewController.swift

@@ -28,7 +28,7 @@ class AboutViewController: UIViewController {
 
         let appBundle = Bundle(for: AboutViewController.self)
 
-        let libraryVersion = "3.0.0"
+        let libraryVersion = "3.1.0"
         let appVersion = appBundle.object(forInfoDictionaryKey: "CFBundleShortVersionString")!
 
         frameworkVersionLabel.text = "Library version: \(libraryVersion)"

docs/chr.md

@@ -1,10 +1,10 @@
 ## Using the HMAC-SHA1 challenge response Service 
 
-This service usage is different from other service because it's not coming as part of list of serviced provided by YubiKitManager singleton, but it's using  `YKFKeyRawCommandService` in implementation to communicate with YubiKey. How to implement such service yourself using  `YKFKeyRawCommandService`  read [here](../docs/raw.md)
+This service usage is not coming as part of list of serviced provided by YubiKitManager singleton, but it's using  `YKFKeyRawCommandService` in implementation to communicate with YubiKey. How to implement such services yourself using  `YKFKeyRawCommandService`  read [here](../docs/raw.md)
 
-The `YKFKeyChallengeResponseService` provides a simple API for sending synchronous request that exchanges chellenge for response from YubiKey.
+The `YKFKeyChallengeResponseService` provides a simple API for sending asynchronous request that exchanges challenge for response from YubiKey.
 
-This method also requires to provide a slot on YubiKey (1 or 2). By default all YubiKeys are programmed to have OTP secret on 1st slot (which requires short touch of YubiKey), but it can be swapped/programmed to use 2nd slot (requires long touch). One slot can be used to keep OTP secret or challenge-respose secret and it's up to user which slot he would prefer to program for one feature or another.
+This method also requires to provide a slot on YubiKey (1 or 2). By default all YubiKeys are programmed to have OTP secret on 1st slot (which requires short touch of YubiKey), but it can be swapped/programmed to use 2nd slot (requires long touch). One slot can be used to keep OTP secret or challenge-response secret and it's up to user which slot he would prefer to program for one feature or another.
 
 ### Prerequisite
 

docs/mgmt.md

@@ -0,0 +1,66 @@
+## Using YubiKey Management Service 
+
+This `YKFKeyMGMTService`  is using  `YKFKeyRawCommandService`  to communicate with YubiKey. How to implement such service yourself using  `YKFKeyRawCommandService`  read [here](../docs/raw.md)
+
+The `YKFKeyMGMTService` provides 2 methods:
+1) reading request that provides you `YKFMGMTInterfaceConfiguration` YubiKey within reading response. 
+2) writing request that accepts the same  `YKFMGMTInterfaceConfiguration` with updated flags on properties that needs to be tweaked (enabled/disabled)
+
+##### Objective-C
+
+```objective-c
+ #import <YubiKit/YubiKit.h>
+  
+ ...
+ YKFKeyMGMTService *service = [[YKFKeyMGMTService alloc] init];
+ [service readConfigurationWithCompletion:^(YKFKeyMGMTReadConfigurationResponse *selectionResponse, NSError *error) {
+     if (error) {
+         // Handle the error
+         return;
+     }
+     YKFMGMTInterfaceConfiguration *configuration = selectionResponse.configuration;
+     
+     if([configuration isSupported:YKFMGMTApplicationTypeOTP overTransport:YKFMGMTTransportTypeNFC]) {
+        //if OTP/YubiKey/Challenge-response application is supported on the app
+     }
+     
+     if ([configuration isEnabled:YKFMGMTApplicationTypeOTP overTransport:YKFMGMTTransportTypeNFC]) {
+         //if OTP/YubiKey/Challenge-response application is enabled on the app
+     }
+     
+}];
+```    
+    
+##### Swift
+
+```swift
+let service = YKFKeyMGMTService()
+mgtmService.readConfiguration { [weak self] (response, error) in
+    guard let self = self else {
+        return
+    }
+    
+    if let error = error {
+        // Handle the error
+        return
+    }
+    
+    let configuration = response.configuration
+
+    ...
+    
+    configuration.setEnabled(true, application: .OTP, overTransport: .USB)
+    
+    mgtmService.write(self.configuration, reboot: true) { [weak self] error in
+        if let error = error {
+            // Handle the error
+            return
+        }
+        //successfully updated
+    }
+}
+```    
+
+If method is invoked when there is no connection with YubiKey than methods of this service will return an error. So it's delegated to user of APIs to make sure that YubiKey is plugged in or tapped over NFC reader when prompted. This can be reached by observing state properties of sessions that has been started by user: the `sessionState` property of `YKFAccessorySession` ( or `iso7816SessionState` property of `NFCSession`). If state is open it means that connection has been established.
+The example of such observer can be found in the Examples/Observers project group of YubiKitDemo project.
+