Criptografia de ponta a ponta
Este tópico inclui detalhes sobre como usar a criptografia de ponta a ponta no Vonage Client SDK para Linux:
- Configurando o segredo de criptografia
- Eventos e erros
- Definir um segredo em uma sessão sem criptografia de ponta a ponta
Para obter uma visão geral da criptografia de ponta a ponta, consulte esse assunto.
Configurando o segredo de criptografia
As sessões com criptografia de ponta a ponta são criadas por meio de APIs do servidor (consulte Ativando a criptografia por meio da API REST).
Antes que o cliente publique ou se inscreva, chame o otc_session_set_encryption_secret() função:
otc_session_set_encryption_secret(session, secret);
otc_session_connect(session, TOKEN);
Um segredo válido é uma sequência de caracteres com comprimento entre 8 e 256 caracteres. Você pode alterar o segredo chamando a função otc_session_set_encryption_secret() funcionar novamente.
O envio de um segredo inválido resultará em um OTC_SESSION_INVALID_ENCRYPTION_SECRET erro.
Eventos e erros
Eventos e erros são essenciais para gerenciar o comportamento da criptografia orientada pelo usuário. A criptografia de ponta a ponta utiliza o modelo de segredo compartilhado: espera-se que todos os participantes da sessão utilizem o mesmo segredo para criptografar seus dados e descriptografar os dados dos demais participantes.
O novo código de erro é OTC_SESSION_INVALID_ENCRYPTION_SECRET e será retornado como o código de resultado do método set_encryption_secret, e não na função de retorno on_error.
Se um cliente tentar definir um segredo de criptografia inválido para uma sessão, o otc_session_callbacks.on_error() retorna um código de erro definido como OTC_SESSION_INVALID_ENCRYPTION_SECRET. No exemplo a seguir, uma sessão é inicializada com um segredo de criptografia vazio (e, portanto, inválido):
int result = otc_session_set_encryption_secret(session, "");
if (result == OTC_SESSION_INVALID_ENCRYPTION_SECRET) {
// Report error...
}
Se um usuário tentar publicar em uma sessão criptografada de ponta a ponta sem ter especificado um segredo de criptografia, ao chamar a função otc_session_publish() A função resulta no otc_publisher_callbacks.on_error() função sendo chamada com um erro cujo código está definido como OTC_SESSION_ENCRYPTION_SECRET_MISSING. Para garantir a melhor experiência do usuário, o aplicativo deve validar um segredo fornecido pelo usuário antes de chamar o otc_session_publish() função:
static void on_publisher_error(otc_publisher *publisher,
void *user_data,
const char* error_string,
enum otc_publisher_error_code error_code) {
if (otc_publisher_error_code == OTC_SESSION_ENCRYPTION_SECRET_MISSING) {
// The application should communicate that the secret was not set.
}
}
struct otc_publisher_callbacks publisher_callbacks = {0};
publisher_callbacks.on_error = on_publisher_error;
session = otc_session_new(API_KEY, SESSION_ID, &session_callbacks);
otc_publisher *publisher = otc_publisher_new("Joe",
nullptr,
&publisher_callbacks);
otc_session_publish(session, publisher);
Se um assinante não conseguir decodificar o conteúdo de mídia de um stream devido a uma chave de criptografia incorreta, o subscriber_callbacks.on_error() a função é chamada com um erro cujo código está definido como OTC_SUBSCRIBER_ENCRYPTION_SECRET_MISMATCH. É importante informar ao usuário que a mídia não está sendo recebida devido a uma incompatibilidade de criptografia e não por causa de uma falha na conexão ou de um problema de áudio/vídeo:
static void on_subscriber_error(otc_subscriber *subscriber,
void *user_data,
const char* error_string,
enum otc_subscriber_error_code error_code) {
if (otc_subscriber_error_code == OTC_SUBSCRIBER_ENCRYPTION_SECRET_MISMATCH) {
// Activate a UI element communicating that there's been an encryption secret mismatch.
}
}
struct otc_subscriber_callbacks subscriber_callbacks = {0};
subscriber_callbacks.on_error = on_subscriber_error;
otc_subscriber *subscriber = otc_subscriber_new(stream,
&subscriber_callbacks);
otc_session_subscribe(session, subscriber);
Se um assinante encontrar um erro interno ao descriptografar um pacote, o subscriber_callbacks.on_error() a função é chamada com um erro cujo código está definido como OTC_SUBSCRIBER_DECRYPTION_INTERNAL_ERROR.
Definir um segredo em uma sessão sem criptografia de ponta a ponta
Observação: Esse recurso está disponível a partir da versão 2.36.0 do SDK.
Se uma sessão não tiver sido criada com a criptografia de ponta a ponta ativada, definir um segredo de criptografia para ela resultará em um erro do tipo “criptografia não ativada”. O momento em que o erro ocorre depende de quando o segredo é definido em relação à conexão, à publicação e à assinatura.
Definir a senha antes de se conectar
Só é possível saber se uma sessão tem a criptografia de ponta a ponta ativada depois que o cliente se conecta. Se você chamar otc_session_set_encryption_secret() antes da conexão, a chamada é bem-sucedida e a sessão é estabelecida normalmente. O erro é relatado quando o cliente publica ou se inscreve: o otc_session_publish() a função retorna OTC_PUBLISHER_ENCRYPTION_NOT_ENABLED, e o otc_session_subscribe() a função retorna OTC_SUBSCRIBER_ENCRYPTION_NOT_ENABLED:
otc_status result = otc_session_publish(session, publisher);
if (result == OTC_PUBLISHER_ENCRYPTION_NOT_ENABLED) {
// The application should communicate that end-to-end encryption
// is not enabled for this session.
}
Definir a senha após a conexão
Se você ligar otc_session_set_encryption_secret() depois que o cliente se conecta a uma sessão sem criptografia de ponta a ponta, o segredo não é definido e a função retorna OTC_SESSION_ENCRYPTION_NOT_ENABLED:
otc_status result = otc_session_set_encryption_secret(session, secret);
if (result == OTC_SESSION_ENCRYPTION_NOT_ENABLED) {
// The application should communicate that end-to-end encryption
// is not enabled for this session.
}
Definir o segredo ao publicar ou assinar
Se você ligar otc_session_set_encryption_secret() enquanto o cliente já estiver publicando ou assinando, a chamada falha conforme descrito acima, e todos os publicadores e assinantes ativos também são removidos da sessão. O otc_publisher_callbacks.on_error() A função é chamada para cada editor com um erro cujo código esteja definido como OTC_PUBLISHER_ENCRYPTION_NOT_ENABLED, e o otc_subscriber_callbacks.on_error() A função é chamada para cada assinante com um erro cujo código esteja definido como OTC_SUBSCRIBER_ENCRYPTION_NOT_ENABLED.
Recuperação após o erro
A sessão permanece válida após qualquer um desses erros. Para publicar ou assinar novamente, limpe o segredo chamando otc_session_set_encryption_secret() com NULL. O mesmo objeto `otc_publisher` pode então ser passado para otc_session_publish() novamente:
otc_session_set_encryption_secret(session, NULL);
otc_session_publish(session, publisher);