rFirma en macOS: firmar con los certificados del llavero y la integración con el sistema #2000

Alcance: firmar con los certificados del llavero de macOS y la integración con el sistema. Las tarjetas y el DNIe están en #2043 (needs-triage); la distribución por el tap de Homebrew, en #2045.

Problem Statement

En macOS, rFirma compila, se empaqueta y firma con una clave en memoria (ADR-0040), pero quien lo abre en su Mac no puede firmar nada:

• no ve ningún certificado: ni los de su llavero. La búsqueda de almacenes es la de Linux (módulos PKCS#11 y bases NSS de /usr/lib), que en un Mac no encuentra nada;
• no puede instalar un .p12: el Almacén de rFirma es una base NSS y macOS no trae NSS;
• no puede hacer un trámite de sede: la CA local consta siempre como no instalada y no hay forma de instalarla, así que el navegador no confía en el servidor local;
• no sabe quién abre afirma:// ni puede elegir rFirma si AutoFirma está instalada;
• una sede que pide el almacén APPLE recibe un error;
• si rFirma no arranca, el aviso sale por la salida de error, que en un .app nadie ve, y --debug-info habla de NSS;
• la entrega no publica el paquete de macOS y rFirma no se actualiza en macOS.

Solution

En macOS, rFirma usa la API de macOS siempre que puede, igual que en Windows (ID-475):

• Los certificados con clave de software del llavero aparecen como Almacén de macOS, y se firma con ellos por la API del sistema: Rust calcula el resumen y macOS lo firma (ADR-0001). La contraseña o el permiso los pide macOS con su diálogo.
• «Instalar certificado» lleva el .p12 al llavero de inicio de sesión (ADR-0034); en macOS no hay Almacén de rFirma.
• La CA local se instala en la confianza de la persona usuaria de macOS, con el diálogo de contraseña del sistema; Safari, Chrome y Firefox (120 o posterior) confían en ella sin tocar perfiles.
• rFirma sabe quién abre afirma:// y deja elegirse, respetando a AutoFirma.
• APPLE y -store apple acotan al Almacén de macOS.
• El aviso de arranque es una alerta nativa y --debug-info habla de macOS.
• La entrega publica el paquete de macOS con firma ad hoc y rFirma se actualiza sola, por el canal de Windows.
• Mientras El DNIe y las tarjetas en macOS #2043 no decida, macOS no lee tarjetas: el Almacén de macOS no lista identidades con clave en un token y la línea del lector no aparece.

User Stories

Certificados del llavero

1. Como persona con un certificado en el llavero de mi Mac, quiero verlo en la lista de rFirma, para firmar sin exportarlo.
2. Como persona con un certificado en el llavero, quiero firmar un PDF con él desde la ventana de rFirma, para no depender de AutoFirma.
3. Como persona con un certificado en el llavero, quiero firmar con él en un trámite de sede, para terminar el trámite.
4. Como persona que firma con un certificado del llavero, quiero que me pida permiso el diálogo de macOS, el que ya conozco, para confiar en quién usa mi clave.
5. Como persona que pulsa «Denegar» en el diálogo de macOS, quiero que rFirma lo trate como una cancelación mía y no como un fallo.
6. Como persona que escribe mal la contraseña en el diálogo de macOS, quiero que rFirma me diga que era incorrecta.
7. Como persona con certificados en el llavero, quiero ver su fila rotulada «Almacén de macOS», para saber de dónde sale.
8. Como persona con el mismo certificado en el llavero y en el perfil de Firefox, quiero verlo una sola vez.
9. Como persona con certificados sin clave privada en el llavero, quiero que solo salgan los que tienen clave, para no elegir uno con el que no se puede firmar.
10. Como persona que firma con SHA-1 porque lo permití en Preferencias, quiero que también funcione con el llavero, como en Windows.
11. Como persona con un certificado de curva elíptica en el llavero, quiero firmar con él igual que con uno RSA.
12. Como persona que lista certificados, quiero que rFirma no abra la clave ni me pida nada solo por listar.
13. Como persona con una tarjeta cuyo controlador mete sus certificados en el llavero, quiero no verlos en el Almacén de macOS mientras rFirma no sepa firmar con tarjetas en macOS, para no elegir uno que va a fallar.
14. Como persona que mete una tarjeta en su Mac, quiero que rFirma no me muestre una línea del lector que prometa algo que no hace.

Sedes y línea de órdenes

15. Como sede que pide el almacén APPLE, quiero que rFirma en macOS ofrezca los certificados del Almacén de macOS, como AutoFirma.
16. Como persona que usa la línea de órdenes de AutoFirma, quiero que -store apple funcione con rFirma en macOS.

Instalar un certificado

17. Como persona con un .p12, quiero instalarlo desde rFirma en mi Mac, para firmar con él después.
18. Como persona que instala un .p12, quiero que acabe en mi llavero de inicio de sesión, para que lo vean también otras aplicaciones del Mac.
19. Como persona que escribe mal la contraseña del .p12, quiero que rFirma me lo diga sin instalar nada.
20. Como persona que quita un certificado instalado desde rFirma, quiero que desaparezca del llavero.

Trámites de sede

21. Como persona que hace su primer trámite en macOS, quiero instalar la CA local desde rFirma, para que el navegador confíe en el servidor local.
22. Como persona que instala la CA, quiero que macOS me pida mi contraseña con su diálogo, para saber que el cambio lo autorizo yo.
23. Como persona que cancela ese diálogo, quiero que rFirma diga que la CA no se instaló, sin error genérico.
24. Como persona que usa Safari, Chrome o Firefox, quiero que todos confíen en la CA sin configurar nada en cada uno.
25. Como persona, quiero ver en el estado de rFirma si la CA está instalada en «Almacén de macOS» y cuándo caduca.
26. Como persona que quiere retirar la CA, quiero hacerlo desde rFirma.
27. Como persona con AutoFirma instalada, quiero ver quién abre hoy afirma:// y poder elegir rFirma, sin que rFirma se lo quede sin preguntar.
28. Como persona que vuelve a AutoFirma, quiero poder elegirla otra vez.
29. Como persona que pulsa «Firmar» en una sede con rFirma cerrada, quiero que rFirma se abra y atienda el trámite.

Arranque, diagnóstico y actualización

30. Como persona a la que rFirma no le arranca, quiero ver el motivo en una ventana de macOS, no en una terminal que no tengo abierta.
31. Como persona que pide ayuda, quiero que --debug-info muestre en macOS la confianza de la CA y los controladores de tarjeta del sistema, para adjuntarlo a mi consulta.
32. Como persona con rFirma en mi Mac, quiero que se actualice sola, como en Windows.
33. Como responsable del proyecto, quiero que cada versión publique el paquete de macOS en la Release, para que haya algo que instalar.

Proyecto

34. Como desarrollador en un Mac, quiero registrar el ejecutable de desarrollo como manejador de afirma:// con just dev-handler, como en Linux.
35. Como desarrollador, quiero probar el listado y la firma del Almacén de macOS en el CI sin tocar el llavero de nadie, con un llavero temporal.
36. Como responsable del proyecto, quiero que la regla «en macOS, la API de macOS» quede en el ADR-0040, para que nadie la rompa sin conocerla.
37. Como persona con Linux o Windows, quiero que nada de esto cambie lo que veo.

Implementation Decisions

La regla

• ID-527: En macOS se usa la API de macOS siempre que se pueda (Security.framework y LaunchServices), como ID-475 en Windows. Las tarjetas y el DNIe quedan fuera hasta que El DNIe y las tarjetas en macOS #2043 decida. El ADR-0040 se reescribe en su sitio con la regla, como se hizo con el ADR-0035; los adaptadores pendientes que esta spec sustituye salen de su tabla.

El Almacén de macOS

• ID-528: Término nuevo «Almacén de macOS» (clase de almacén propia, como StoreClass::Windows): los certificados con clave privada del llavero de la persona usuaria. Se rotula «Almacén de macOS» en la lista, el asistente y el estado. El glosario lo define junto a «Almacén de Windows»; «llavero» sigue reservado para lo que guarda secretos.
• ID-529: Un adaptador del puerto Token para el Almacén de macOS, análogo al del Almacén de Windows. Lista identidades del llavero sin abrir la clave, completa la cadena con los certificados del llavero y del sistema, y entrega con cada certificado si su clave vive en un token del sistema (tarjeta) o en software.
• ID-530: La firma sigue el ADR-0001: Rust calcula el resumen y el sistema firma el resumen ya calculado con RSA PKCS#1 v1.5, RSA PSS y ECDSA (que macOS ya devuelve en DER), SHA-1 incluido con su rama explícita (Windows: CNG firma con SHA-1 cuando la preferencia lo permite #1625). Los errores del sistema se traducen a las situaciones de siempre: cancelación, contraseña o PIN incorrecto, PIN bloqueado, tarjeta retirada.
• ID-531: El orden de almacenes pasa a ser: tarjeta, Almacén de Windows o Almacén de macOS, Almacén de rFirma, NSS del sistema, familia Firefox, familia Chromium. El glosario se actualiza.
• ID-554: El Almacén de macOS solo lista certificados con clave de software. Una identidad con la clave en un token del sistema no sale, sea el DNIe, una PIV o cualquier otra tarjeta: ID-532 cae (Sonda: una app con firma ad hoc y las identidades de un token del sistema en macOS #2002) y las tarjetas son de El DNIe y las tarjetas en macOS #2043.
• ID-533: APPLE y -store apple acotan al Almacén de macOS en macOS (paridad con AutoFirma, ADR-0041). Fuera de macOS siguen como hoy.
• ID-537: Para el Almacén de macOS no hay diálogo propio: la contraseña o el PIN los pide macOS, como en Windows (ID-477).

Instalar certificados

• ID-534: En macOS, «Instalar certificado» importa el .p12 al llavero de inicio de sesión (ADR-0034) y el certificado aparece en el Almacén de macOS. Quitar un certificado instalado lo borra del llavero. En macOS no existe el Almacén de rFirma ni el llavero de su PIN; el adaptador pendiente del llavero se queda respondiendo que no hay, sin uso.

Lectores

• ID-555: En macOS no se vigilan los lectores ni aparece la línea del lector mientras rFirma no lea tarjetas en macOS. El vigilante, el diálogo nativo del PIN de PKCS#11 y la ayuda de la línea «ilegible» de macOS se quedan en el código para El DNIe y las tarjetas en macOS #2043.

Integración con el sistema

• ID-542: La CA local se instala en la confianza del dominio de la persona usuaria de macOS (ADR-0005), con el diálogo de contraseña que pide el sistema; rFirma no lo sustituye ni lo esquiva. Se mide si está instalada y su caducidad, y se retira desde rFirma. Marca nueva «Almacén de macOS» en el asistente y el estado, junto a «Almacén de Windows». No hay perfiles de Firefox que gestionar en macOS: Firefox 120 o posterior importa la confianza del usuario. Sustituye al adaptador pendiente de la CA en macOS.
• ID-543: afirma:// por LaunchServices: rFirma lee qué aplicaciones declaran el esquema y cuál lo abre, y la persona elige con la API actual del sistema. Igual que en Linux y Windows, rFirma nunca se queda con el esquema sin que la persona lo pida. Sustituye al adaptador pendiente de los manejadores en macOS. El arranque en frío desde afirma:// con el .app real se prueba a mano.
• ID-544: just dev-handler funciona en macOS: registra el ejecutable de desarrollo como manejador de afirma:// por LaunchServices, como hoy hace con xdg-mime en Linux.
• ID-545: El aviso de arranque en macOS es una alerta nativa del sistema, que no necesita la ventana de Tauri.
• ID-546: --debug-info en macOS sustituye las secciones de NSS por la confianza de la CA local en el Almacén de macOS (instalada, caducidad) y los controladores de tarjeta del sistema (como --debug-info: almacén de Windows y minidrivers #1864 en Windows). Los módulos PKCS#11 son de El DNIe y las tarjetas en macOS #2043.

Entrega y actualización

• ID-548: No hay cuenta de Apple Developer. rFirma para Mac no se firma con Developer ID ni se notariza; mantiene la firma ad hoc y el hardened runtime desactivado del ADR-0040, que además deja cargar módulos PKCS#11 de terceros.
• ID-550: En macOS, rFirma se actualiza sola con el canal de Windows (Actualización de rFirma en Windows desde la propia aplicación #1230): la entrega publica el paquete de actualización de macOS firmado con minisign y su entrada en latest.json, y rFirma lo comprueba e instala igual que en Windows. Una instalación por Homebrew no se trata como gestionada por paquete; el cask y su auto_updates: true son de Distribución de rFirma para Mac por un tap de Homebrew #2045.

Testing Decisions

• TD-131: Una buena prueba mira el comportamiento visible desde fuera: la lista que recibe la ventana con sus chips y su orden, el estado del lector, lo que se firma y si verifica, el estado de la CA y del manejador. No mira llamadas a Security.framework ni a LaunchServices.
• TD-132: El Almacén de macOS en el caso de uso de listado de identity, con un doble del adaptador en el puerto Token que entrega certificados con clave de software y con clave en un token: los primeros salen como «Almacén de macOS» y los segundos no salen. Precedente: TD-126 y TD-117/118.
• TD-134: El adaptador del Almacén de macOS con pruebas cfg(macos) contra un llavero temporal que cada prueba crea, desbloquea y borra, con un certificado de pruebas propio (RSA y curva elíptica): listar, firmar con PKCS#1, PSS y ECDSA y verificar la firma; importar un .p12 y quitarlo. Nunca tocan el llavero de inicio de sesión de quien las corre. Precedente: las pruebas CNG de TD-128, que crean y borran su certificado.
• TD-135: La CA local y afirma:// por sus puertos actuales con dobles: el caso de uso de confianza muestra «Almacén de macOS» con su estado y caducidad, y el de manejadores respeta a AutoFirma. Los adaptadores reales, que piden contraseña o tocan LaunchServices, se prueban a mano.
• TD-140: El canal de actualización de macOS se prueba como el de Windows (Canal windows que comprueba la versión contra latest.json #1233): la comprobación de versión contra latest.json elige la entrada darwin-aarch64, y una instalación por Homebrew no desactiva el actualizador.
• TD-141: Las guardas de plataforma (AUTHORISED_SITES, ADR-0035) incluyen cada adaptador nuevo de macOS y siguen en verde en Linux y Windows.
• TD-144: Los lectores en macOS se prueban en el caso de uso de lectores: en macOS no se vigilan y no hay línea del lector; Linux y Windows no cambian.

Out of Scope

• Las tarjetas y el DNIe en macOS, el diálogo propio del PIN de PKCS#11 en uso y la búsqueda de módulos PKCS#11: El DNIe y las tarjetas en macOS #2043.
• La distribución por el tap de Homebrew y sus instrucciones: Distribución de rFirma para Mac por un tap de Homebrew #2045.
• Firma con Developer ID, notarización y cualquier otra vía que necesite cuenta de Apple Developer (ID-548).
• macOS en Intel.
• Leer certificados del almacén propio de Firefox en macOS.

Further Notes

• Ya integrado en la rama de la spec y que sirve a El DNIe y las tarjetas en macOS #2043: el vigilante PC/SC en macOS (El vigilante de lectores corre en macOS #2009), el diálogo nativo del PIN de PKCS#11 (El PIN de una tarjeta por PKCS#11 se pide con un diálogo nativo de macOS #2011) y la ayuda de la línea «ilegible» de macOS (La línea del lector «ilegible» en macOS ofrece OpenSC y la DGP #2016).
• Las decisiones ID-532, ID-535, ID-536, ID-538, ID-539, ID-541 e ID-547 pasaron a El DNIe y las tarjetas en macOS #2043; ID-549, a Distribución de rFirma para Mac por un tap de Homebrew #2045. Sus números no se reutilizan.
• Instalar confianza en el dominio de usuario pide contraseña (Apple); Firefox 120 importa en macOS las raíces del usuario (notas).
• Con firma ad hoc (ID-548), cada versión es otra identidad de código para macOS, y el «Permitir siempre» del llavero puede volver a pedirse tras cada actualización.
• El carril de macOS del CI corre en macos-14 y el mínimo de la aplicación es 15.4; las pruebas de esta spec no arrancan la aplicación.