This document describes the procedure to connect to WAF SDK by using an iOS App.

Download the SDK package

Download and unzip the WAF SDK package. The following files are included in the sdk-iOS folder:

The description of these files is as follows:

Name Description
SGMain.framework Main framework SDK
SecurityGuardSDK.framework Basic security plugin
SGSecurityBody.framework Man/machine identification plugin
SGAVMP.framework Virtual machine plugin
yw_1222_0335_mwua.jpg Configuration file

Procedure

Follow these steps to configure a project:

  1. Add Framework. Add the four .framework files provided by WAF SDK to the project’s dependent libraries.

  2. Add link options.

  3. Add system dependent libraries.

  4. Import configuration file. Add the yw_1222_0335_mwua.jpg  configuration file of the SDK to mainbunle.

    When the application integrates multiple targets, make sure to add the yw_1222_0335_mwua.jpg configuration file to the correct Target Membership.

Coding process

1. Initialize SDK

Interface definition
+ (BOOL) initialize;
Interface description
  • Function: Initializes SDK.
  • Parameter: N/A.
  • Return value: BOOL type. YES if the initialization is successful, and NO if the initialization fails.
Call method
[JAQAVMPSignature initialize];
Sample code
static BOOL avmpInit = NO;
- (BOOL) initAVMP{
    @synchronized(self) { // just initialize once
        if(avmpInit == YES){
            return YES;
        }
        avmpInit = [JAQAVMPSignature initialize];
        return avmpInit;
    }
}

2. Sign the request data

Interface definition
+ (NSData*) avmpSign: (NSInteger) signType input: (NSData*) input;

Interface description

Use the avmp technology to sign the input data, and return the signature string.
Note The signed request body must be identical to the request body sent out from the client. For example, the encoding format, spaces, special characters, and order of parameters in the request bodies must be the same. Otherwise, the verification may fail.
Parameters:
Name Type Required Description
signType NSInteger Yes Algorithm used by the signature. Currently, it is a fixed value. Enter 3.
input NSData* No Data to be signed, which is generally the entire request body. If the request body is empty, then enter null for this parameter.

Return value: NSData* type. The signature string is returned.

Call method
[JAQAVMPSignature avmpSign: 3 input: request_body];

Sample code

When the client sends data to the server, it must call the avmpSign interface to sign the entire body data and obtain the signature string (the wToken).
# define VMP_SIGN_WITH_GENERAL_WUA2 (3)

- (NSString*) avmpSign{
    
    @synchronized(self) {
        NSString* request_body = @"i am the request body, encrypted or not!" ;  
        
        if(![ self initAVMP]){
            [self toast:@"Error: init failed"];
			            return nil;
        }
        
        NSString* wToken = nil;
        NSData* data = [request_body dataUsingEncoding:NSUTF8StringEncoding];
        NSData* sign = [JAQAVMPSignature avmpSign: VMP_SIGN_WITH_GENERAL_WUA2 input:data];
        if(sign == nil || sign.length <= 0){
            return nil;
        }else{
            wToken = [[NSString alloc] initWithData:sign encoding: NSUTF8StringEncoding];
            return wToken;
        }
    }
}
Note Even if the request body is empty, the client still must call the avmpSign interface to generate the wToken. In this case, directly import null as the second parameter. The sample code is as follows:
NSData* sign = [JAQAVMPSignature avmpSign: VMP_SIGN_WITH_GENERAL_WUA2 input:nil];

3. Put the wToken in the protocol header

The sample code is as follows:
#define VMP_SIGN_WITH_GENERAL_WUA2 (3)

-(void)setHeader
{
    NSString* request_body = @"i am the request body, encrypted or not!" ;  
    NSData* body_data = [request_body dataUsingEncoding:NSUTF8StringEncoding];

NSString* wToken = nil;
NSData* sign = [JAQAVMPSignature avmpSign: VMP_SIGN_WITH_GENERAL_WUA2 input:body_data];
    wToken = [[NSString alloc] initWithData:sign encoding: NSUTF8StringEncoding];
    NSString *strUrl = [NSString stringWithFormat:@"http://www.xxx.com/login"];
    NSURL *url = [NSURL URLWithString:strUrl];
    NSMutableURLRequest *request = 
        [[NSMutableURLRequest alloc]initWithURL:url cachePolicy:NSURLRequestReloadIgnoringCacheData timeoutInterval:20];

    [request setHTTPMethod:@"POST"];

    // set request body info
    [request setHTTPBody:body_data];

    // set wToken info to header
    [request setValue:wToken forHTTPHeaderField:@"wToken"];

    NSURLConnection *mConn = [[NSURLConnection alloc]initWithRequest:request delegate:self startImmediately:true];
    [mConn start];
    // ...
}

4. Send data to the server

Send the data with the modified protocol header to WAF. Upon receiving the request, WAF parses the wToken for risk identification, and then blocks malicious requests and forwards only the valid requests to the origin.

Error codes

The preceding initialize and avmpSign interfaces may encounter exceptions. If you encounter an exception or error when generating the signature string, you can search “SG Error” in the console.

Common errors and descriptions are listed in the following table:

Error Code Meaning
1901 Incorrect parameter. Enter the correct parameter.
1902 Image file error. It generally indicates that the apk signature used to retrieve the image file is inconsistent with the current application’s apk signature. Use the current application’s apk to generate the image file. In iOS, it may be caused by inconsistent BundleIDs.
1903 Incorrect image format.
1904 Upgrade to the latest images. AVMP signature function only supports v5 images.
1905 Unable to find the image file. Make sure that the yw_1222_0335_mwua.jpg image file is added into the project.
1906 byteCode corresponding to the AVMP signature is missing in the image. Check if the image is correct.
1907 Failed to initialize AVMP. Try again later.
1910 Invalid avmpInstance instance. Probable causes are:
  • InvokeAVMP is called after AVMPInstance is destroyed.
  • The image’s byteCode version does not match with that of the SDK.
1911 The encrypted image’s byteCode does not have the corresponding export function.
1912 AVMP call failed. Submit a ticket for further assistance.
1913 InvokeAVMP is called after AVMPInstance is destroyed.
1915 Insufficient AVMP memory. Try again later.
1996 Unknown error. Try again