Exemplos de código de iOS/OS X
Importante
As versões do Microsoft Rights Management Service SDK lançadas antes de março de 2020 são depreciadas; as aplicações que utilizam versões anteriores devem ser atualizadas para utilizar a versão de março de 2020. Para mais detalhes, consulte o aviso de depreciação.
Não estão previstas mais melhorias para o Microsoft Rights Management Service SDK. Recomendamos vivamente a adoção do Proteção de Informações da Microsoft SDK para serviços de classificação, rotulagem e proteção.
Este tópico apresenta-lhe elementos de código importantes para a versão iOS/OS X do SDK RMS.
Nota No código de exemplo e descrições que se seguem, utilizamos o termo MSIPC (Proteção de Informações da Microsoft e Controlo) para fazer referência ao processo do cliente.
Utilizar o SDK Microsoft Rights Management 4.2 – cenários principais
Seguem-se exemplos de código do Objetivo C de uma aplicação de exemplo maior que representam cenários de desenvolvimento importantes para se orientar neste SDK. Estes demonstram a utilização do formato de Ficheiro Protegido da Microsoft referido como ficheiro protegido, a utilização de formatos de ficheiros protegidos personalizados e a utilização de controlos de IU personalizados.
Cenário: consumir um ficheiro de RMS protegido
Passo 1: criar um objeto MSProtectedData
Descrição: instanciar um objeto MSProtectedData através do respetivo método de criação que implementa o serviço de autenticação com o MSAuthenticationCallback para obter um token ao transferir uma instância de MSAuthenticationCallback, como o parâmetro authenticationCallback, para a API de MSIPC. Consulte a chamada para MSProtectedData protectedDataWithProtectedFile na secção de código de exemplo seguinte.
+ (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]; }]; }Passo 2: configurar a autenticação com a Active Directory Authentication Library (ADAL).
Descrição: neste passo, verá a ADAL utilizada para implementar um MSAuthenticationCallback com parâmetros de autenticação de exemplo. Para obter mais informações sobre a utilização da ADAL, consulte a 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); } }]; }Passo 3: verificar se o direito de Edição existe para este utilizador com estes conteúdos através do método MSUserPolicy accessCheck de um objeto MSUserPolicy.
- (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; } }
Cenário: criar um novo ficheiro protegido através de um modelo
Este cenário começa com a obtenção de uma lista de modelos, MSTemplateDescriptor, ao selecionar o primeiro para criar uma política e, em seguida, ao criar e escrever no novo ficheiro protegido.
Passo 1: obter lista de modelos
+ (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) }]; }Passo 2: criar um MSUserPolicy com o primeiro modelo na lista.
+ (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) }]; }Passo 3: criar um MSMutableProtectedData e escrever os conteúdos no mesmo.
+ (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) }]; }
Cenário: abrir um ficheiro protegido personalizado
Passo 1: criar um MSUserPolicy a partir de um 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) { }]; }Passo 2: criar um MSCustomProtectedData com o MSUserPolicy do Passo 1 e ler a partir do mesmo.
+ (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); }]; }
Cenário: criar um ficheiro protegido personalizado utilizando uma política personalizada (ad hoc)
Passo 1: com um endereço de e-mail fornecido pelo utilizador, crie um descritor de política.
Descrição: na prática, seria possível criar os seguintes objetos com entradas do utilizador a partir da interface do dispositivo; MSUserRights e 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; }Passo 2: criar um MSUserPolicy personalizado do descritor de política, 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) }]; }Passo 3: criar e escrever os conteúdos no MSMutableCustomProtectedData e fechar.
+ (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]; }]; }