Padrão de Chave ValetValet Key pattern

Utilize um token que conceda aos clientes acesso direto restrito a um recurso específico para descarregar a transferência de dados da aplicação.Use a token that provides clients with restricted direct access to a specific resource, in order to offload data transfer from the application. Esta ação é particularmente útil em aplicações que utilizam filas ou sistemas de armazenamento alojado na cloud e pode minimizar os custos e maximizar o desempenho e a escalabilidade.This is particularly useful in applications that use cloud-hosted storage systems or queues, and can minimize cost and maximize scalability and performance.

Contexto e problemaContext and problem

Muitas vezes, os programas cliente e os browsers têm de ler e escrever fluxos de dados ou ficheiros de e para o armazenamento de uma aplicação.Client programs and web browsers often need to read and write files or data streams to and from an application’s storage. Normalmente, a aplicação irá processar o movimento dos dados — ao obtê-los do armazenamento e ao transmitir em fluxo para o cliente ou ao ler o fluxo carregado a partir do cliente e ao armazená-lo no arquivo de dados.Typically, the application will handle the movement of the data — either by fetching it from storage and streaming it to the client, or by reading the uploaded stream from the client and storing it in the data store. No entanto, esta abordagem absorve recursos importantes, tais como a computação, a memória e a largura de banda.However, this approach absorbs valuable resources such as compute, memory, and bandwidth.

Os arquivos de dados têm a capacidade de processar o carregamento e a transferência de dados diretamente, sem que a aplicação realize qualquer processamento para mover estes dados.Data stores have the ability to handle upload and download of data directly, without requiring that the application perform any processing to move this data. No entanto, tal requer, normalmente, que o cliente tenha acesso às credenciais de segurança do arquivo.But, this typically requires the client to have access to the security credentials for the store. Tal pode ser uma técnica útil para minimizar os custos de transferência de dados e o requisito para aumentar horizontalmente a aplicação e para maximizar o desempenho.This can be a useful technique to minimize data transfer costs and the requirement to scale out the application, and to maximize performance. Significa, no entanto, que a aplicação já não é capaz de gerir a segurança dos dados.It means, though, that the application is no longer able to manage the security of the data. Depois de o cliente ter uma ligação ao arquivo de dados para proporcionar acesso direto, a aplicação não pode atuar como um controlador de chamadas.After the client has a connection to the data store for direct access, the application can't act as the gatekeeper. Este já não controla o processo e não pode impedir carregamentos ou transferências subsequentes do arquivo de dados.It's no longer in control of the process and can't prevent subsequent uploads or downloads from the data store.

Esta abordagem não é realista em sistemas distribuídos que precisem de servir clientes não fidedignos.This isn't a realistic approach in distributed systems that need to serve untrusted clients. Ao invés, as aplicações têm de ser capazes de controlar o acesso de forma segura aos dados de forma granular, mas ainda reduzir a carga no servidor ao configurar esta ligação e, em seguida, ao permitir que o cliente comunique diretamente com o arquivo de dados para realizar as operações de leitura ou escrita necessárias.Instead, applications must be able to securely control access to data in a granular way, but still reduce the load on the server by setting up this connection and then allowing the client to communicate directly with the data store to perform the required read or write operations.

SoluçãoSolution

Tem de resolver o problema do controlo do acesso a um arquivo de dados em que o arquivo não consiga gerir a autenticação e autorização de clientes.You need to resolve the problem of controlling access to a data store where the store can't manage authentication and authorization of clients. Uma solução típica é restringir o acesso à ligação pública do arquivo de dados e dar ao cliente uma chave ou um token que o arquivo de dados possa validar.One typical solution is to restrict access to the data store’s public connection and provide the client with a key or token that the data store can validate.

Geralmente, esta chave ou token é denominada uma chave valet.This key or token is usually referred to as a valet key. Concede acesso por tempo limitado a recursos específicos e permite apenas operações predefinidas como ler e escrever no armazenamento ou nas filas ou carregar e transferir num browser.It provides time-limited access to specific resources and allows only predefined operations such as reading and writing to storage or queues, or uploading and downloading in a web browser. As aplicações podem criar e emitir chaves valet para dispositivos cliente e browsers rápida e facilmente, permitindo que os clientes realizem as operações necessárias sem pedir que a aplicação lide diretamente com a transferência de dados.Applications can create and issue valet keys to client devices and web browsers quickly and easily, allowing clients to perform the required operations without requiring the application to directly handle the data transfer. Deste modo, remove a sobrecarga de processamento e o impacto no desempenho e escalabilidade da aplicação e do servidor.This removes the processing overhead, and the impact on performance and scalability, from the application and the server.

O cliente utiliza este token para aceder a um recurso específico no arquivo de dados apenas por um período específico e com restrições específicas nas permissões de acesso, conforme mostrado na figura.The client uses this token to access a specific resource in the data store for only a specific period, and with specific restrictions on access permissions, as shown in the figure. Após o período especificado, a chave fica inválida e não permite o acesso ao recurso.After the specified period, the key becomes invalid and won't allow access to the resource.

Figura 1 – Descrição geral do padrão

Também pode configurar uma chave que tenha outras dependências, tais como o âmbito dos dados.It's also possible to configure a key that has other dependencies, such as the scope of the data. Por exemplo, consoante as capacidades do arquivo de dados, a chave pode especificar uma tabela completa num arquivo de dados, ou apenas linhas específicas numa tabela.For example, depending on the data store capabilities, the key can specify a complete table in a data store, or only specific rows in a table. Nos sistemas de armazenamento na cloud, a chave pode especificar um contentor ou apenas um item específico num contentor.In cloud storage systems the key can specify a container, or just a specific item within a container.

A chave também pode ser invalidada pela aplicação.The key can also be invalidated by the application. Esta é uma abordagem útil se o cliente notificar o servidor que a operação de transferência de dados está concluída.This is a useful approach if the client notifies the server that the data transfer operation is complete. O servidor pode, em seguida, invalidar essa chave para impedir o acesso.The server can then invalidate that key to prevent further access.

A utilização deste padrão pode simplificar a gestão de acesso a recursos porque não há qualquer requisito para criar e autenticar um utilizador, conceder permissões e, em seguida, remover o utilizador novamente.Using this pattern can simplify managing access to resources because there's no requirement to create and authenticate a user, grant permissions, and then remove the user again. Também facilita limitar a localização e a permissão e o período de validade, bastando gerar uma chave no tempo de execução.It also makes it easy to limit the location, the permission, and the validity period—all by simply generating a key at runtime. Os fatores importantes são para limitar o máximo possível o período de validade e, especialmente, a localização do recurso, para que o destinatário possa apenas utilizá-lo para o objetivo pretendido.The important factors are to limit the validity period, and especially the location of the resource, as tightly as possible so that the recipient can only use it for the intended purpose.

Problemas e consideraçõesIssues and considerations

Na altura de decidir como implementar este padrão, considere os seguintes pontos:Consider the following points when deciding how to implement this pattern:

Gerir o estado e o período de validade da chave.Manage the validity status and period of the key. Se for divulgada ou estiver comprometida, a chave desbloqueia de forma eficaz o item de destino e disponibiliza-o para uma utilização maliciosa durante o período de validade.If leaked or compromised, the key effectively unlocks the target item and makes it available for malicious use during the validity period. Uma chave pode, normalmente, ser revogada ou desativada, dependendo de como foi emitida.A key can usually be revoked or disabled, depending on how it was issued. As políticas do lado do servidor podem ser alteradas ou a chave de servidor com a qual foram assinadas pode ser invalidada.Server-side policies can be changed or, the server key it was signed with can be invalidated. Especifique um período de validade curto para minimizar o risco de permitir que ocorram operações não autorizadas no arquivo de dados.Specify a short validity period to minimize the risk of allowing unauthorized operations to take place against the data store. No entanto, se o período de validade for demasiado curto, o cliente poderá não conseguir concluir a operação antes de a chave expirar.However, if the validity period is too short, the client might not be able to complete the operation before the key expires. Permita que os utilizadores autorizados renovem a chave antes de o período de validade expirar se forem precisos vários acessos ao recurso protegido.Allow authorized users to renew the key before the validity period expires if multiple accesses to the protected resource are required.

Controlar o nível de acesso que a chave concede.Control the level of access the key will provide. Normalmente, a chave deve permitir que o utilizador execute apenas as ações necessárias para concluir a operação, como o acesso só de leitura se o cliente não conseguir carregar dados para o arquivo de dados.Typically, the key should allow the user to only perform the actions necessary to complete the operation, such as read-only access if the client shouldn't be able to upload data to the data store. Para carregamentos de ficheiros, é comum especificar uma chave que conceda a permissão só de escrita, bem como a localização e o período de validade.For file uploads, it's common to specify a key that provides write-only permission, as well as the location and the validity period. É fundamental especificar com precisão o recurso ou o conjunto de recursos aos quais a chave se aplica.It's critical to accurately specify the resource or the set of resources to which the key applies.

Considerar a forma de controlar o comportamento dos utilizadores.Consider how to control users’ behavior. A implementação deste padrão significa alguma perda de controlo sobre os recursos aos quais é concedido acesso aos utilizadores.Implementing this pattern means some loss of control over the resources users are granted access to. O nível de controlo que pode ser exercido é limitado pelas capacidades das políticas e permissões disponíveis para o serviço ou o arquivo de dados de destino.The level of control that can be exerted is limited by the capabilities of the policies and permissions available for the service or the target data store. Por exemplo, normalmente, não pode criar uma chave que limite o tamanho dos dados a ser escritos no armazenamento ou o número de vezes que a chave pode ser utilizada para aceder a um ficheiro.For example, it's usually not possible to create a key that limits the size of the data to be written to storage, or the number of times the key can be used to access a file. Tal pode resultar em grandes custos inesperados para a transferência de dados, mesmo em caso de utilização pelo cliente pretendido, e pode ser causado por um erro no código que resulta em carregamentos ou transferências repetidos.This can result in huge unexpected costs for data transfer, even when used by the intended client, and might be caused by an error in the code that causes repeated upload or download. Para limitar o número de vezes que um ficheiro pode ser carregado, sempre que possível, force o cliente a notificar a aplicação quando uma operação é concluída.To limit the number of times a file can be uploaded, where possible, force the client to notify the application when one operation has completed. Por exemplo, alguns arquivos de dados geram eventos que o código da aplicação pode utilizar para monitorizar as operações e controlar o comportamento do utilizador.For example, some data stores raise events the application code can use to monitor operations and control user behavior. No entanto, é difícil de impor quotas para utilizadores individuais num cenário com vários inquilinos em que a mesma chave é utilizada por todos os utilizadores de um inquilino.However, it's hard to enforce quotas for individual users in a multi-tenant scenario where the same key is used by all the users from one tenant.

Validar e, opcionalmente, limpar todos os dados carregados.Validate, and optionally sanitize, all uploaded data. Um utilizador malicioso que obtenha acesso à chave pode carregar dados concebidos para comprometer o sistema.A malicious user that gains access to the key could upload data designed to compromise the system. Em alternativa, os utilizadores autorizados podem carregar dados inválidos e, quando processados, podem resultar num erro ou numa falha de sistema.Alternatively, authorized users might upload data that's invalid and, when processed, could result in an error or system failure. Para impedir esta situação, garanta que todos os dados carregados são validados e verificados relativamente ao conteúdo malicioso antes da utilização.To protect against this, ensure that all uploaded data is validated and checked for malicious content before use.

Auditar todas as operações.Audit all operations. Vários mecanismos baseados em chaves podem registar operações como carregamentos, transferências e falhas.Many key-based mechanisms can log operations such as uploads, downloads, and failures. Estes registos poderão, normalmente, ser incorporados num processo de auditoria e ser utilizados para a faturação se for cobrado um valor ao utilizador com base no volume de dados ou no tamanho do ficheiro.These logs can usually be incorporated into an audit process, and also used for billing if the user is charged based on file size or data volume. Utilize os registos para detetar falhas de autenticação que podem ser causadas por problemas com o fornecedor de chave ou por uma remoção acidental de uma política de acesso armazenado.Use the logs to detect authentication failures that might be caused by issues with the key provider, or accidental removal of a stored access policy.

Enviar a chave de forma segura.Deliver the key securely. Pode ser incorporada num URL que o utilizador ativa numa página Web ou pode ser utilizada numa operação de redirecionamento do servidor para que a transferência ocorra automaticamente.It can be embedded in a URL that the user activates in a web page, or it can be used in a server redirection operation so that the download occurs automatically. Utilize sempre HTTPS para enviar a chave através de um canal seguro.Always use HTTPS to deliver the key over a secure channel.

Proteger os dados confidenciais em trânsito.Protect sensitive data in transit. O envio de dados confidenciais através da aplicação ocorre, normalmente, através de SSL ou TLS e este meio deve ser imposto aos clientes que acedem diretamente ao arquivo de dados.Sensitive data delivered through the application will usually take place using SSL or TLS, and this should be enforced for clients accessing the data store directly.

Outros problemas a ter em consideração ao implementar este padrão:Other issues to be aware of when implementing this pattern are:

  • Se o cliente não notificar ou não conseguir notificar o servidor quanto à conclusão da operação e o único limite for o período de expiração da chave, a aplicação não conseguirá realizar operações de auditorias como a contagem do número de carregamentos ou de transferências, nem impedir vários carregamentos ou transferências.If the client doesn't, or can't, notify the server of completion of the operation, and the only limit is the expiration period of the key, the application won't be able to perform auditing operations such as counting the number of uploads or downloads, or preventing multiple uploads or downloads.

  • A flexibilidade das políticas de chaves que podem ser geradas poderá ser limitada.The flexibility of key policies that can be generated might be limited. Por exemplo, alguns mecanismos permitem apenas a utilização de um período de expiração limitado.For example, some mechanisms only allow the use of a timed expiration period. Outros mecanismos não são capazes de especificar uma granularidade suficiente de permissões de leitura/escrita.Others aren't able to specify a sufficient granularity of read/write permissions.

  • Se a hora de início da chave ou o período de validade do token for especificado, garanta que é um pouco anterior à hora atual do servidor para permitir os relógios cliente que poderão estar ligeiramente fora de sincronização.If the start time for the key or token validity period is specified, ensure that it's a little earlier than the current server time to allow for client clocks that might be slightly out of synchronization. Por predefinição, se não for especificada, é, normalmente, a hora atual do servidor.The default, if not specified, is usually the current server time.

  • O URL que contém a chave será registado nos ficheiros de registo do servidor.The URL containing the key will be recorded in server log files. Geralmente, a chave terá expirado antes de os ficheiros de registo serem utilizados para análise e garanta que limita o acesso aos mesmos.While the key will typically have expired before the log files are used for analysis, ensure that you limit access to them. Se os dados de registo forem transmitidos a um sistema de monitorização ou armazenados noutra localização, pondere implementar um atraso para evitar a fuga de chaves até após o período de validade expirar.If log data is transmitted to a monitoring system or stored in another location, consider implementing a delay to prevent leakage of keys until after their validity period has expired.

  • Se o código de cliente for executado num browser, o browser poderá ter de suportar a partilha de recursos de várias origens (CORS) para ativar o código que é executado num browser para aceder a dados num domínio diferente do que executou a página.If the client code runs in a web browser, the browser might need to support cross-origin resource sharing (CORS) to enable code that executes within the web browser to access data in a different domain from the one that served the page. Alguns browsers mais antigos e alguns arquivos de dados não suportam o CORS e o código que é executado nestes browsers pode conseguir utilizar uma chave valet para conceder acesso aos dados num domínio diferente, tal como uma conta de armazenamento na cloud.Some older browsers and some data stores don't support CORS, and code that runs in these browsers might be able to use a valet key to provide access to data in a different domain, such as a cloud storage account.

Quando utilizar este padrãoWhen to use this pattern

Este padrão é útil nas seguintes situações:This pattern is useful for the following situations:

  • Para minimizar o carregamento de recursos e maximizar o desempenho e a escalabilidade.To minimize resource loading and maximize performance and scalability. A utilização de uma chave valet não requer que o recurso seja bloqueado, não precisa de qualquer chamada de servidor remoto, não tem qualquer limite para o número de chaves valet que podem ser emitidas e evita um ponto único de falha provocado pela transferência de dados através do código da aplicação.Using a valet key doesn't require the resource to be locked, no remote server call is required, there's no limit on the number of valet keys that can be issued, and it avoids a single point of failure resulting from performing the data transfer through the application code. Criar uma chave valet é, normalmente, uma operação criptográfica simples de assinar uma cadeia com uma chave.Creating a valet key is typically a simple cryptographic operation of signing a string with a key.

  • Para minimizar os custos operacionais.To minimize operational cost. Permitir o acesso direto a filas e arquivos é eficiente a nível de recursos e custos, pode resultar em menos percursos de ida e volta na rede e poderá permitir uma redução do número de recursos de computação necessários.Enabling direct access to stores and queues is resource and cost efficient, can result in fewer network round trips, and might allow for a reduction in the number of compute resources required.

  • Quando os clientes carregam ou transferem dados regularmente, particularmente quando há um grande volume ou quando cada operação envolve ficheiros grandes.When clients regularly upload or download data, particularly where there's a large volume or when each operation involves large files.

  • Quando a aplicação tem recursos de computação disponíveis limitados, devido a limitações de alojamento ou considerações de custos.When the application has limited compute resources available, either due to hosting limitations or cost considerations. Neste cenário, o padrão será ainda mais útil se existirem muitos carregamentos ou transferências de dados em simultâneo porque liberta a aplicação do processamento de transferência de dados.In this scenario, the pattern is even more helpful if there are many concurrent data uploads or downloads because it relieves the application from handling the data transfer.

  • Quando os dados são armazenados num arquivo de dados remoto ou num datacenter diferente.When the data is stored in a remote data store or a different datacenter. Se a aplicação foi obrigada a atuar como um controlador de chamadas, poderá ser cobrada uma taxa pela largura de banda adicional da transferência de dados entre datacenters ou redes públicas ou privadas entre o cliente e a aplicação e, em seguida, entre a aplicação e o arquivo de dados.If the application was required to act as a gatekeeper, there might be a charge for the additional bandwidth of transferring the data between datacenters, or across public or private networks between the client and the application, and then between the application and the data store.

Este padrão pode não ser prático nas seguintes situações:This pattern might not be useful in the following situations:

  • Se a aplicação tiver de realizar algumas tarefas nos dados antes de serem armazenados ou de serem enviados para o cliente.If the application must perform some task on the data before it's stored or before it's sent to the client. Por exemplo, se a aplicação tiver de realizar a validação, registar o acesso com êxito ou executar uma transformação nos dados.For example, if the application needs to perform validation, log access success, or execute a transformation on the data. No entanto, alguns arquivos de dados e clientes conseguem negociar e realizar transformações simples, tais como a compressão e a descompressão (por exemplo, um browser pode normalmente processar formatos GZip).However, some data stores and clients are able to negotiate and carry out simple transformations such as compression and decompression (for example, a web browser can usually handle GZip formats).

  • Se a conceção de uma aplicação existente dificultar a incorporação do padrão.If the design of an existing application makes it difficult to incorporate the pattern. Normalmente, este padrão requer uma abordagem arquitetónica diferente para a entrega e a receção de dados.Using this pattern typically requires a different architectural approach for delivering and receiving data.

  • Se for necessário manter os registos de auditoria ou controlar o número de vezes que uma operação de transferência de dados é executada e o mecanismo de chave valet em utilização não suportar notificações que o servidor pode utilizar para gerir estas operações.If it's necessary to maintain audit trails or control the number of times a data transfer operation is executed, and the valet key mechanism in use doesn't support notifications that the server can use to manage these operations.

  • Se for necessário limitar o tamanho dos dados, especialmente durante as operações de carregamento.If it's necessary to limit the size of the data, especially during upload operations. A única solução passa pela aplicação verificar o tamanho de dados depois de concluída a operação ou verificar o tamanho dos carregamentos após um período de tempo especificado ou de forma agendada.The only solution to this is for the application to check the data size after the operation is complete, or check the size of uploads after a specified period or on a scheduled basis.

ExemploExample

O Azure suporta assinaturas de acesso partilhado no Armazenamento do Azure para o controlo do acesso granular aos dados em blobs, tabelas e filas e para tópicos e filas do Service Bus.Azure supports shared access signatures on Azure Storage for granular access control to data in blobs, tables, and queues, and for Service Bus queues and topics. Pode ser configurado um token de assinatura de acesso partilhado para conceder direitos de acesso específicos, tais como a leitura, escrita, atualização e eliminação de uma tabela específica; um intervalo de chaves numa tabela; uma fila; um blob; ou um contentor de blobs.A shared access signature token can be configured to provide specific access rights such as read, write, update, and delete to a specific table; a key range within a table; a queue; a blob; or a blob container. A validade pode ser um período de tempo especificado ou não ter limite de tempo.The validity can be a specified time period or with no time limit.

As assinaturas de acesso partilhado do Azure também suportam políticas de acesso armazenadas no servidor que podem ser associadas a um recurso específico, como uma tabela ou um blob.Azure shared access signatures also support server-stored access policies that can be associated with a specific resource such as a table or blob. Esta funcionalidade proporciona controlo adicional e flexibilidade em comparação com os tokens de assinatura de acesso partilhado gerados por aplicações e deve ser utilizada sempre que possível.This feature provides additional control and flexibility compared to application-generated shared access signature tokens, and should be used whenever possible. As definições configuradas numa política armazenada no servidor podem ser alteradas e são refletidas no token sem ser preciso emitir um novo token, mas as definições configuradas no token não podem ser alteradas sem emitir um novo token.Settings defined in a server-stored policy can be changed and are reflected in the token without requiring a new token to be issued, but settings defined in the token can't be changed without issuing a new token. Esta abordagem também torna possível revogar um token de assinatura de acesso partilhado válido antes de o mesmo expirar.This approach also makes it possible to revoke a valid shared access signature token before it's expired.

Para obter mais informações, veja Introducing Table SAS (Shared Access Signature), Queue SAS and update to Blob SAS (Apresentação da Tabela SAS (Assinatura de Acesso Partilhado), da SAS da Fila e da atualização da SAS do Blob) e Utilizar Assinaturas de Acesso Partilhado no MSDN.For more information see Introducing Table SAS (Shared Access Signature), Queue SAS and update to Blob SAS and Using Shared Access Signatures on MSDN.

O código seguinte mostra como criar um token de assinatura de acesso partilhado que é válido durante cinco minutos.The following code shows how to create a shared access signature token that's valid for five minutes. O método GetSharedAccessReferenceForUpload devolve um token de assinaturas de acesso partilhado que pode ser utilizado para carregar um ficheiro para o Armazenamento de Blobs do Azure.The GetSharedAccessReferenceForUpload method returns a shared access signatures token that can be used to upload a file to Azure Blob Storage.

public class ValuesController : ApiController
{
  private readonly CloudStorageAccount account;
  private readonly string blobContainer;
  ...
  /// <summary>
  /// Return a limited access key that allows the caller to upload a file
  /// to this specific destination for a defined period of time.
  /// </summary>
  private StorageEntitySas GetSharedAccessReferenceForUpload(string blobName)
  {
    var blobClient = this.account.CreateCloudBlobClient();
    var container = blobClient.GetContainerReference(this.blobContainer);

    var blob = container.GetBlockBlobReference(blobName);

    var policy = new SharedAccessBlobPolicy
    {
      Permissions = SharedAccessBlobPermissions.Write,

      // Specify a start time five minutes earlier to allow for client clock skew.
      SharedAccessStartTime = DateTime.UtcNow.AddMinutes(-5),

      // Specify a validity period of five minutes starting from now.
      SharedAccessExpiryTime = DateTime.UtcNow.AddMinutes(5)
    };

    // Create the signature.
    var sas = blob.GetSharedAccessSignature(policy);

    return new StorageEntitySas
    {
      BlobUri = blob.Uri,
      Credentials = sas,
      Name = blobName
    };
  }

  public struct StorageEntitySas
  {
    public string Credentials;
    public Uri BlobUri;
    public string Name;
  }
}

O exemplo completo está disponível na solução ValetKey disponível para transferência a partir do GitHub.The complete sample is available in the ValetKey solution available for download from GitHub. O projeto ValetKey.Web nesta solução contém uma aplicação Web que inclui a classe ValuesController mostrada acima.The ValetKey.Web project in this solution contains a web application that includes the ValuesController class shown above. Um exemplo de aplicação de cliente que utiliza esta aplicação Web para obter uma chave de assinaturas de acesso partilhado e carregar um ficheiro para o armazenamento de blobs está disponível no projeto ValetKey.Client.A sample client application that uses this web application to retrieve a shared access signatures key and upload a file to blob storage is available in the ValetKey.Client project.

Passos SeguintesNext steps

Os padrões e orientações que se seguem também podem ser relevantes ao implementar este padrão:The following patterns and guidance might also be relevant when implementing this pattern: