Casos de uso
Derechos
Los derechos son concesiones firmadas de clave/valor que viajan dentro de cada licencia y lease de Keyright. Úsalos para controlar el acceso a funciones, las cuotas numéricas y qué versiones del producto ejecuta una licencia — todo a partir de un único par de claves de firma, de modo que publicas una nueva versión mayor reemitiendo una clave, nunca rotando claves y distribuyendo una nueva clave pública.
Objetivo. Cambiar qué puede hacer un cliente — qué funciones recibe, cuánto de algo puede usar y qué versiones de tu producto puede ejecutar — sin publicar una nueva compilación y sin rotar jamás tus claves de firma. Los derechos son el único mecanismo detrás de los tres casos.
Qué es un derecho
Un derecho es un par name → value que adjuntas a una licencia. Keyright lo firma dentro de la licencia con la clave privada de tu tenant y lo entrega en la máquina del cliente por dos vías que tu aplicación ya verifica:
- dentro del archivo de licencia offline, y
- dentro del lease de activación online de corta duración.
Ambos están firmados con RSA y se comprueban contra la clave pública integrada en tu aplicación, de modo que un cliente no puede añadir un derecho, activar uno ni subir un número — editar cualquier parte rompe la firma y el SDK rechaza el conjunto entero. Nada en un derecho es secreto; la seguridad es la firma, no ocultar el valor.
Como cada SDK (.NET, Node, Python, Java) y el formato HTTP puro verifican la misma carga firmada, los mismos derechos se leen de la misma manera en una línea de productos de lenguajes mixtos a partir de una sola clave pública.
El principio: un par de claves, todas las versiones
El error de licenciamiento más común es atar el par de claves de firma a una versión del producto — emitir licencias 3.0 bajo una clave nueva y distribuir una nueva clave pública en la compilación 3.0. Esto rompe las compilaciones antiguas (no pueden verificar la clave nueva), fuerza la migración de todos los clientes de pago a la vez y no te da ningún control por cliente.
El modelo de Keyright es el opuesto:
Conserva un par de claves durante toda la vida del producto. Lleva qué puede hacer una licencia en derechos firmados y cámbialo reemitiendo la clave — nunca rotando claves.
La clave pública de tu aplicación nunca se mueve. Publicar la 4.0 no la toca. Si una licencia concreta puede ejecutar la 4.0 es una cuestión de derechos, respondida localmente contra la clave que ya integras.
Los tres patrones
Lee los derechos del LicenseInfo resuelto. El SDK de .NET expone un EntitlementSet con accesores tipados; los demás SDK exponen el equivalente.
1. Indicadores de función — desbloquear una capacidad
Una concesión booleana: activada o desactivada. IsEnabled acepta true, 1, yes o enabled.
var info = client.Validate(); // offline, from the cached lease/license
if (info.Entitlements.IsEnabled("feature.pdf_export"))
EnablePdfExport();
Este es el desbloqueo clásico por edición. Para el tratamiento completo — definir funciones en una edición, la condición de pago frente a gratis, combinarlo con indicadores de función operativos — consulta Condicionar funciones y ediciones.
2. Cuotas numéricas — imponer un límite
Un número que el cliente pagó: puestos, proyectos, llamadas a la API, dispositivos. GetLimit analiza el valor y trata "unlimited" como efectivamente infinito; el valor de reserva es lo que recibe un valor no licenciado o ausente (fallo cerrado).
long maxProjects = info.Entitlements.GetLimit("max_projects", fallback: 3);
if (currentProjectCount >= maxProjects)
throw new QuotaExceeded($"Your plan allows {maxProjects} projects.");
Cambia el límite de un cliente reemitiendo su clave con un nuevo max_projects — sin compilación, sin cambio de clave.
3. Control de versiones — qué releases ejecuta una licencia
Tu aplicación conoce su propia versión mayor. La licencia lleva la versión mayor más alta que cubre. Ejecuta solo en o por debajo de ese techo:
const int runningMajor = 4; // this build's major version
var raw = info.Entitlements.GetRaw("max_major_version"); // e.g. "3" or "4"
int ceiling = int.TryParse(raw, out var m) ? m : 3; // absent => your pre-coverage default
if (runningMajor > ceiling)
ShowUpgradeRequired($"Your license covers up to v{ceiling}.x.");
Así es como publicas una nueva versión mayor sin rotar claves: una licencia vendida para la línea 3.x lleva max_major_version: "3" (o nada, si es anterior al esquema), de modo que la 4.0 la rechaza localmente; una licencia que incluye la actualización a la 4.0 lleva "4". Un techo más alto sigue ejecutándose en compilaciones antiguas, así que una licencia 4.x continúa funcionando en la 3.x.
max_major_versiones un nombre que eliges tú. Elige cualquier clave en la que tu aplicación esté de acuerdo. El valor es una cadena simple; analízala como quieras versionar.
¿Necesitas un control más fino que “una versión mayor”? Si vendes por fecha de release, ventanas de mantenimiento o rangos exactos de versión — “cada release 2.x”, “cualquier cosa publicada en el año posterior a la compra”, “lo que se publique mientras la suscripción esté activa” — usa el motor de cobertura de versiones de primera clase de Keyright, que registra y firma el conjunto de cobertura completo y responde la elegibilidad de cualquier versión. El derecho anterior es la versión ligera y de grano mayor de la misma idea; la cobertura de versiones es la precisa.
Establecer derechos
En una sola licencia
Adjunta derechos cuando emites (o actualizas) una clave — panel, o la API de administración:
curl -X POST "https://keyright.example.com/admin/licenses" \
-H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{
"licensee": "Acme Ltd", "product": "your-product", "tier": "pro",
"entitlements": {
"feature.pdf_export": "true",
"max_projects": "10",
"max_major_version": "3"
}
}'
En el panel aparecen en el editor Features del cajón Issue-license como filas key → value.
En una plantilla de edición/nivel (heredada automáticamente)
Pon los valores por defecto en la edición para que cada clave emitida bajo ella los herede. Así es como lo haces automático de cara al futuro: establece max_major_version en tu edición actual hoy y, cuando publiques la siguiente versión mayor, sube la plantilla (o añade una nueva edición) — cada clave acuñada después lleva el nuevo techo, y cada clave ya en producción conserva aquello con lo que se emitió.
curl -X POST "https://keyright.example.com/admin/products/your-product/tiers" \
-H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{ "name": "Pro", "seats": 3,
"entitlements": { "feature.pdf_export": "true", "max_major_version": "3" } }'
Cómo llegan los derechos a la aplicación
issue/update license ──signs──▶ offline license file ─┐
│ ├─▶ your app verifies against the
└──on activation──▶ signed online lease ────────┘ embedded public key, reads EntitlementSet
- Las licencias offline llevan los derechos en el documento firmado; las máquinas aisladas de la red los leen sin conexión.
- Los leases online llevan los mismos derechos, firmados en la activación, de modo que la vía online expone exactamente lo que expone la vía offline. Un lease se renueva contra el servicio antes de caducar — así, reemitir los derechos de un cliente surte efecto en su siguiente renovación, sin reintroducir la clave y sin reactivar.
Como los valores están en la carga firmada, un archivo manipulado o editado a mano falla la verificación y se rechaza por completo — nunca lees un derecho falsificado.
Leer derechos en cada SDK
Cada SDK resuelve el mismo conjunto firmado. Los accesores (los nombres pueden variar ligeramente) son: una comprobación booleana IsEnabled(name), una lectura numérica GetLimit(name, fallback) ("unlimited" ⇒ máximo), una lectura de cadena en bruto y un ayudante de lista/pertenencia para concesiones multivalor.
- .NET —
info.Entitlements.IsEnabled(...),.GetLimit(...),.GetRaw(...),.GetList(...),.IsListed(name, value). - Node / Python / Java — las mismas lecturas sobre los derechos de la licencia resuelta.
- HTTP — los derechos son un objeto JSON en el lease/licencia firmado; verifica la firma y luego lee el objeto directamente.
Consulta las guías por lenguaje en Integración del SDK, y el repositorio de ejemplos ejecutable (la operación 7 demuestra los tres patrones).
Derecho frente a indicador de función frente a cobertura de versiones
| Lo que quieres… | Usa |
|---|---|
| Desbloquear una capacidad que un cliente pagó | Derecho (booleano) — esta página / condicionar funciones |
| Imponer un límite numérico (puestos, proyectos, llamadas) | Derecho (GetLimit) |
| Condicionar toda una versión mayor, de forma sencilla | Derecho (max_major_version) |
| Condicionar por fecha de release / rango de versión / ventana de mantenimiento | Cobertura de versiones |
| Escalonar un despliegue que tú controlas (no una compra) | Un indicador de función operativo, superpuesto dentro de lo que el derecho ya permite |
Verificar
- Emite dos claves bajo el mismo producto y par de claves — una con
max_major_version: "3", otra con"4". - En una compilación cuya versión mayor es
4, confirma que la primera se rechaza (“se requiere actualización”) y la segunda se ejecuta — con la misma clave pública en la aplicación. - Edita un lease/licencia almacenado para subir
max_projectso añadirfeature.pdf_export; confirma que el SDK lo rechaza (la firma ya no coincide). - Emite una clave sin
max_major_version; confirma que se comporta como tu valor por defecto documentado previo a la cobertura.