Interfaz de servicio web

Introducción

La interfaz de servicio web JAX-WS 2.0 se utiliza para acceder remotamente a las funciones básicas mediante HTTPS autenticado por el cliente. La funcionalidad disponible a través de la interfaz de servicio web está documentada en la Referencia de la API de servicios web EJBCA .

También existe una CLI que permite ejecutar scripts de llamadas a servicios web de forma remota (consulte Uso de la CLI de servicios web) . Tenga en cuenta que no todas las llamadas a servicios web están disponibles a través de la CLI.

Al usar la API de WS, asegúrese de que wsdl-host y modify-wsdl-address estén configurados como parte de la configuración de TLS. Para obtener más información, consulte las instrucciones específicas del servidor de aplicaciones en Servidores de aplicaciones .

Servicios web a través de la RA

Usando una RA conectada entre pares, es posible ejecutar un subconjunto de llamadas a la API de WS a través de la RA. Estas llamadas se intentan ejecutar primero en la CA tras el sondeo de esta mediante conectores entre pares. Si la RA tiene CA activas, intenta procesar las solicitudes primero localmente, a menos que se indique lo contrario en la lista a continuación.

La generación y recuperación de clave local se procesa en la RA en todos los casos (consulte la función 'keyRecover').

La configuración del rol del usuario de la API de WS se realiza en la CA, y WS debe estar habilitado en el rol utilizado por la conexión de pares para la RA. En la RA, es posible deshabilitar WS en la configuración del sistema.

El subconjunto de llamadas API disponibles a través de RA son:

  • Solicitud de certificado

  • checkRevokationStatus (en cualquier momento en que se intente procesar primero en la CA)

  • Solicitud de crmf

  • registro personalizado

  • Solicitud cvc

  • editUser (en cualquier momento en que se intentó procesar primero en la CA)

  • encontrarCerts

  • buscarUsuario

  • obtener CA disponibles

  • obtenerCAsDisponiblesEnPerfil

  • obtenerPerfilesDeCertificadoDisponibles

  • obtenerCertificado

  • obtenerCertificadosPorTiempoDeExpiración

  • Obtener certificados por fecha de vencimiento y emisor

  • Obtener certificados por tiempo de vencimiento y tipo

  • obtenerÚltimaCadenaCA

  • obtenerÚltimaCadenaDeCertificados

  • obtener la última CRL

  • obtenerPerfil

  • obtenerLongitudDeColaDePublicador

  • obtenerNúmeroRestanteDeAprobaciones

  • está aprobado

  • está autorizado

  • keyRecover (generación o recuperación de almacén de claves local procesada únicamente en la RA)

  • Solicitud pkcs10

  • pkcs12Req

  • republicarCertificado

  • revokeCert (en cualquier momento en que se intente procesar primero en la CA)

  • revokeCertBackdated (en cualquier momento en que se intente procesar primero en la CA)

  • revokeCertWithMetadata (en cualquier momento en que se intente procesar primero en la CA)

  • revocarUsuario

Autenticación de servicios web

La interfaz de Servicios Web requiere la autenticación del certificado de cliente por parte de los administradores, al igual que la GUI de administración. Si tiene un certificado de cliente que funciona en la GUI de administración, también debería poder usarlo para la interfaz de Servicios Web.

Configuración del comportamiento de los servicios web

El archivo de propiedades de ejemplo conf/jaxws.properties.sample contiene más información sobre cómo configurar el comportamiento del WS EJBCA. Cópielo en conf/jaxws.properties , edítelo y vuelva a implementarlo.

Si la información del perfil de entidad final se debe utilizar para definir valores predeterminados cuando crea un usuario, se debe seleccionar la opción Permitir combinar DN en todas las interfaces en el perfil de entidad final; consulte Campos de perfiles de entidad final .

Si existen varias instancias de un componente, la fusión se realiza desde el final hasta el principio y los valores restantes de este tipo de componente se colocarán al final.

Por ejemplo, si desea fusionar:

dn=cn=foo,..., dc =dc1, ..., dc =dc2, ...

con

dn=..., dc =mdc1, ..., dc =mdc2, ..., dc =mdc3, ...

El resultado será:

dn=cn=foo, ..., dc =mdc1, ..., dc =mdc2, ..., dc =mdc3, ...

Configuración de servicios web CLI

Edite dist/ejbca-ws-cli/ejbcawsracli.properties antes de ejecutar la CLI de WS de EJBCA. Los archivos contienen descripciones de lo que se puede configurar. Tenga en cuenta que este directorio se vuelve a crear cada vez que compila EJBCA, así que cópielo en una ubicación diferente si desea reconstruir o volver a implementar EJBCA y conservar la configuración.

La configuración de la CLI de Servicios Web requiere un almacén de claves P12 o JKS. Puede probar la CLI de WS con el almacén de claves superadmin.p12 generado durante la instalación o generar un nuevo JKS mediante la GUI de administración.

Para crear un JKS para un usuario mediante la línea de comandos y agregar el nuevo usuario al rol de superadministrador, ejecute lo siguiente:

bin /ejbca .sh ra addendentity <1> <2> "C=..,O=..,CN=<1>" ManagementCA 1 JKS
bin /ejbca .sh ra setclearpwd <1> <2>
bin /ejbca .sh batch <1>
bin /ejbca .sh roles addmember "Temporary Super Administrator Group" ManagementCA WITHCOMMONNAME EQUALCASEINS <1>

Uso de la CLI de servicios web

La caja de herramientas del cliente EJBCA incluye una herramienta CLI de servicio web.

Para usar el cliente CLI de servicios web, copie el directorio con todos los archivos incluidos en el equipo desde el que desea realizar la administración remota. A continuación, cree un archivo JKS o P12 con los permisos de acceso adecuados (consulte "Reglas de acceso necesarias al usar la API de servicios web ") y, por último, configure el archivo ejbcawsracli.properties. En este archivo, debe especificar el nombre de host del servidor de CA, el nombre del almacén de claves y la contraseña para desbloquearlo. La configuración se encuentra en el archivo ejbcacsracli.properties.

Para enumerar cada subcomando, ejecute:

ejbcaClientToolBox.sh EjbcaWsRaCli

Para ver ayuda detallada sobre el uso de la CLI, ejecute:

ejbcaClientToolBox.sh EjbcaWsRaCli "subcommand"

Ejemplo de uso:

ejbcaClientToolBox.sh EjbcaWsRaCli pkcs12req testuser2 foo123 2048 NONE tmp
ejbcaClientToolBox.sh EjbcaWsRaCli revokeendentity testuser2 SUPERSEDED fals

Un ejemplo de flujo de trabajo para agregar una entidad final y realizar una solicitud con una CSR podría verse así:

./ejbcaClientToolBox.sh EjbcaWsRaCli edituser testuser foo123 false "CN=testuser" NULL NULL ManagementCA 1 USERGENERATED NEW END_ENTITY_PROFILE CERTIFICATE_PROFILE NULL
./ejbcaClientToolBox.sh EjbcaWsRaCli pkcs10req testuser foo123 csr.pem PEM NONE .

En cambio, las dos llamadas se pueden combinar en una sola transacción utilizando la eficiente llamada certreq WS:

./ejbcaClientToolBox.sh EjbcaWsRaCli certreq testuser "CN=testuser" NULL ManagementCA END_ENTITY_PROFILE CERTIFICATE_PROFILE csr.pem PKCS10 PEM NONE .

Si su CA requiere aprobaciones para emitir certificados, utilice el proceso bidireccional y verifique si se han completado las aprobaciones según el siguiente ejemplo:

./ejbcaClientToolBox.sh EjbcaWsRaCli edituser testuser foo123 false "CN=testuser" NULL NULL ManagementCA 1 USERGENERATED NEW EMPTY ENDUSER NULL
<...>
Waiting for approval: Add Entity request has been added for approval by authorized administrators.
Approval requestID: 1845592727
# If you now try to enroll you will get an error, since the above edituser command has not been executed:
./ejbcaClientToolBox.sh EjbcaWsRaCli pkcs10req testuser foo123 ~/tmp/ 1 .csr PEM NONE .
Error: USER_WRONG_STATUS: null
org.ejbca.ui.cli.ErrorAdminCommandException: org.ejbca.core.protocol.ws.client.gen.EjbcaException_Exception: Got request with status GENERATED ( 40 ), NEW, FAILED or INPROCESS required: testuser.
# You can run a command to check how many approvals are remaining, use this to poll the CA for when the request is approved (don't poll too often though):
./ejbcaClientToolBox.sh EjbcaWsRaCli getremainingnumberofapprovals 1845592727
Approvals remaining: 1
# Approve the request in RA GUI (or Admin GUI), and check again:
./ejbcaClientToolBox.sh EjbcaWsRaCli getremainingnumberofapprovals 1845592727
Approvals remaining: 0
# Now you can enroll:
./ejbcaClientToolBox.sh EjbcaWsRaCli pkcs10req testuser foo123 ~/tmp/ 1 .csr PEM NONE .

Depuración de TLS de CLI de servicios web

Dado que la API de WS y la CLI de WS utilizan autenticación de certificado de cliente, tanto el servidor como el cliente deben estar configurados correctamente. La CLI de WS se configura en el archivo ejbcawsracli.properties y el servidor se configura durante la instalación.

Pueden surgir problemas cuando se utilizan certificados de cliente emitidos por una CA distinta a la que emite el certificado del servidor (y se necesitan agregar más CA al almacén de confianza del servidor) o cuando se utiliza un proxy antes del servidor de CA (y se necesita configurar la autenticación de cliente TLS y el paso a través en el proxy).

<p Para solucionar el problema, habilite la depuración TLS para imprimir la información completa de depuración TLS de Java al ejecutar clientToolBox. Para habilitar la depuración TLS, configure la siguiente variable de entorno antes de ejecutar la CLI:

export JAVA_OPT=-Djavax.net.debug=all
./ejbcaClientToolBox.sh ...

Uso de la API de servicio web para la integración

Puede utilizar la interfaz de servicio web para integrar EJBCA desde otras aplicaciones.

Si usa un lenguaje distinto a Java, comience descargando el archivo WSDL en http://hostname:8080/ejbca/ejbcaws/ejbcaws?wsdl. Con esto, podrá usar sus herramientas de lenguaje de programación para generar stubs de cliente.

Al usar Java, puede encontrar las bibliotecas necesarias en dist/ejbcawscli y su subdirectorio lib .

Para inicializar el servicio web mediante TLS con certificado de cliente:

CryptoProviderTools.installBCProvider();
String urlstr = "https://localhost:8443/ejbca/ejbcaws/ejbcaws?wsdl" ;
System.setProperty( "javax.net.ssl.trustStore" , "p12/wstest.jks" );
System.setProperty( "javax.net.ssl.trustStorePassword" , "foo123" );
System.setProperty( "javax.net.ssl.keyStore" , "p12/wstest.jks" );
System.setProperty( "javax.net.ssl.keyStorePassword" , "foo123" );
QName qname = new QName( "http://ws.protocol.core.ejbca.org/" , "EjbcaWSService" );
EjbcaWSService service = new EjbcaWSService(new URL(urlstr),qname);
ejbcaraws = service.getEjbcaWSPort();

Al usar Java 11 no siempre funciona configurar las propiedades anteriores, y las líneas System.setProperty anteriores se pueden reemplazar con la inicialización directa del SSLSocketFactory predeterminado:

HttpsURLConnection.setDefaultSSLSocketFactory(getSSLFactory(p12/wstest.jks, "foo123" .toCharArray()));

Ejemplo de código WS para buscar todos los usuarios que tienen 'Smith' en su DN de asunto:

UserMatch usermatch = new UserMatch();
usermatch.setMatchwith(UserMatch.MATCH_WITH_DN);
usermatch.setMatchtype(UserMatch.MATCH_TYPE_CONTAINS);
usermatch.setMatchvalue( "Smith" );
List<UserDataVOWS> result = ejbcaraws.findUser(usermatch);

Ejemplo de generación de un certificado a partir de una solicitud PKCS10:

UserDataVOWS user1 = new UserDataVOWS();
user1.setUsername( "WSTESTUSER1" );
user1.setSubjectDN( "CN=WSTESTUSER1" );
user1.setCaName( "ManagementCA" );
user1.setEmail(null);
user1.setSubjectAltName(null);
user1.setEndEntityProfileName( "EMPTY" );
user1.setCertificateProfileName( "ENDUSER" );
KeyPair keys = KeyTools.genKeys( "2048" , AlgorithmConstants.KEYALGORITHM_RSA);
PKCS10CertificationRequest pkcs10 = new PKCS10CertificationRequest( "SHA256WithRSA" ,
CertTools.stringToBcX500Name( "CN=NOUSED" ), keys.getPublic(), null, keys.getPrivate());
CertificateResponse certenv = ejbcaraws.certificateRequest(user1,
CertificateHelper.CERT_REQ_TYPE_PKCS10,
new String(Base64.encode(pkcs10.getEncoded())),
null, CertificateHelper.RESPONSETYPE_CERTIFICATE);
X509Certificate cert = certenv.getCertificate();

Ejemplo de comprobación del estado de revocación de un certificado:

RevokeStatus revokestatus = ejbcaraws.checkRevokationStatus(cert.getIssuerDN.toString,cert.getSerialNumber().toString( 16 ));
if (revokestatus != null ){
if (revokestatus.getReason() != RevokeStatus.NOT_REVOKED)){
// Certificate is revoked
} else {
// Certificate isn't revoked
}
} else {
// Certificate doesn't exist
}

Desarrollo contra la API SOAP de servicios web

La API SOAP es compatible con todos los lenguajes de desarrollo que gestionan mensajes SOAP, incluyendo lenguajes de programación como Java, C# y PHP. Normalmente, se utilizan las herramientas de los lenguajes de programación para generar stubs de cliente, que son clases que se usarán en el programa cliente. En Java, estas clases stub ya están incluidas en el cliente clientToolBox WS.

Los stubs de cliente se generan a partir del archivo WSDL, que incluye toda la información para usar la API de WS. Se puede acceder al WSDL desde el EJBCA instalado en https://localhost:8443/ejbca/ejbcaws/ejbcaws?wsdl. En el WSDL se describen todos los métodos y parámetros, pero no se proporciona documentación detallada. Por ejemplo, se describe lo siguiente en el WSDL para el método getProfile :

<xs:complexType name= "getProfile" >
<xs:sequence>
<xs:element name= "arg0" type= "xs:int" />
<xs:element minOccurs= "0" name= "arg1" type= "xs:string" />
</xs:sequence>
</xs:complexType>

El método arg0 tiene dos parámetros: un entero y arg1, una cadena. La documentación de la API de WS de Javadoc contiene descripciones detalladas de los argumentos; consulte la documentación de la API de WS y, específicamente, EjbcaWS .

La documentación de la API abarca los métodos para los parámetros, el valor de retorno, los privilegios necesarios para usar el método (según el certificado de cliente TLS) y los errores que pueden ocurrir, que se devuelven como clases de error SOAP. Por ejemplo, se documenta lo siguiente para el método getProfile :

Parameters:
profileId - ID of the profile we want to retrieve.
profileType - The type of the profile we want to retrieve. 'eep' for End Entity Profiles and 'cp' for Certificate Profiles
Returns:
a byte array containing the specified profile in format XML

Ahora puede usar sus stubs de cliente, en su lenguaje de programación preferido, para llamar al método getProfile de WS SOAP con un parámetro entero y uno de cadena, obteniendo un perfil en formato XML.

Código de muestra

Consulte el archivo modules/ejbca-ws/src/org/ejbca/core/protocol/ws/common/IEjbcaWS para obtener instrucciones más detalladas sobre la API. Puede encontrar un código de ejemplo en:

Depuración de mensajes de servicios web

Una herramienta muy útil al desarrollar contra la API de WS, especialmente si no se utiliza la CLI de clientToolBox, sino que se integra desde el propio código, es revisar los mensajes SOAP para ver si funcionan. De esta manera, se puede:

  • Ejecute clientToolBox para probar un flujo de trabajo, utilizando la CLI oficial .

  • Depure los mensajes SOAP según lo siguiente.

  • Verifique que su código produzca los mismos mensajes SOAP.

  • Mira en los mensajes SOAP devueltos cómo obtener la información, también de las excepciones.

Registre los mensajes SOAP para facilitar la depuración, agregando lo siguiente a JAVA_OPTS:

-Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump= true

En JBoss 7/EAP6/WildFly 9 y 10, esto se puede hacer añadiendo la línea anterior a JAVA_OPTS en JBOSS_HOME/bin/standalone.conf. Por ejemplo:

if [ "x$JAVA_OPTS" = "x" ]; then
JAVA_OPTS= "-Xms1303m -Xmx1303m -XX:MetaspaceSize=256M -XX:MaxMetaspaceSize=512m -Djava.net.preferIPv4Stack=true"
JAVA_OPTS= "$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
else
echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"
fi
JAVA_OPTS= "$JAVA_OPTS -Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true"

Reglas de acceso necesarias al utilizar la API de servicio web

Todas las llamadas requieren autenticación de cliente HTTPS. El almacén de claves utilizado debe estar configurado como administrador y las reglas de acceso deben ser las siguientes:

Común para todas las llamadas (excepto isAuthorized, existsHardToken, isApproved que solo necesitan un certificado confiable válido):

  • /administrador

  • /ca/'CA relacionada'

editarUsuario:

  • /ra_functionality/crear_entidad_final y/o editar_entidad_final

  • / endentityprofilesrules / perfil de entidad final del usuario /create_end_entity y/o edit_end_entity

buscarUsuario, buscarCertificado:

  • /ra_funcionalidad/entidad_final_vista

  • /ra_functionality/perfil de entidad final del usuario/view_end_entity

Solicitud pkcs10, pkcs12req:

  • /ra_funcionalidad/entidad_final_vista

  • /ra_functionality/edit_end_entity (solo se requiere para recuperación sin clave)

  • /ra_functionality/keyrecovery (solo necesario para la recuperación de clave)

  • /ra_functionality/perfil de entidad final del usuario/view_end_entity

  • / endentityprofilesrules / perfil de entidad final del usuario /keyrecovery (solo requerido para recuperación de clave)

  • / endentityprofilesrules / perfil de entidad final del usuario /keyrecovery (solo se requiere para recuperación sin clave)

  • /ca_funcionalidad/crear_certificado

Solicitud de certificado, solicitud de token suave:

  • /ra_functionality/crear_entidad_final y/o editar_entidad_final

  • / endentityprofilesrules / perfil de entidad final del usuario /create_end_entity y/o edit_end_entity

  • /ca_funcionalidad/crear_certificado

revokeCert, revokeToken: estas llamadas admiten aprobaciones.

  • /ra_funcionalidad/revocar_entidad_final

  • / endentityprofilesrules / perfil de entidad final del usuario /revoke_end_entity

revokeUser: Esta llamada admite aprobaciones.

  • /ra_funcionalidad/revocar_entidad_final

  • / endentityprofilesrules/ perfil de entidad final del usuario /revoke_end_entity

  • /ra_functionality/delete_end_entity (solo si se deben eliminar los usuarios)

  • /endentityprofilesrules /perfil de entidad final del usuario/delete_end_entity (solo si se deben eliminar usuarios)

fetchUserData: Es posible desactivar la autorización de esta llamada en jaxws.properties

  • /userdatasourcesrules/'fuente de datos del usuario'/fetch_userdata

genTokenCertificate: Importante: esta llamada también admite aprobaciones. El comportamiento predeterminado es que, cuando alguien sin acceso "/administrator" crea una llamada, se creará una GenerateTokenApprovalRequest. Este comportamiento se puede desactivar en el archivo jaxws.properties.

  • /ra_functionality/crear_entidad_final y/o editar_entidad_final

  • /endentityprofilesrules/ perfil de entidad final del usuario/ create_end_entity y/o edit_end_entity

  • /ra_functionality/revoke_end_entity (si el indicador de sobrescritura está configurado)

  • /endentityprofilesrules/ finaliza el perfil de entidad del usuario /revoke_end_entity (si está configurado el indicador de sobrescritura)

  • /ca_funcionalidad/crear_certificado

  • /ca/'ca de todos los certificados solicitados'

republicarCertificado:

  • /ra_funcionalidad/entidad_final_vista

  • /endentityprofilesrules/ perfil de entidad final del usuario /view_end_entity

customLog: No se requiere regla de acceso de CA.

  • /secureaudit/log_custom_events (debe configurarse en modo avanzado al editar reglas de acceso)

eliminarDatosDeUsuarioDeFuente:

  • /userdatasourcesrules/'fuente de datos del usuario'/remove_userdata (para todas las fuentes de datos del usuario indicadas)

getCertificate: no se requiere el indicador '/administrator'

  • /ca_functionality/ver_certificado

Respuesta de certificado de ca, solicitud de renovación de certificado de ca:

  • /ca_funcionalidad/renovar_ca

createCryptoToken (disponible solo en la edición Enterprise):

  • /cryptotoken/modificar

generateCryptoTokenKeys (disponible solo en Enterprise Edition):

  • /cryptotoken/keys/generate/'CryptoToken relacionado'

createCA (disponible solo en Enterprise Edition):

  • /

addSubjectToRole, removeSubjectFromRole (disponible solo con Enterprise Edition):

  • /ca/'CA relacionadas (todas las CA que emitieron los certificados de cada miembro en el rol relacionado)'

  • /funcionalidad_del_sistema/editar_privilegios_de_administrador

obtenerCertificadosPorHoraDeExpiración, obtenerCertificadosPorHoraDeExpiraciónYEmisor, obtenerCertificadosPorHoraDeExpiraciónYTipo:

  • No se requieren otras reglas de acceso

Códigos de error en los servicios web

Se han agregado códigos de error comercial para discriminar excepciones de tipo EjbcaException.

El siguiente ejemplo de código muestra cómo utilizar códigos de error:

try {
ejbcaraws.editUser(user1);
} catch(EjbcaException_Exception e) {
if (org.cesecore.ErrorCode.CERT_PROFILE_NOT_EXISTS.getInternalErrorCode().equals(e.getFaultInfo().getErrorCode().getInternalErrorCode())) {
log.error( "No such certifcate profile." );
}
}

Los códigos de error se describen en org.cesecore.ErrorCode y src/test/org/ejbca/core/protocol/ws/CommonEjbcaWSTest.java.

Registro de transacciones de WS

El registro de transacciones de WS se realiza de manera similar al registro del respondedor OCSP, consulte Auditoría y registro de cuentas de OCSP .

Sin embargo, tenga en cuenta que se utilizan etiquetas diferentes:

  • LOG_TIME: La hora en que se realizó la llamada

  • SESSION_ID: una cadena aleatoria de 32 bytes de longitud generada cuando se inicia el respondedor OCSP.

  • LOG_ID: Un número entero que identifica que comienza en 1 y se incrementa con cada solicitud recibida.

  • REPLY_TIME: El tiempo que tardó en regresar del método WS.

  • MÉTODO: Nombre del método WS llamado.

  • ERROR_MESSAGE: Un mensaje de error con información sobre el error. Si la llamada se devolvió correctamente, se indica "NO_ERROR".

  • ADMIN_DN: DN del sujeto para el certificado del cliente en la llamada.

  • ADMIN_ISSUER_DN: DN del emisor del certificado del cliente en la llamada

<p La configuración se especifica en conf/jaxws.properties. En la configuración del registrador de JBoss, utilice org.ejbca.core.protocol.ws.logger.TransactionLogger como nombre de categoría para el appender.

Secciones de ejemplo para un JBoss standalone.xml para habilitar el registro de transacciones de WS:

<size-rotating-file-handler name= "WSTRANS" autoflush= "true" >
<formatter>
<named-formatter name= "PATTERN" />
</formatter>
<file relative-to= "jboss.server.log.dir" path= "wstrans.log" />
<rotate-size value= "100M" />
<max-backup-index value= "10" />
<append value= "true" />
</size-rotating-file-handler>
<logger category= "org.ejbca.core.protocol.ws.logger.TransactionLogger" >
<level name= "DEBUG" />
<handlers>
<handler name= "WSTRANS" />
</handlers>
</logger>