iOS/OS X-kodexempeliOS/OS X code examples

Viktigt

Versioner av Microsoft Rights Management Service SDK som lanserades före mars 2020 är inaktuella. program som använder tidigare versioner måste uppdateras för att använda versionen från mars 2020.Versions of the Microsoft Rights Management Service SDK released prior to March 2020 are deprecated; applications using earlier versions must be updated to use the March 2020 release. Fullständig information finns i utfasnings meddelandet.For full details, see the deprecation notice.

Inga ytterligare förbättringar planeras för Microsoft Rights Management Service SDK.No further enhancements are planned for the Microsoft Rights Management Service SDK. Vi rekommenderar starkt att du använder Microsoft Information Protection SDK för klassificering, märkning och skydds tjänster.We strongly recommend adoption of the Microsoft Information Protection SDK for classification, labeling, and protection services.

I det här avsnittet beskrivs viktiga kodelement för iOS/OS X-versionen av RMS SDK.This topic will introduce you to important code elements for the iOS/OS X version of the RMS SDK.

Obs! I exempelkoden och beskrivningarna som följer använder vi termen MSIPC (Microsoft Information Protection och Control) när vi refererar till klientprocessen.Note In the example code and descriptions that follow, we use the term MSIPC (Microsoft Information Protection and Control) to reference the client process.

Använda Microsoft Rights Management SDK 4.2 – nyckelscenarierUsing the Microsoft Rights Management SDK 4.2 - key scenarios

Följande är Objective C-kodexempel från ett större exempelprogram som representerar utvecklingsscenarier som är viktiga för din förståelse av detta SDK.Following are Objective C code examples from a larger sample application representing development scenarios important to your orientation to this SDK. Dessa demonstrerar användningen av formatet Microsoft-skyddad fil, här kallat skyddad fil, användningen av anpassade skyddade filformat och användningen av anpassade UI-kontroller.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.

Scenario: Använda en RMS-skyddad filScenario: Consume an RMS protected file

  • Steg 1: Skapa ett MSProtectedData-objektStep 1: Create an MSProtectedData object

    Beskrivning: Skapa en instans av ett MSProtectedData-objekt som implementerar tjänstautentisering med hjälp av MSAuthenticationCallback för att hämta en token genom att skicka en instans av MSAuthenticationCallback, som parametern authenticationCallback, till MSIPC-API:et.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. Se anropet till MSProtectedData protectedDataWithProtectedFile i följande avsnitt med exempelkod.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];
            }];
        }
    
  • Steg 2: Konfigurera autentisering med hjälp av ADAL (Active Directory Authentication Library).Step 2: Setup authentication using the Active Directory Authentication Library (ADAL).

    Beskrivning: I det här steget ser du hur ADAL används för att implementera ett MSAuthenticationCallback med exempelautentiseringsparametrar.Description: In this step you will see ADAL used to implement an MSAuthenticationCallback with example authentication parameters. Mer information om hur du använder ADAL finns i Azure AD Authentication Library (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);
                              }
                          }];
       }
    
  • Steg tre: Kontrollera om användaren har redigeringsbehörighet till detta innehåll via metoden MSUserPolicy accessCheck för ett MSUserPolicy-objekt.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: Skapa en ny skyddad fil med en mallScenario: Create a new protected file using a template

I det här scenariot börjar vi med att hämta en lista över mallar, MSTemplateDescriptor Vi väljer den första mallen för att skapa en princip och skapar och skriver sedan till den nya skyddade filen.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.

  • Steg 1: Hämta lista över mallarStep 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)
                                   }];
        }
    
  • Steg två: Skapa en MSUserPolicy med hjälp av den första mallen i listan.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)
            }];
        }
    
  • Steg tre: Skapa ett MSMutableProtectedData-objekt och skriv innehåll till det.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: Öppna en anpassad skyddad filScenario: Open a custom protected file

  • Steg ett: Skapa en MSUserPolicyfrån en serializedContentPolicy.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)
            {
    
            }];
         }
    
  • Steg två: Skapa ett MSCustomProtectedData-objekt med hjälp av MSUserPolicy från Steg ett och läs från det.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: Skapa en anpassad skyddad fil med hjälp av en anpassad princip (ad hoc)Scenario: Create a custom protected file using a custom (ad-hoc) policy

  • Steg 1: Skapa en principbeskrivning med en e-postadress som anges av användaren.Step 1: With an email address provided by the user, create a policy descriptor.

    Beskrivning: I praktiken skapas följande objekt med användarindata från enhetsgränssnittet: MSUserRights och MSPolicyDescriptor.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;
        }
    
  • Steg 2: Skapa en anpassad MSUserPolicy från principbeskrivningen, selectedDescriptor.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)
            }];
        }
    
  • Steg 3: Skapa och skriv innehåll till MSMutableCustomProtectedData och stäng sedan.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];
    
            }];
          }