Codebeispiele für iOS/OS XiOS/OS X code examples

Wichtig

Versionen des Microsoft Rights Management Service SDK, die vor dem 2020 von März veröffentlicht wurden, sind veraltet. Anwendungen, die frühere Versionen verwenden, müssen aktualisiert werden, um die Version vom März 2020 zu verwenden.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. Ausführliche Informationen finden Sie im Hinweis zur Veraltung.For full details, see the deprecation notice.

Für das Microsoft Rights Management Service SDK sind keine weiteren Erweiterungen geplant.No further enhancements are planned for the Microsoft Rights Management Service SDK. Es wird dringend empfohlen, das Microsoft Information Protection SDK für Klassifizierungen, Bezeichnungen und Schutzdienste zu erhalten.We strongly recommend adoption of the Microsoft Information Protection SDK for classification, labeling, and protection services.

In diesem Thema werden wichtige Codeelemente der iOS/OS X-Version des RMS SDK vorgestellt.This topic will introduce you to important code elements for the iOS/OS X version of the RMS SDK.

Hinweis: Im Beispielcode und in den nachfolgenden Beschreibungen verwenden wir den Begriff MSIPC (Microsoft Information Protection und Steuerelement) zur Bezeichnung des Clientprozesses.Note In the example code and descriptions that follow, we use the term MSIPC (Microsoft Information Protection and Control) to reference the client process.

Verwenden von Microsoft Rights Management SDK 4.2 – SchlüsselszenarienUsing the Microsoft Rights Management SDK 4.2 - key scenarios

Es folgen Codebeispiele für Objective C aus einer größeren Beispielanwendung, die für die Einführung in dieses SDK wichtig sind.Following are Objective C code examples from a larger sample application representing development scenarios important to your orientation to this SDK. Diese veranschaulichen die Verwendung des Microsoft Protected File-Dateiformats (geschützte Datei), benutzerdefinierter geschützter Dateiformate und benutzerdefinierter Benutzeroberflächen-Steuerelemente.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.

Szenario: Nutzen einer RMS-geschützten DateiScenario: Consume an RMS protected file

  • Schritt 1: Erstellen eines MSProtectedData-ObjektsStep 1: Create an MSProtectedData object

    Beschreibung: Instanziieren Sie ein MSProtectedData-Objekt mit dessen create-Methode. Diese Methode implementiert die Dienstauthentifizierung mit MSAuthenticationCallback, um durch die Übergabe einer Instanz von MSAuthenticationCallback als Parameter authenticationCallback an die MSIPC-API ein Token abzurufen.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. Den Aufruf von MSProtectedData protectedDataWithProtectedFile finden Sie im folgenden Beispielcodeabschnitt.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];
            }];
        }
    
  • Schritt 2: Einrichten der Authentifizierung mit der Active Directory-Authentifizierungsbibliothek (ADAL).Step 2: Setup authentication using the Active Directory Authentication Library (ADAL).

    Beschreibung: In diesem Schritt erfahren Sie, wie ADAL zum Implementieren von MSAuthenticationCallback mit Beispielauthentifizierungsparametern verwendet wird.Description: In this step you will see ADAL used to implement an MSAuthenticationCallback with example authentication parameters. Weitere Informationen zur Verwendung von ADAL finden Sie in der Azure AD-Authentifizierungsbibliothek (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);
                              }
                          }];
       }
    
  • Schritt 3: Überprüfen der Bearbeitungsrechte dieses Benutzers mit diesem Inhalt mithilfe der MSUserPolicy accessCheck-Methode eines MSUserPolicy-ObjektsStep 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;
          }
      }
    

Szenario: Erstellen einer neuen geschützten Datei mithilfe einer VorlageScenario: Create a new protected file using a template

In diesem Szenario wird zunächst eine Liste mit Vorlagen (MSTemplateDescriptor) abgerufen. Dabei wird die erste Vorlage zum Erstellen einer Richtlinie ausgewählt und anschließend die neue geschützte Datei erstellt und in diese geschrieben.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.

  • Schritt 1: Abrufen der Liste der VorlagenStep 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)
                                   }];
        }
    
  • Schritt 2: Erstellen eines MSUserPolicy-Objekts mit der ersten Vorlage in der ListeStep 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)
            }];
        }
    
  • Schritt 3: Erstellen eines MSMutableProtectedData-Objekts und Füllen des Objekts mit InhaltStep 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)
            }];
        }
    

Szenario: Öffnen einer benutzerdefinierten geschützten DateiScenario: Open a custom protected file

  • Schritt 1: Erstellen eines MSUserPolicy-Objekts aus einem serializedContentPolicy-ObjektStep 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)
            {
    
            }];
         }
    
  • Schritt 2: Erstellen Sie ein MSCustomProtectedData-Objekt mithilfe des MSUserPolicy-Objekts aus Schritt 1, und lesen Sie daraus.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);
            }];
         }
    

Szenario: Erstellen einer benutzerdefinierten geschützten Datei mit einer benutzerdefinierten (Ad-Hoc)-RichtlinieScenario: Create a custom protected file using a custom (ad-hoc) policy

  • Schritt 1: Erstellen einer Richtlinienbeschreibung mit einer vom Benutzer angegebenen E-Mail-Adresse.Step 1: With an email address provided by the user, create a policy descriptor.

    Beschreibung: In der Praxis würden die Objekte MSUserRights und MSPolicyDescriptor mithilfe von Benutzereingaben von der Geräteschnittstelle erstellt werden.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;
        }
    
  • Schritt 2: Erstellen eines benutzerdefinierten MSUserPolicy-Objekts aus der Richtlinienbeschreibung selectedDescriptorStep 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)
            }];
        }
    
  • Schritt 3: Erstellen und Füllen des MSMutableCustomProtectedData-Objekts mit Inhalt und anschließendes Schließen des ObjektsStep 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];
    
            }];
          }