Convidar um par para um grupo

Este tópico discute o processo de convidar um par para ingressar em um grupo de pares usando as APIs de Agrupamento de Pares.

Um grupo de pares requer credenciais válidas para participar. As credenciais são emitidas de fora de um grupo na forma de convites ou diretamente para membros dentro de um grupo quando são necessárias atualizações de credenciais.

Certificados de Membro do Grupo

Um grupo de pares é criado quando um aplicativo faz uma chamada para PeerGroupCreate.

Para participar de um grupo de pares, cada par deve ter uma identidade de par. Chame PeerEnumIdentities até que todas as identidades de pares definidas para o par sejam retornadas e selecione aquela que deve ser usada. Se uma identidade de par não existir, crie uma chamando PeerIdentityCreate.

Cada identidade de par é associada a um conjunto específico de credenciais que pode ser usado para provar a associação de grupo par ao se conectar, bem como ao publicar registros ou convidar membros adicionais. Essas credenciais são representadas como cadeias de certificados X.509 chamados GMC (Certificados de Associação de Grupo).

Para criar o GMC para uma identidade de par, primeiro você deve obter sua chave pública. Essa chave é obtida chamando PeerIdentityGetXML no potencial convidado e passando sua identidade de par. Essa função retorna um IDC (certificado codificado em base 64) que contém a chave pública RSA usada para criar o GMC para a identidade de par (entre outras coisas), encapsulado em um blob XML, no seguinte formato:

<PEERIDENTITYINFO VERSION="1.0">
     <IDC xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">
          <!-- Base-64 encoded certificate  -->
     </IDC>
</PEERIDENTITYINFO>

Essa cadeia de caracteres pode ser passada para PeerGroupCreateInvitation, que retorna um convite que contém o GMC para essa identidade de par. O convite deve ser passado para o convidado usando um processo diferente, como email, FTP ou um compartilhamento de arquivos seguro.

Como alternativa, o próprio IDC pode ser colocado em uma nova estrutura PEER_CREDENTIAL_INFO e passado para PeerGroupIssueCredentials, que também gera um convite.

Observe que os aplicativos não têm permissão para adicionar marcas dentro da marca PEERIDENTITYINFO ou modificar esse fragmento XML de qualquer forma. Os aplicativos têm permissão para incorporar esse fragmento XML em outros documentos XML, mas devem remover todos os XML específicos do aplicativo antes de passar esse fragmento para as funções PeerGroupCreateInvitation ou PeerGroupIssueCredentials .

Os GMCs membros são emitidos pelos administradores e pelo criador do grupo de pares. Os membros devem obter novos GMCs com tempos de vida estendidos de seus GMCs antes que o tempo de expiração tenha passado. O administrador do grupo de pares emite credenciais atualizadas chamando PeerGroupIssueCredentials com as credenciais existentes para esse par.

A estrutura PEER_CREDENTIAL_INFO contém os dados básicos no status de associação de um par, incluindo a chave pública para o GMC. As credenciais recém-emitidas podem ser publicadas no grupo de pares definindo o sinalizador PEER_GROUP_STORE_CREDENTIALS na chamada para PeerGroupIssueCredentials. Quando o destinatário das novas credenciais ingressar no grupo de pares, suas credenciais existentes serão atualizadas pela Infraestrutura de Agrupamento de Pares.

Emitindo um convite

Um membro é convidado a ingressar no grupo de pares de uma das duas maneiras a seguir:

• Um administrador de grupo par chama PeerGroupCreateInvitation, passando a cadeia de caracteres XML de informações de identidade obtida do potencial convidado por meio de um mecanismo fora de banda comum, como email ou uma sessão de mensagens instantâneas. O convite também é passado por algum processo externo ou mecanismo para o par, que, em última análise, o receberá como uma cadeia de caracteres XML ou um arquivo de texto.
• Um administrador de grupo par chama PeerGroupIssueCredentials. Para usar essa função, o par já deve ter publicado informações de associação no grupo par (PEER_MEMBER) ou ter uma chave pública disponível (do par de chaves RSA usado para criar a identidade do assunto). No caso anterior, a estrutura de PEER_CREDENTIAL_INFO necessária para PeerGroupIssueCredentials pode ser obtida da estrutura PEER_MEMBER ; no último caso, uma nova estrutura de PEER_CREDENTIAL_INFO pode ser preenchida com a chave pública.

Depois de receber a cadeia de caracteres de convite, o par a passa para PeerGroupJoin para ingressar no grupo par. Se a chamada para PeerGroupJoin for bem-sucedida, o par poderá abrir posteriormente o grupo de pares chamando PeerGroupOpen.

Analisando um convite

Opcionalmente, um convite pode ser analisado chamando PeerGroupParseInvitation, que retorna uma estrutura PEER_INVITATION_INFO . Os campos na estrutura podem ser facilmente obtidos para fins de exibição.