Cifrado de extremo a extremo
Este tema incluye información detallada sobre el uso del cifrado de extremo a extremo en el Client SDK de Vonage Video para Linux:
- Configuración del secreto de cifrado
- Sucesos y errores
- Establecer una clave secreta en una sesión sin cifrado de extremo a extremo
Para obtener una visión general del cifrado de extremo a extremo, consulta este tema.
Configuración del secreto de cifrado
Las sesiones cifradas de extremo a extremo se crean mediante las API del servidor (véase Activación del cifrado mediante la API REST).
Antes de que el cliente publique o se suscriba, llame a la función otc_session_set_encryption_secret() función:
otc_session_set_encryption_secret(session, secret);
otc_session_connect(session, TOKEN);
Una clave válida es una cadena de entre 8 y 256 caracteres. Puedes cambiar la clave llamando a la función otc_session_set_encryption_secret() función de nuevo.
Si se introduce un secreto no válido, se producirá un OTC_SESSION_INVALID_ENCRYPTION_SECRET error.
Sucesos y errores
Los eventos y errores son esenciales para gestionar el comportamiento del cifrado dirigido por el usuario. El cifrado de extremo a extremo utiliza el modelo de secreto compartido: se espera que todos los participantes en la sesión utilicen el mismo secreto para cifrar sus medios y descifrar los de los demás.
El nuevo código de error es OTC_SESSION_INVALID_ENCRYPTION_SECRET y se devolverá como código de resultado del método `set_encryption_secret`, no en la función de devolución de llamada `on_error`.
Si un cliente intenta establecer un secreto de cifrado no válido para una sesión, el otc_session_callbacks.on_error() devuelve un código de error igual a OTC_SESSION_INVALID_ENCRYPTION_SECRET. En el siguiente ejemplo, se inicializa una sesión con un secreto de cifrado vacío (y, por lo tanto, no válido):
int result = otc_session_set_encryption_secret(session, "");
if (result == OTC_SESSION_INVALID_ENCRYPTION_SECRET) {
// Report error...
}
Si un usuario intenta publicar en una sesión cifrada de extremo a extremo sin haber especificado un secreto de cifrado, al llamar a la función otc_session_publish() da como resultado la función otc_publisher_callbacks.on_error() función a la que se llama con un error cuyo código está establecido en OTC_SESSION_ENCRYPTION_SECRET_MISSING. Para garantizar la mejor experiencia de usuario, la aplicación debería validar una clave secreta facilitada por el usuario antes de llamar a la otc_session_publish() función:
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);
Si un suscriptor no puede descodificar el contenido multimedia de una transmisión debido a una clave de cifrado incorrecta, el subscriber_callbacks.on_error() con un error cuyo código es OTC_SUBSCRIBER_ENCRYPTION_SECRET_MISMATCH. Es importante comunicar al usuario que los medios no se están recibiendo debido a un desajuste de cifrado y no a un fallo de conexión o a un problema de audio/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);
Si un abonado encuentra un error interno al descifrar un paquete, el subscriber_callbacks.on_error() con un error cuyo código es OTC_SUBSCRIBER_DECRYPTION_INTERNAL_ERROR.
Establecer una clave secreta en una sesión sin cifrado de extremo a extremo
Nota: Esta función está disponible a partir de la versión 2.36.0 del SDK.
Si una sesión no se ha creado con el cifrado de extremo a extremo activado, al establecer un secreto de cifrado para ella se produce un error que indica que «el cifrado no está activado». El momento en que aparece el error depende de cuándo se establezca el secreto en relación con la conexión, la publicación y la suscripción.
Configuración de la clave secreta antes de conectarse
Solo se sabe si una sesión tiene activado el cifrado de extremo a extremo una vez que el cliente se conecta. Si llamas a otc_session_set_encryption_secret() Antes de establecer la conexión, la llamada se realiza con éxito y la sesión se establece con normalidad. El error se produce cuando el cliente publica o se suscribe: el otc_session_publish() la función devuelve OTC_PUBLISHER_ENCRYPTION_NOT_ENABLED, y el otc_session_subscribe() la función devuelve 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.
}
Configuración de la clave secreta tras la conexión
Si llamas otc_session_set_encryption_secret() Una vez que el cliente se ha conectado a una sesión sin cifrado de extremo a extremo, el secreto no se establece y la función devuelve 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.
}
Configuración de la clave secreta al publicar o suscribirse
Si llamas otc_session_set_encryption_secret() Mientras el cliente ya esté publicando o suscrito, la llamada falla tal y como se ha descrito anteriormente, y todos los editores y suscriptores activos también se eliminan de la sesión. El otc_publisher_callbacks.on_error() La función se invoca para cada editor con un error cuyo código esté establecido en OTC_PUBLISHER_ENCRYPTION_NOT_ENABLED, y el otc_subscriber_callbacks.on_error() La función se invoca para cada suscriptor con un error cuyo código esté establecido en OTC_SUBSCRIBER_ENCRYPTION_NOT_ENABLED.
Recuperación tras el error
La sesión sigue siendo válida tras cualquiera de estos errores. Para volver a publicar o suscribirte, borra el secreto llamando a otc_session_set_encryption_secret() con NULL. A continuación, el mismo objeto `otc_publisher` se puede pasar a otc_session_publish() otra vez:
otc_session_set_encryption_secret(session, NULL);
otc_session_publish(session, publisher);