Conexión JCA SSL

Información general

Uso del proveedor HSM JCA para establecer un túnel TLS con autenticación mutua (mTLS).

El código es un ejemplo de la documentación de la API Java de HSM.

Este ejemplo establece una conexión con un punto final de SEFAZ-SP (Secretaría de Hacienda del Estado de São Paulo) accesible el 03 de octubre de 2025, pero puede utilizarse con cualquier host compatible con el estándar.

Configuración del entorno:

SO: Windows 11 Pro
Símbolo del sistema
Maven 3.9.1
Navegador Chrome: versión 134.0.6998.166 (versión oficial) 64 bits
Java 21 (instalado, en ruta y JAVA_HOME)
Firmware HSM: 5.9.0.0
Cliente HSM: 4.19.0
Cliente Java de HSM: 4.19.0 (o superior)

Requisitos

Conectividad con el HSM (puerto TCP 4433).
Servicio HSM iniciado.
Credenciales de la partición HSM donde se creará o utilizará la clave privada.
Clave privada, certificado y cadena de usuario.
Cadena de certificados del host remoto.

Artefactos

Peligro

Siga estrictamente las reglas de nomenclatura o los certificados y cadenas no se encontrarán, haciendo imposible establecer el túnel TLS. Consulte más detalles y opciones en la documentación de JCA.

Por ejemplo:

Clave privada: el nombre es libre. Por ejemplo: test.
Certificado: el nombre de la clave privada con el sufijo _cert. Por ejemplo: test_cert.
Cadena del certificado: el nombre de la clave privada con un sufijo _chain. Por ejemplo: cadena_prueba.

Importar un archivo .pfx

Si no tiene una clave privada y un certificado instalados en el HSM, lleve a cabo los siguientes pasos.

Instale el cliente HSM, disponible en descargas.
Abra el programa dynamocon.
Configure la información del HSM.
Importe el archivo PFX que contiene la clave privada y el certificado que se utilizarán para la autenticación mutua.

En este punto, el HSM tendrá una clave privada y un certificado de usuario. Por ejemplo: clave privada denominada test y certificado denominado test_cert.

Exportación de la cadena de usuarios

Si no tiene instalada la cadena de certificados en el HSM con la nomenclatura correcta, siga estos pasos.

Abra el gestor de certificados. Puede hacerlo ejecutando el siguiente comando.
```
certmgr.msc
```
Haga doble clic en el certificado importado.
Seleccione la pestañaRuta de certificación y, a continuación, haga doble clic en la autoridad de certificación situada justo encima del certificado importado.

Seleccione pkcs#7
Seleccione la pestaña Detalles y, a continuación, haga clic en Copiar a archivo.

Copiar a archivo
Seleccione No exportar clave privada.
Seleccione Certificado PKCS#7 (.P7B).

Seleccione pkcs#7
Guarde el archivo .p7b.

Importar la cadena de usuarios

No prompt de comando executar o seguinte comando hsmcon <IP> <usuário>. E em seguida inserir a senha.

Por ejemplo
```
hsmcon 127.0.0.1 master
```

Importe la cadena de certificados. Seleccione la opción Importar, Otros y, a continuación, PKCS#7. Añada el nombre del archivo .p7b y a continuación el nombre de la cadena, siguiendo la nomenclatura.

Importación de cadenas de certificados a HSM

Dinamo - Remote Management Console v. 4.19.0.0 2018 (c) Dinamo Networks

HSM 127.0.0.1 e - Engine 5.9.0.0 (DXP) - TCA0000000  - ID master

Keys/Objects - Import - Others - PKCS#7

File (local): D:\tmp\examples\jcassl\test.p7b
File name (HSM): teste_chain

File loaded successfully.

Press ENTER key to continue...

Compruebe los objetos. En el menú principal, seleccione la opción Listar objetos.

Objeto	Tipo	Nomenclatura	Ejemplo
Clave privada	p. ej. rsa2048	gratis	`prueba`
Certificado	x.509	nombre de la clave más sufijo `_cert`	`certificado_prueba`
Cadena de certificados	pkcs#7	nombre de la clave más sufijo `_chain`	`cadena_prueba`

Los detalles de la nomenclatura pueden consultarse más arriba o en la documentación de la JCA.

Listado de objetos en HSM

Dinamo - Remote Management Console v. 4.19.0.0 2018 (c) Dinamo Networks

HSM 127.0.0.1 e - Engine 5.9.0.0 (DXP) - TCA0000000  - ID master

Keys/Objects - List


Name                                      Type                 T E Label
================================================================================
teste                                     rsa2048              n y teste_cert
teste_cert                                x.509                n y teste_cert
teste_chain                               pkcs#7               n y

Total of objects: 3

Press ENTER key to continue...

Exportación de cadenas de host remotas

Para realizar la autenticación mutua, necesitamos verificar el host remoto, y para ello necesitamos su cadena de certificados.

A continuación se muestra una forma de recuperación con fines didácticos.

Abra su navegador y vaya a la página de destino (no necesita iniciar sesión), haga clic en No seguro y luego en certificado.

Seleccionar certificado remoto
En la ventana que se abre, haz clic en Detalles, luego en Exportar y, por último, en Guardar en un archivo.

Exportar certificado remoto
Abra el certificado y realice los pasos anteriores, pero ahora para extraer la cadena del certificado del host remoto.

Creación de proyectos

Cree un proyecto estándar.

mvn archetype:generate -DgroupId=doxy.examples -DartifactId=jcassl -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Introduzca la carpeta del proyecto.
```
cd jcassl
```
Copie el archivo de ejemplo de la documentación de la API Java de HSM en la carpeta src\main\java\doxy\examples.

Elimina los archivos:
- src\main\java\doxy\examples\App.java
- src\test\java\doxy\examples\AppTest.java

Cambie el POM por el siguiente contenido:

<project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                         https://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>
<groupId>doxy.examples</groupId>
<artifactId>jcassl</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>

<name>JCASSL</name>

<properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
</properties>

<dependencies>
    <!-- Dinamo HSM SDK (external, not bundled) -->
    <dependency>
      <groupId>io.dinamonetworks.sdk</groupId>
      <artifactId>dinamo-hsm</artifactId>
      <version>4.19.0</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Compiler plugin -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <source>${maven.compiler.source}</source>
                <target>${maven.compiler.target}</target>
            </configuration>
        </plugin>

        <!-- Jar plugin to define main class -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.3.0</version>
            <configuration>
                <archive>
                    <manifest>
                        <mainClass>doxy.examples.JCASSL</mainClass>
                    </manifest>
                </archive>
            </configuration>
        </plugin>

        <!-- Exec plugin for easy run -->
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>exec-maven-plugin</artifactId>
            <version>3.1.0</version>
        </plugin>
    </plugins>
</build>

</project>

Compilar.
```
mvn clean package
```

Ejecución y pruebas de conexión

Para definir qué HSM utilizará el JCA, utilizaremos las propiedades del sistema, pero también son aceptables otras formas.

Ejecute el comando de la siguiente manera:

mvn exec:java -Dexec.mainClass="doxy.examples.JCASSL" -Ddinamo.hsm.jca.ip=`<IP DO HSM>` -Ddinamo.hsm.jca.user=`<USUÁRIO DO HSM>` -Ddinamo.hsm.jca.pwd=`<SENHA DO USUÁRIO>` -Dexec.args="`<URL DE DESTINO>` `<ARQUIVO DA CADEIA DO HOST REMOTO> ` `<ID DA CHAVE PRIVADA>`"

Por ejemplo

mvn exec:java -Dexec.mainClass="doxy.examples.JCASSL" -Ddinamo.hsm.jca.ip=127.0.0.1 -Ddinamo.hsm.jca.user=master -Ddinamo.hsm.jca.pwd=12345678 -Dexec.args="https://nfe.fazenda.sp.gov.br/ws/nfestatusservico4.asmx D:\tmp\examples\jcassl\sefaz-sp.p7b teste"

En este ejemplo debería mostrar los asuntos de los certificados en la cadena y el código html del host remoto.

Por ejemplo

mvn exec:java -Dexec.mainClass="doxy.examples.JCASSL" -Ddinamo.hsm.jca.ip=127.0.0.1 -Ddinamo.hsm.jca.user=master -Ddinamo.hsm.jca.pwd=12345678 -Dexec.args="https://nfe.fazenda.sp.gov.br/ws/nfestatusservico4.asmx D:\tmp\examples\jcassl\sefaz-sp.p7b teste"

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------< doxy.examples:jcassl >------------------------
[INFO] Building JCASSL 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- exec:3.1.0:java (default-cli) @ jcassl ---
Host chain(received from host):

[0] Subject: OID.1.3.6.1.4.1.311.60.2.1.3=BR, OID.2.5.4.15=Government Entity, CN=nfe.fazenda.sp.gov.br, SERIALNUMBER=46377222000129, L=Abadia de Goias, ST=GO, O=SECRETARIA DA FAZENDA E PLANEJAMENTO, C=BR
Issuer: CN=AC SOLUTI SSL EV G4, OU=Autoridade Certificadora Raiz Brasileira v10, O=ICP-Brasil, C=BR
[1] Subject: CN=AC SOLUTI SSL EV G4, OU=Autoridade Certificadora Raiz Brasileira v10, O=ICP-Brasil, C=BR
Issuer: CN=Autoridade Certificadora Raiz Brasileira v10, OU=Instituto Nacional de Tecnologia da Informacao - ITI, O=ICP-Brasil, C=BR

URL content:


<html>

<head><link rel="alternate" type="text/xml" href="/ws/nfestatusservico4.asmx?disco" />

<style type="text/css">

...

</style>

<title>
    NFeStatusServico4 Web Service
</title></head>

  <body>

<div id="content">

  <p class="heading1">NFeStatusServico4</p><br>

  <span>
      <p class="intro">Servi├ºo destinado ├á consulta do status do servi├ºo prestado pelo Portal da Secretaria de Fazenda Estadual.</p>
  </span>

  <span>

      <p class="intro">The following operations are supported.  For a formal definition, please review the <a href="nfestatusservico4.asmx?WSDL">Service Description</a>. </p>


          <ul>

          <li>
            <a href="nfestatusservico4.asmx?op=nfeStatusServicoNF">nfeStatusServicoNF</a>

            <span>
              <br>Consulta Status do Servi├ºo
            </span>
          </li>
          <p>

          </ul>

  </span>




<span>

</span>






  </body>
</html>
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.266 s
[INFO] Finished at: 2025-10-03T20:31:50-03:00
[INFO] ------------------------------------------------------------------------