iOS SDK

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

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

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 Types下添加Identifier为“NSC_SDK“的 URL Type,其中URL Schemes 请修改为您要使用的URL Schemes。

urltypes设置

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

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

APPTSS设置

2.2 引入头文件

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

2.3 设置授权码

用户在使用NSCiSDK之前需要获取授权码,这个授权码与应用的Bundle identifier相关联,您可以在EMM管理平台获取。在EMM管理平台登陆后,点击:设置—管理平台—授权证书,在“EMM SDK授权”一项中,输入您应用使用的Bundle identifier,点击生成授权码。您可以使用这个授权码启动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 — 若发送请求失败,包含错误信息

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 未知错误