iOS SDK

SecCom-iSDK是一套提供了穿透SAG、支持SSO认证、数据库文件加解密和应用配置信息下发的应用程序接口。支持armv7、armv7s、arm64 处理器的设备，支持iOS 7.0以上的操作系统。SecCom-iSDK提供.framework形式的开发包(NSCiSDK.framework)。

本套SDK接口是提供给具有一定iOS编程经验和了解面向对象概念的读者使用。

1. SDK下载
2. SDK集成
2.1 引入Framework
2.2 引入头文件
2.3 设置授权码
2.4 处理openURL事件
3. API说明
3.1 设置授权码
3.2 SecCom授权
3.3 获取应用策略和应用配置信息
3.4 获取应用策略
3.5 应用策略变更
3.6 穿透SAG发送HTTPS请求
3.7 创建包含HTTPS请求的Tunnel Task
3.8 发送请求撤销请求
3.9 更改Tunnel Session参数配置
3.10 实现Tunnel Session Delegate
3.11 Secure Tunnel错误代码

1. SDK下载

下载SDK。

2. SDK集成

2.1 引入Framework

将 NSCiSDK.framework 拷贝到您的工程目录下或者合适的地方，在Linked Frameworks and Libraries 添加NSCiSDK.framework，如图：

引入Framework

在other linker Flags 加入-ObjC –lz –lsqlit3

加入objc

在Info.plist LSApplicationQueriesSchemes，添加UrlSchemesAppMdm的Item

添加appmdm

在info.plist中设置URL Types、NSCiSDK部分接口需要跳转到EMM客户端获取信息，其中URL Schemes 请修改为您要使用的URL Schemes，您需要在URL Types下添加Identifier为“NSC_SDK“的 URL Type。

urltypes设置

在使用穿透SAG(Proxy)时，请确定可以用以上方法获取到证书文件，您需要将emm_proxy_certificate.cer 拷贝到您的工程目录下，SDK使用的 [[NSBundle mainBundle] pathForResource:@”emm_proxy_certificate” ofType:@”cer”]; 方式读取的信息证书，将emm_proxy_certificate.cer 文件加入您的工程。

注：在使用穿透Proxy是、由于iOS9改用更安全的https，否则影响SDK的使用，请在”Info.plist”中进行配置，如果您使用了自签名证书为了能够在iOS9中正常使用。

APPTSS设置

2.2 引入头文件

引入头文件 #import <NSCiSDK/NSCiSDK.h>

2.3 设置授权码

用户在使用NSCiSDK之前需要获取授权码、您可以在EMM管理平台获取，这个授权码与应用的Bundle identifier相关联。在EMM管理平台登陆后，输入您应用使用的Bundle identifier，在“EMM SDK授权”一项中，点击生成授权码，点击：设置—管理平台—授权证书。您可以使用这个授权码启动NSCiSDK。

您可以在合适的地方初始NSCiSDK，相关代码如下：

//NSCiSDK授权
if (NSCPermissionStatus_OK != [NSCServices.sharedServices start:@"4699**************7fd57"]) {
    NSLog(@"SDK授权失败");
}

2.4 处理openURL事件

NSCiSDK部分接口需要从EMM Client获取SDK必要的信息，您需要在您工程的AppDelegate.m中的 – (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation 方法下添加以下代码：

//处理NSCiSDK openURL
if ([NSCServices.sharedServices.emmHandler handleOpenURL:url sourceApplication:sourceApplication]) {
    return YES;
}
//处理您应用自己的openURL

3. API说明

3.1 设置授权码

您需要使用正确NSCiSDK的授权码来启动NSCiSDK，只有使用正确的授权码进行认证成功后您才能使用NSCiSDK提供的服务。

a.类名：NSCServices

b.方法名：- (NSCPermissionStatus)start:(nonnull NSString *)appKey;

c.功能说明：启动NSCiSDK，设置授权码.

d.调用参数说明：

参数名	参数说明
Appkey	EMM SDK授权码，需要填写EMM 管理平台上生成的授权码，在设置—管理平台—授权证书下获取

e.对应的返回值：

参数名	参数说明
NSCPermissionStatus	SCPermissionStatus_OK 授权成功，NSCPermissionStatus_AppkeyInvalid授权码无效

3.2 SecCom授权

SecCom授权后才能够使用穿透 SAG (Proxy)和SSO功能，请更具您的业务需要选择是否获取SecCom授权。

调用SecCom授权将会跳转到EMM客户端进行授权操作。

a.类名：NSCEMMHandler

b.方法名：- (void)secComAuthorization;

c.功能说明：获取SecCom授权。

d.授权结果返回的代理方法：

– (void)nscEMMHandler:(nonnull NSCEMMHandler *)handler

platformAppConfig:(nullable NSString *)platformAppConfig

error:(nullable NSError *)error;

参数说明：

参数名	参数说明
Handler	NSCEMMHandler 实例, 授权是否成功调用handler.secComAuthorized方法
platformAppConfig	平台配置的应用信息
Error	错误信息

3.3 获取应用策略和应用配置信息

NSCiSDK提供了获取应用策略和应用配置信息的接口，使用此功能前您需要安装EMM iOS客户端。

3.4 获取应用策略

NSCiSDK提供获取应用配置策略的接口。应用配置策略是在EMM管理平台选择应用下发的时候选择的策略信息，这个接口在应用通过EMM下发并且成功安装的情况下生效。

a.类名：NSCEMMHandler

b.方法名：- (nullable NSDictionary *)appConfig;

c.功能说明：获取应用配置的策略信息。

3.5 应用策略变更

当应用策略发送变更，NSCiSDK会通知APP并将变更后的值通知给APP。

a.协议：NSCEMMHandlerDelegate

b.方法名：- (void)nscEMMHandler:(nonnull NSCEMMHandler *)handler

appConfigDidChange:(nullable NSDictionary *)appConfig;

c.功能说明：应用配置策略变更回调。

d.参数说明：

参数名	参数说明
handler	NSCEMMHandler 实例
appConfig	应用配置策略信息

3.6 穿透SAG发送HTTPS请求

Secure Tunnel API 是SecCom-iSDK中一组提供了穿透SAG (Proxy)的能力的API，Secure Tunnel API是参照iOS SDK中的NSURLSession/NSURLSessionDataTask设计的，目前Secure Tunnel仅支持发送HTTPS请求。

3.7 创建包含HTTPS请求的Tunnel Task

Secure Tunnel提供NSCTunnelSession，用于创建Tunnel Task。

a.类名：NSCTunnelSession

b1.方法名：+ (NSCTunnelSession *)sessionWithConfiguration:(NSCTunnelSessionConfiguration *)configuration delegate:(id<NSCTunnelSessionDelegate>)delegate;

c1.功能说明：创建Tunnel Session。

d1.参数说明：

参数名	参数说明
Configuration	Tunnel Session参数配置，可为nil
Delegate	Tunnel Session的delegate，可为nil

e1.返回值：已创建的Tunnel Session，若为nil则创建失败

b2.方法名：- (NSCTunnelTask *)taskWithRequest:(NSURLRequest *)request completion:(void(^)(NSData *data, NSHTTPURLResponse *response, NSError *error))completion;

c2.功能说明：创建包含HTTPS请求的Tunnel Task。

d2.参数说明：

参数名	参数说明
request	包含请求的URL, Headers, Body, 不可为nil
completion	请求完成时被调用, 不可为nil data — 服务器返回的数据 response — NSHTTPURLResponse对象，包含服务器返回的statusCode, Headers等 error — 若发送请求失败，包含错误信息

参数名

参数说明

request

包含请求的URL, Headers, Body, 不可为nil

completion

请求完成时被调用, 不可为nil

data — 服务器返回的数据
response — NSHTTPURLResponse对象，包含服务器返回的statusCode, Headers等
error — 若发送请求失败，包含错误信息

e2.返回值：已创建的Tunnel Task，若为nil则创建失败

示例代码：

NSURL *url = [NSURL URLWithString:@"https://appserver.internal.net/sample"];
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:url];
urlRequest.HTTPMethod = @"GET";

// 应持有Tunnel Session直到Task完成
self.tunnelSession = [NSCTunnelSession sessionWithConfiguration:nil delegate:nil];
NSCTunnelTask *tunnelTask = [self.tunnelSession taskWithRequest:urlRequest completion:^(NSData *data, NSHTTPURLResponse *response, NSError *error) {
    NSLog(@"Got response: %@, body length: %lu", response, (unsigned long)data.length);
}];
[tunnelTask start];

3.8 发送请求撤销请求

Secure Tunnel提供NSCTunnelTask，用于发送或撤销HTTPS请求。

a.类名：NSCTunnelTask

b1. 方法名：- (void)start;

c1. 功能说明：启动Tunnel Task，发送HTTPS请求。

b2.方法名：- (void)cancel;

c2.功能说明：撤销Tunnel Task及HTTPS请求。

示例代码：

[tunnelTask start];

// Do something ... ...

[tunnelTask cancel];

3.9 更改Tunnel Session参数配置

Secure Tunnel提供NSCTunnelSessionConfiguration，作为配置Tunnel Session的参数。

a.类名：NSCTunnelSessionConfiguration

b.功能说明：配置Tunnel Session的参数。

c.属性说明：

参数名	参数说明
timeoutIntervalForRequest	设置Tunnel中发送请求的超时时长、则取60秒，若此值小于60秒。发送请求时。若此时长内没有数据传输，则请求失败。
TLSMinimumSupportedProtocol	与服务器SSL握手时，所支持的最低SSL协议版本，默认值为0（kSSLProtocolUnknown）
TLSMaximumSupportedProtocol	与服务器SSL握手时，所支持的最高SSL协议版本，默认值为0（kSSLProtocolUnknown）
HTTPAdditionalHeaders	为Tunnel中发送的请求添加额外的HTTP Headers，仅当请求中不包含某个Header时，这个Header才会被添加到请求中
validatesDomainName	在Tunnel中发送请求时。是否验证应用服务器证书的Common Name与服务器域名一致，默认值为YES
anchorCertificates	提供信任的证书列表，用于验证服务器证书。若提供了此列表，则內建的可信任证书将不会被用于服务器证书验证。

示例代码：

// 配置Additional Headers
NSMutableDictionary *additionalHeaders = [NSMutableDictionary dictionary];
[additionalHeaders setObject:@"application/json" forKey:@"content-type"];

// 配置信任的证书列表
NSString *path = [[NSBundle mainBundle] pathForResource:@"SampleCert" ofType:@"cer"];
NSData *certificateData = [NSData dataWithContentsOfFile:path];
NSArray *certificates = @[certificateData];

// 创建配置对象
NSCTunnelSessionConfiguration *configuration = [[NSCTunnelSessionConfiguration alloc] init];
configuration.HTTPAdditionalHeaders = additionalHeaders;
configuration.timeoutIntervalForRequest = 60 * 3;
configuration.anchorCertificates = certificates;

// 创建Tunnel Session
self.tunnelSession = [NSCTunnelSession sessionWithConfiguration:configuration delegate:nil];

3.10 实现Tunnel Session Delegate

Secure Tunnel提供NSCTunnelSessionDelegate。用于通知App在Secure Tunnel中发生的事件，如Auth Challenge等。

a.类名：NSCTunnelSessionDelegate

b.方法名：- (void)tunnelSession:(NSCTunnelSession *)session task:(NSCTunnelTask *)task didReceiveChallengeWithAuthMethod:(NSString *)authMethod completionHandler:(void (^)(BOOL useAuthString, NSString *authorizationString))completionHandler;

c.功能说明：通知App，某Tunnel Task收到了来自服务器的Auth Challenge。

d.参数说明：

参数名	参数说明
session	此Tunnel Session中的Task收到了Auth Challenge
task	收到Auth Challenge的Tunnel Task
authMethod	Auth Challenge的方法，如: NTLM, Negotiate等
completionHandler	Auth Challenge处理完成后，delegate必须调用此方法，否则造成内存泄漏 useAuthString — YES 已处理Auth Challenge, NO 未处理Auth Challenge authorizationString — 身份验证字符串，当 useAuthString == YES 时，必须提供

示例代码：

@interface NSCCredentialProvider : NSObject <NSCTunnelSessionDelegate>
@end

@implementation NSCCredentialProvider
- (void)tunnelSession:(NSCTunnelSession *)session task:(NSCTunnelTask *)task didReceiveChallengeWithAuthMethod:(NSString *)authMethod completionHandler:(void (^)(BOOL, NSString *))completionHandler {
    
    if ([authMethod hasPrefix:@"Basic"]) {
        
        NSString *credentailString = [NSString stringWithFormat:@"%@:%@", @"The username", @"The password"];
        NSString *base64CredentialString = [[credentailString dataUsingEncoding:NSUTF8StringEncoding] base64EncodedStringWithOptions:0];
        NSString *basicAuthCredentials = [NSString stringWithFormat:@"Basic %@", base64CredentialString];
        completionHandler(YES, basicAuthCredentials);
    }
    else {
        completionHandler(NO, nil);
    }
}
@end

// ......

- (void)sampleMethod {

    // ......

    // 应持有delegate直到Tunnel Session被释放
    self.credentialProvider = [[NSCCredentialProvider alloc] init];
    self.tunnelSession = [NSCTunnelSession sessionWithConfiguration:nil delegate:self.credentialProvider];
    
    // ......
}

3.11 Secure Tunnel错误代码

Secure Tunnel的错误以NSError形式体现，随taskWithRequest:completion:方法completion块的error参数返回。

NSError.domain：kNSCTunnelErrorDomain

NSError.code: 见下表

错误名称	错误码	错误说明
NSCTunnelErrorNone	0	成功
NSCTunnelErrorInvalidParameter	-6501	发送给代理服务器的参数无效
NSCTunnelErrorInvalidVerb	-6502	发送给代理服务器的操作无效
NSCTunnelErrorCipher	-6503	代理服务器内部密码错误
NSCTunnelErrorPassTokenExpired	-6504	代理服务器Pass Token过期
NSCTunnelErrorGrantService	-6505	授权服务器内部错误
NSCTunnelErrorAuthFailed	-6521	代理服务器无法验证该请求
NSCTunnelErrorNoProxyCredential	-6522	创建Tunnel时，无代理服务器需要的验证信息
NSCTunnelErrorInvalidAppPassToken	-6531	发送给代理服务器的App Pass Token无效
NSCTunnelErrorResourceNotFound	-6532	未发现请求的资源
NSCTunnelErrorInvalidCredential	-6533	发送给代理服务器的验证信息无效
NSCTunnelErrorInternalServerError	-6551	代理服务器内部错误
NSCTunnelErrorServiceUnavailable	-6552	代理服务器服务不可用
NSCTunnelErrorUnknown	-6599	未知错误

EMM

SecCom SDK

安全容器

NPNS SDK

NPNS API

Restful API

iOS SDK

1. SDK下载

2. SDK集成

2.1 引入Framework

2.2 引入头文件

2.3 设置授权码

2.4 处理openURL事件

3. API说明

3.1 设置授权码

3.2 SecCom授权

3.3 获取应用策略和应用配置信息

3.4 获取应用策略

3.5 应用策略变更

3.6 穿透SAG发送HTTPS请求

3.7 创建包含HTTPS请求的Tunnel Task

3.8 发送请求撤销请求

3.9 更改Tunnel Session参数配置

3.10 实现Tunnel Session Delegate

3.11 Secure Tunnel错误代码

EMM

SecCom SDK

安全容器

NPNS SDK

NPNS API

Restful API

iOS SDK

1. SDK下载

2. SDK集成

2.1 引入Framework

2.2 引入头文件

2.3 设置授权码

2.4 处理openURL事件

3. API说明

3.1 设置授权码

3.2 SecCom授权

3.3 获取应用策略和应用配置信息

3.4 获取应用策略

3.5 应用策略变更

3.6 穿透SAG发送HTTPS请求

3.7 创建包含HTTPS请求的Tunnel Task

3.8 发送请求 撤销请求

3.9 更改Tunnel Session参数配置

3.10 实现Tunnel Session Delegate

3.11 Secure Tunnel错误代码

3.8 发送请求撤销请求