Métodos DSS
El servicio de firma de documentos de Redtrust cumple el estándar DSS de OASIS y algunas de sus extensiones.
El servicio se compone de tres métodos:
1. GetAccessibleCertificates
Este método obtiene la lista de certificados disponibles para el usuario autenticado, en función de las políticas de autorización de Redtrust.
Para llamar a este método, debes autenticarte como el usuario cuyos certificados quieres obtener. La respuesta incluye un objeto Result que contiene la lista de certificados accesibles.
En la respuesta se devuelve un objeto Result, con un ResultStatus en estado de éxito que indica que no se ha producido ningún error. También se devuelve un ResultMessage con un mensaje descriptivo y un objeto ResultData, que es una lista de objetos Certificate.
Cada objeto Certificate contiene la información necesaria para su uso. Por ejemplo, la siguiente:
| Parámetros | Descripción |
|---|---|
needPin | Indica si es necesario un PIN para usar el certificado. |
thumbprint | Identificador que se utiliza en SignHash y SignRequest; el campo expiration permite saber si el certificado ha caducado. |
alias | Nombre asignado al certificado en la configuración de Redtrust. |
issuer o subject | Información extraída directamente del certificado para esos campos o, en su defecto, la propia huella digital. |
X509Data | Parte pública del certificado. El contenido de este atributo está codificado en Base64 para poder incluirse en la respuesta. |
filter | Filtro opcional para la lista de certificados devuelta. Permite filtrar por cualquier cadena incluida en el campo subject del certificado. Si se omite o está vacío, el servicio devuelve todos los certificados accesibles. |
2. SignHash
Este método realiza una firma digital sobre un hash previamente calculado utilizando el certificado seleccionado.
Debes llamar al método SignHash y proporcionar:
- El hash que se va a firmar
- El tipo de firma
- Los datos de identificación del certificado
El servicio genera una firma en formato PKCS#1. En las secciones siguientes se proporcionan más detalles y ejemplos.
Los parámetros de entrada del método son:
| Parámetros | Descripción |
|---|---|
toSignHash | Hash binario codificado en Base64. |
thumbprint | Huella digital del certificado. |
certificatePin | PIN del certificado (opcional). |
algorithm | Algoritmo de hash; los valores admitidos son RSA_SHA1, RSA_SHA256, RSA_SHA512, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512. |
En la respuesta se devuelve un objeto Result con los siguientes campos:
| Campo | Descripción |
|---|---|
ResultStatus | Código de resultado; SUCCESS si la firma se ha realizado correctamente. |
ResultMessage | Mensaje que describe el resultado de la operación. |
ResultData | Contiene el resultado de la operación si la firma se ha realizado correctamente (opcional). |
Consulta los códigos de respuesta Result de este documento para conocer los posibles códigos de error que pueden devolverse en la respuesta.
3. SignRequest
Realiza una operación completa de firma de documentos basada en el estándar DSS de OASIS.
Para usar este método, envía un objeto SignRequest válido que cumpla el esquema DSS y sus extensiones. La petición especifica el perfil de firma, el certificado de firma y el documento de entrada. El servidor responde con un objeto SignResponse que contiene:
- Un código de respuesta y un mensaje
- El resultado de la operación de firma
Estructura de la petición
Los siguientes campos constituyen el núcleo de la mayoría de las peticiones de firma. Según la configuración del perfil de firma, algunos campos pueden quedar forzados por el perfil y omitirse en la petición.
| Campo | Ubicación | Descripción |
|---|---|---|
Profile | Atributo de SignRequest | Identifica el perfil de firma configurado en Redtrust. El perfil puede forzar el modo de firma, el nivel y otras opciones. |
RequestID | Atributo de SignRequest | Identificador que se devuelve en la respuesta para facilitar la correlación entre peticiones y respuestas. |
OptionalInputs | Cuerpo de SignRequest | Entradas opcionales que influyen en cómo se genera la firma. |
KeySelector | OptionalInputs | Selecciona el certificado de firma (normalmente mediante la huella digital). |
AdditionalKeyInfo | OptionalInputs | Información adicional de la clave requerida por el certificado, como un PIN. |
SignatureForm | OptionalInputs | Forma de firma que utiliza el servicio para validar y procesar la petición. |
| Elemento de modo de firma | OptionalInputs | Especifica cómo se relaciona la firma con el documento cuando el perfil no lo fuerza (por ejemplo, enveloped, enveloping o detached). |
InputDocuments | Cuerpo de SignRequest | Contenedor del documento o documentos que se van a firmar. |
Document | InputDocuments | Documento de entrada. El atributo ID puede referenciarse desde otros elementos de la petición. |
| Elemento de contenido del documento | Document | Proporciona el contenido del documento (binario o XML), según el escenario de firma. |
Para ver ejemplos completos de peticiones y respuestas, consulta Ejemplos de la API DSS.
Para obtener definiciones detalladas, valores admitidos y restricciones de elementos DSS como Profile, SignatureForm e InputDocuments, consulta la referencia de la API DSS.
Para la estructura normativa de los mensajes DSS, consulta la especificación de OASIS: