iOS/OS X のコード例iOS/OS X code examples

このトピックでは、iOS/OS X バージョンの RMS SDK の重要なコード要素について説明します。This topic will introduce you to important code elements for the iOS/OS X version of the RMS SDK.

: 以下のコード例と説明では、クライアント プロセスを参照するために MSIPC (Microsoft Information Protection and Control) という用語を使用します。Note In the example code and descriptions that follow, we use the term MSIPC (Microsoft Information Protection and Control) to reference the client process.

Microsoft Rights Management SDK 4.2 の使用 - 主要なシナリオUsing the Microsoft Rights Management SDK 4.2 - key scenarios

この SDK を理解するうえで重要な開発シナリオを表す大規模なサンプル アプリケーションの Objective C コード例を次に示します。Following are Objective C code examples from a larger sample application representing development scenarios important to your orientation to this SDK. これらのコード例では、保護ファイルと呼ばれる Microsoft Protected File 形式の使用例、カスタム保護ファイル形式の使用例、およびカスタムの UI コントロールの使用例を示します。These demonstrate; use of Microsoft Protected File format referred to as protected file , use of custom protected file formats, and use of custom UI controls.

シナリオ:RMS 保護ファイルを使用するScenario: Consume an RMS protected file

  • 手順 1:MSProtectedData オブジェクトを作成します。Step 1: Create an MSProtectedData object

    説明: MSProtectedData オブジェクトを、その作成メソッドによりインスタンス化し、サービス認証を実装します。これには、MSAuthenticationCallback を使用し、MSAuthenticationCallback のインスタンスを、パラメーター authenticationCallback として MSIPC API に渡し、トークンを取得します。Description: Instantiate an MSProtectedData object, through its create method which implements service authentication using the MSAuthenticationCallback to get a token by passing an instance of MSAuthenticationCallback, as the parameter authenticationCallback, to the MSIPC API. 次のコード例セクションの MSProtectedData protectedDataWithProtectedFile の呼び出しを参照してください。See the call to MSProtectedData protectedDataWithProtectedFile in the following example code section.

      + (void)consumePtxtFile:(NSString *)path authenticationCallback:(id<MSAuthenticationCallback>)authenticationCallback
      {
          // userId can be provided as a hint for authentication
          [MSProtectedData protectedDataWithProtectedFile:path
                                               userId:nil
                               authenticationCallback:authenticationCallback
                                              options:Default
                                      completionBlock:^(MSProtectedData *data, NSError *error)
          {
              //Read the content from the ProtectedData, this will decrypt the data
              NSData *content = [data retrieveData];
          }];
      }
    
  • 手順 2: Active Directory 認証ライブラリ (ADAL) を使用して認証をセットアップします。Step 2: Setup authentication using the Active Directory Authentication Library (ADAL).

    説明: この手順では、例の認証パラメーターで MSAuthenticationCallback を実装するために ADAL が使用されています。Description: In this step you will see ADAL used to implement an MSAuthenticationCallback with example authentication parameters. ADAL の使用の詳細については、「Azure AD Authentication Library (ADAL) (Azure AD 認証ライブラリ (ADAL))」を参照してください。For more information on using ADAL, see the Azure AD Authentication Library (ADAL).

    // AuthenticationCallback holds the necessary information to retrieve an access token.
    @interface MsipcAuthenticationCallback : NSObject<MSAuthenticationCallback>
    
    @end
    
    @implementation MsipcAuthenticationCallback
    
    - (void)accessTokenWithAuthenticationParameters:
           (MSAuthenticationParameters *)authenticationParameters
                                  completionBlock:
           (void(^)(NSString *accessToken, NSError *error))completionBlock
    {
        ADAuthenticationError *error;
        ADAuthenticationContext* context = [
            ADAuthenticationContext authenticationContextWithAuthority:authenticationParameters.authority
                                                              error:&error
        ];
        NSString *appClientId = @”com.microsoft.sampleapp”;
        NSURL *redirectURI = [NSURL URLWithString:@"local://authorize"];
        // Retrieve token using ADAL
        [context acquireTokenWithResource:authenticationParameters.resource
                               clientId:appClientId
                            redirectUri:redirectURI
                                 userId:authenticationParameters.userId
                        completionBlock:^(ADAuthenticationResult *result) {
                            if (result.status != AD_SUCCEEDED)
                            {
                                NSLog(@"Auth Failed");
                                completionBlock(nil, result.error);
                            }
                            else
                            {
                                completionBlock(result.accessToken, result.error);
                            }
                        }];
     }
    
  • 手順 3: MSUserPolicy オブジェクトの MSUserPolicy accessCheck メソッドを呼び出して、このユーザーにこのコンテンツの編集権限があるかどうかを確認します。Step 3: Check if the Edit right exists for this user with this content via the MSUserPolicy accessCheck method of a MSUserPolicy object.

    - (void)accessCheckWithProtectedData:(MSProtectedData *)protectedData
    {
        //check if user has edit rights and apply enforcements
        if (!protectedData.userPolicy.accessCheck(EditableDocumentRights.Edit))
        {
            // enforce on the UI
            textEditor.focusableInTouchMode = NO;
            textEditor.focusable = NO;
            textEditor.enabled = NO;
        }
    }
    

シナリオ:テンプレートを使用して新しい保護ファイルを作成するScenario: Create a new protected file using a template

このシナリオは、初めにテンプレートの一覧 MSTemplateDescriptor を取得し、最初の 1 つを選択してポリシーを作成してから、新しい保護ファイルを作成して書き込みます。This scenario begins with getting a list of templates, MSTemplateDescriptor, selecting the first one to create a policy, then creating and writing to the new protected file.

  • 手順 1:テンプレートの一覧を取得します。Step 1: Get list of templates

    + (void)templateListUsageWithAuthenticationCallback:(id<MSAuthenticationCallback>)authenticationCallback
    {
        [MSTemplateDescriptor templateListWithUserId:@"user@domain.com"
                        authenticationCallback:authenticationCallback
                               completionBlock:^(NSArray/*MSTemplateDescriptor*/ *templates, NSError *error)
                               {
                                 // use templates array of MSTemplateDescriptor (Note: will be nil on error)
                               }];
    }
    
  • 手順 2: 一覧の最初のテンプレートを使用して MSUserPolicy を作成します。Step 2: Create a MSUserPolicy using the first template in the list.

    + (void)userPolicyCreationFromTemplateWithAuthenticationCallback:(id<MSAuthenticationCallback>)authenticationCallback
    {
        [MSUserPolicy userPolicyWithTemplateDescriptor:[templates objectAtIndex:0]
                                        userId:@"user@domain.com"
                                 signedAppData:nil
                        authenticationCallback:authenticationCallback
                                       options:None
                               completionBlock:^(MSUserPolicy *userPolicy, NSError *error)
        {
        // use userPolicy (Note: will be nil on error)
        }];
    }
    
  • 手順 3: MSMutableProtectedData を作成し、コンテンツを書き込みます。Step 3: Create a MSMutableProtectedData and write content to it.

    + (void)createPtxtWithUserPolicy:(MSUserPolicy *)userPolicy contentToProtect:(NSData *)contentToProtect
    {
        // create an MSMutableProtectedData to write content
        [contentToProtect protectedDataInFile:filePath
                    originalFileExtension:kDefaultTextFileExtension
                           withUserPolicy:userPolicy
                          completionBlock:^(MSMutableProtectedData *data, NSError *error)
        {
         // use data (Note: will be nil on error)
        }];
    }
    

シナリオ:カスタム保護ファイルを開くScenario: Open a custom protected file

  • 手順 1:serializedContentPolicy から MSUserPolicy を作成します。Step 1: Create a MSUserPolicy from a serializedContentPolicy.

    + (void)userPolicyWith:(NSData *)protectedData
    authenticationCallback:(id<MSAuthenticationCallback>)authenticationCallback
    {
        // Read header information from protectedData and extract the  PL
        /*-------------------------------------------
        | PL length | PL | ContetSizeLength |
        -------------------------------------------*/
        NSUInteger serializedPolicySize;
        NSMutableData *serializedPolicy;
        [protectedData getBytes:&serializedPolicySize length:sizeof(serializedPolicySize)];
        [protectedData getBytes:[serializedPolicy mutableBytes] length:serializedPolicySize];
    
        // Get the user policy , this is an async method as it hits the REST service
        // for content key and usage restrictions
        // userId provided as a hint for authentication
        [MSUserPolicy userPolicyWithSerializedPolicy:serializedPolicy
                                          userId:@"user@domain.com"
                          authenticationCallback:authenticationCallback
                                         options:Default
                                 completionBlock:^(MSUserPolicy *userPolicy,
                                                   NSError *error)
        {
    
        }];
     }
    
  • 手順 2: 手順 1MSUserPolicy を使用して MSCustomProtectedData を作成し、読み取りを行います。Step 2: Create a MSCustomProtectedData using the MSUserPolicy from Step 1 and read from it.

    + (void)customProtectedDataWith:(NSData *)protectedData
    {
        // Read header information from protectedData and extract the  protectedContentSize
        /*-------------------------------------------
        | PL length | PL | ContetSizeLength |
        -------------------------------------------*/
        NSUInteger protectedContentSize;
        [protectedData getBytes:&protectedContentSize
                     length:sizeof(protectedContentSize)];
    
        // Create the MSCustomProtector used for decrypting the content
        // The content start position is the header length
        [MSCustomProtectedData customProtectedDataWithPolicy:userPolicy
                                           protectedData:protectedData
                                    contentStartPosition:sizeof(NSUInteger) + serializedPolicySize
                                             contentSize:protectedContentSize
                                         completionBlock:^(MSCustomProtectedData *customProtector,
                                                           NSError *error)
        {
         //Read the content from the custom protector, this will decrypt the data
         NSData *content = [customProtector retrieveData];
         NSLog(@"%@", content);
        }];
     }
    

シナリオ:カスタム (アドホック) ポリシーを使用してカスタム保護ファイルを作成するScenario: Create a custom protected file using a custom (ad-hoc) policy

  • 手順 1:ユーザーが指定した電子メール アドレスを使用してポリシー記述子を作成するStep 1: With an email address provided by the user, create a policy descriptor.

    説明:実際には、次のオブジェクトは、デバイス インターフェイス MSUserRightsMSPolicyDescriptor からのユーザー入力を使用して作成されます。Description: In practice the following objects would be created by using user inputs from the device interface; MSUserRights and MSPolicyDescriptor.

    + (void)policyDescriptor
    {
        MSUserRights *userRights = [[MSUserRights alloc] initWithUsers:[NSArray arrayWithObjects: @"user1@domain.com", @"user2@domain.com", nil] rights:[MSEmailRights all]];
    
        MSPolicyDescriptor *policyDescriptor = [[MSPolicyDescriptor alloc] initWithUserRights:[NSArray arrayWithObjects:userRights, nil]];
        policyDescriptor.contentValidUntil = [[NSDate alloc] initWithTimeIntervalSinceNow:NSTimeIntervalSince1970 + 3600.0];
        policyDescriptor.offlineCacheLifetimeInDays = 10;
    }
    
  • 手順 2: ポリシー記述子 selectedDescriptor からカスタムの MSUserPolicy を作成します。Step 2: Create a custom MSUserPolicy from the policy descriptor, selectedDescriptor.

    + (void)userPolicyWithPolicyDescriptor:(MSPolicyDescriptor *)policyDescriptor
    {
        [MSUserPolicy userPolicyWithPolicyDescriptor:policyDescriptor
                                      userId:@"user@domain.com"
                      authenticationCallback:authenticationCallback
                                     options:None
                             completionBlock:^(MSUserPolicy *userPolicy, NSError *error)
        {
          // use userPolicy (Note: will be nil on error)
        }];
    }
    
  • 手順 3: MSMutableCustomProtectedData を作成してコンテンツを書き込み、閉じます。Step 3: Create and write content to the MSMutableCustomProtectedData and then close.

    + (void)mutableCustomProtectedData:(NSMutableData *)backingData policy:(MSUserPolicy *)policy contentToProtect:(NSString *)contentToProtect
    {
        //Get the serializedPolicy from a given policy
        NSData *serializedPolicy = [policy serializedPolicy];
    
        // Write header information to backing data including the PL
        // ------------------------------------
        // | PL length | PL | ContetSizeLength |
        // -------------------------------------
        NSUInteger serializedPolicyLength = [serializedPolicy length];
        [backingData appendData:[NSData dataWithBytes:&serializedPolicyLength length:sizeof(serializedPolicyLength)]];
        [backingData appendData:serializedPolicy];
        NSUInteger protectedContentLength = [MSCustomProtectedData getEncryptedContentLengthWithPolicy:policy contentLength:unprotectedData.length];
        [backingData appendData:[NSData dataWithBytes:&protectedContentLength length:sizeof(protectedContentLength)]];
    
        NSUInteger headerLength = sizeof(serializedPolicyLength) + serializedPolicyLength + sizeof(protectedContentLength);
    
        // Create the MSMutableCustomProtector used for encrypting content
        // The content start position is the current length of the backing data
        // The encryptedContentSize content size is 0 since there is no content yet
        [MSMutableCustomProtectedData customProtectorWithUserPolicy:policy
                                                    backingData:backingData
                                         protectedContentOffset:headerLength
                                                completionBlock:^(MSMutableCustomProtectedData *customProtector,
                                                                  NSError *error)
        {
            //Append data to the custom protector, this will encrypt the data and write it to the backing data
            [customProtector appendData:[contentToProtect dataUsingEncoding:NSUTF8StringEncoding] error:&error];
    
            //close the custom protector so it will flush and finalise encryption
            [customProtector close:&error];
    
        }];
      }