Proteger un SDK o una biblioteca de clases .NET que entregas a tus clientes

Proteger una aplicación que entregas es un problema. Proteger una biblioteca que entregas —un SDK, un componente, un paquete NuGet contra el que otros desarrolladores compilan— es otro distinto, y la diferencia hace tropezar a la gente constantemente. Con una aplicación, puedes renombrar casi todo, porque nada externo llama por nombre. Con una biblioteca, la mitad del sentido es que la gente sí llame por nombre. Renombra lo que no debes y no has endurecido tu SDK: has roto la compilación de todos tus clientes.

El truco es una separación limpia: la API pública se queda exactamente como se publicó, y todo lo que hay detrás se protege. Este artículo trata de cómo trazar esa línea en .NET y publicar el resultado con seguridad.

Resumen

• La API pública debe conservar sus nombres exactos, o el código consumidor no compilará ni enlazará. Excluye del renombrado toda la superficie pública.
• Protege las interioridades que hay detrás: renombra miembros privados/internos, cifra cadenas, aplana el flujo de control interno.
• Reserva el cifrado de métodos o la virtualización para los métodos internos concretos que son el valor real: algoritmos propietarios, lógica de licenciamiento.
• Preserva también cualquier cosa que se resuelva por nombre en tiempo de ejecución: reflexión, serialización, DI, documentación XML pública.
• Prueba contra un consumidor real antes de publicar, y mantén el mapa de símbolos privado por versión.

Por qué una biblioteca es diferente de una aplicación

Cuando ofuscas una aplicación, el ensamblado es un mundo cerrado. El único punto de entrada es Main, y nada externo hace referencia a tus tipos por nombre, así que un ofuscador agresivo puede renombrar prácticamente todo y la aplicación sigue funcionando. Ese es el caso que nuestra guía cómo proteger el código .NET de la decompilación asume por defecto.

Una biblioteca invierte eso. Su razón de existir es que la llame código que nunca verás. Cada nombre de tipo, método, propiedad y parámetro público forma parte de un contrato:

// El código de tu cliente, compilado contra tu SDK:
var client = new AcmeSdk.PaymentClient(apiKey);
var result = client.Charge(amount, currency);

Si tu ofuscador renombra PaymentClient a a y Charge a b, el código de ese cliente ya no compila: los nombres contra los que se escribió han desaparecido. Peor aún, si el renombrado se entrega en una actualización menor, rompes a todo el que actualice. Así que la primera regla de proteger una biblioteca es: la superficie pública está vedada al renombrado. Lo que proteges es todo lo que el llamante no nombra: la implementación detrás del contrato.

Paso 1: preserva la superficie pública

Todo ofuscador serio puede preservar miembros por accesibilidad, y para una biblioteca quieres mantener intacta la superficie visible. En Nebula.NET esto es una regla de preservación/conservación que excluye del renombrado los miembros públicos y protegidos mientras deja el resto totalmente renombrable. Conceptualmente:

{
  "inputs": ["publish/AcmeSdk.dll"],
  "outputDirectory": "protected",
  "rename": {
    "keepPublicApi": true
  },
  "encryptStrings": true,
  "controlFlow": true
}

keepPublicApi (comoquiera que lo escriba tu herramienta) preserva los nombres a los que un consumidor puede hacer referencia —tipos, métodos, propiedades y eventos públicos y protegidos, y sus parámetros— de modo que el contrato compilado queda sin cambios. Todo lo internal, private o de otro modo invisible para un consumidor sigue siendo renombrable, que es exactamente donde quieres que la ofuscación muerda.

Una sutileza que merece la pena señalar: los miembros internal no forman parte de tu contrato público salvo que los hayas expuesto con [InternalsVisibleTo]. Si lo has hecho —a un ensamblado hermano o a un proyecto de pruebas que también entregas—, trátalos como públicos a efectos de preservación, o ese hermano se rompe.

Paso 2: preserva lo que se resuelve por nombre en tiempo de ejecución

Las reglas de accesibilidad capturan el contrato en tiempo de compilación, pero las bibliotecas se apoyan mucho en la resolución de nombres en tiempo de ejecución, y esos nombres no aparecen como “públicos” de forma obvia. Los sospechosos habituales:

• Serialización: si tus DTO los serializa a JSON/XML un consumidor (o tú), los nombres de las propiedades son un contrato de cable. Renómbralos y el ida y vuelta se rompe.
• Reflexión: cualquier cosa que tu biblioteca o sus consumidores busquen por cadena (GetType, GetMethod, descubrimiento guiado por atributos) debe conservar su nombre.
• Inyección de dependencias: tipos registrados y resueltos por un contenedor, o descubiertos por convención.

Una buena herramienta detecta los casos comunes automáticamente, pero deberías añadir reglas de conservación explícitas para cualquier cosa personalizada en lugar de confiar en la suerte. Esta es la mayor fuente de “funcionaba en mis pruebas, se rompió en el cliente”: el mismo modo de fallo que señalamos para las aplicaciones en CI, solo que con más superficie, porque los consumidores de una biblioteca hacen cosas impredecibles.

Paso 3: protege las interioridades, como es debido

Con la superficie clavada, las interioridades son donde endureces de verdad. Esta es la parte que da valor a tu SDK y la parte que un competidor o un cliente curioso más querría leer. Aplícala por capas:

• Renombra todos los tipos y miembros internos y privados: convierte los nombres autodescriptivos de tu implementación en ruido.
• Cifra las cadenas para que los endpoints internos, los mensajes, las plantillas de formato y las claves no entreguen tu lógica a quien busque en el binario. Consulta cifrado de cadenas en .NET.
• Aplana el flujo de control interno para que la implementación detrás de cada método público se decompile como un laberinto de goto en lugar de lógica limpia.
• Reserva la artillería pesada para las joyas de la corona. El puñado de métodos internos que son el producto —un algoritmo de emparejamiento propietario, una derivación de claves, una comprobación de licencia— son los candidatos a cifrado de métodos o virtualización de código. No virtualices toda la biblioteca; protege los métodos concretos que valen el coste en tiempo de ejecución.

El modelo mental: un consumidor ve una API limpia, estable y documentada; quien aplica ingeniería inversa y abre la DLL ve una superficie preservada envolviendo una implementación cara de leer.

Paso 4: mantén IntelliSense y la documentación funcionando

Una preocupación común es que la ofuscación arruine la experiencia de desarrollo de tu SDK. No lo hace, si lo haces bien. IntelliSense lee los nombres del ensamblado y las descripciones de tu archivo de documentación XML, y tú has preservado los nombres públicos y entregas el doc XML junto al paquete como de costumbre. La ofuscación cambia lo que hay dentro de tus métodos, no las firmas públicas que muestra IntelliSense. Así que los consumidores obtienen IntelliSense completo sobre tu API, con documentación, contra una implementación protegida.

Lo único que no debes hacer es entregar el mapa de símbolos interno dentro del paquete. Ese mapa invierte tu renombrado; es para que tú leas las trazas de pila de producción, y se queda privado (más sobre esto abajo).

Paso 5: empaqueta y publica con seguridad

El orden importa cuando una biblioteca se convierte en paquete NuGet. Ofusca primero el ensamblado, luego empaqueta la DLL protegida en el .nupkg: nunca empaquetes primero y confíes en la suerte. Después, antes de publicar:

1. Ofusca la biblioteca con la API pública preservada.
2. Empaqueta el ensamblado protegido (más la documentación XML) en el paquete.
3. Construye un consumidor real: un pequeño proyecto de ejemplo que haga referencia al paquete empaquetado (no al proyecto) y ejercite la API pública, más cualquier ruta de reflexión/serialización que un cliente tocaría.
4. Publica solo después de que esa prueba de consumidor pase.

Esa prueba de consumidor es el equivalente a ejecutar la batería de pruebas de tu aplicación contra la compilación protegida: es la única comprobación que demuestra que el contrato sobrevivió a la protección. Hazla contra el paquete empaquetado en concreto, porque el empaquetado es donde un error de preservación aflora de verdad.

Los límites honestos

La misma honestidad se aplica aquí que en todas partes de este terreno:

• Una API pública preservada es, por definición, legible. Elegiste mantener esos nombres y firmas: un decompilador los mostrará limpiamente, porque debe hacerlo para que la biblioteca sea usable. La protección va de la implementación detrás de la superficie, no de la superficie en sí. Si un método tiene que ser público, su forma es pública.
• La protección del lado del cliente eleva el coste, no hace el código indescifrable. Una biblioteca se ejecuta enteramente en la máquina del consumidor. La ofuscación y la virtualización hacen caras de invertir las interioridades; no las hacen imposibles. Si tu SDK impone licenciamiento, la decisión fiable pertenece a un servidor que tú controlas; consulta proteger las comprobaciones de licencia en .NET.
• La preservación ensancha un poco la superficie de ataque. Cada regla de conservación es un ancla legible. Conserva el mínimo que exijan el contrato y la resolución en tiempo de ejecución, no un margen generoso.

Primeros pasos

Proteger una biblioteca consiste sobre todo en trazar la línea en el lugar correcto y luego probar contra un consumidor real. Nebula.NET preserva tu API pública automáticamente, detecta los casos comunes de reflexión y serialización, y te deja añadir reglas de conservación explícitas para el resto; luego renombra, cifra y aplana todo lo que hay detrás de la superficie, con cifrado de métodos y virtualización para las interioridades que importan.

La edición gratuita ejecuta todo el bucle —ofuscar, empaquetar, probar un consumidor de ejemplo— para que puedas demostrar que el contrato sobrevive antes de comprometerte; limita cuánto puedes cifrar o virtualizar, no si puedes intentarlo. Si estás decidiendo entre niveles para un SDK que vas a enviar, qué edición de Nebula es la adecuada para ti y los precios exponen las opciones. Conserva la API que a tus clientes les encanta; protege la implementación que es tuya.