El connector original amb Catcert disposa de dos mètodes de validació, el primer, validate, espera rebre un string amb el XML per processar la petició. El segon, validateDetStr, és un mètode de conveniència d'un entorn anterior que només permet la validació de documents amb signatura Dettached, i que espera rebre dos strings (una per al document en base 64 i l'altre per a la seva signatura).

Ambdós mètodes retornen un XML (comentat en el punt 4.1.2) que conté el resultat de la petició, els camps del certificat que s'hagin demanat cas que aquest sigui correcte i una signatura del validador.

Les noves funcionalitats d'accés a PSIS consisteixen en dues funcions que s'executen en el mateix connector i que permeten d'extraure el Hash i la Signatura d'un arxiu PDF

i dues funcions de validació, que accedeixen als serveis de PSIS:

del hash i signatura obtinguts amb les funcions anteriors
d'un PDF signat

Context i Escenaris d'Ús

El connector Catcert es troba dins els connectors de serveis funcional.

Versions i Dependències

En el present apartat es mostren quines són les versions i dependències necessàries per fer ús del Servei.

Les dependències descrites a la següent url son requerides per tal de fer funcionar el servei:
Dependències Connector amb Catcert

A qui va dirigit

Aquest document va dirigit als següents perfils:

Programador. Per conéixer l'ús del connector.
Arquitecte. Per conéixer quins són els components i la configuració del connector.

Documents i Fonts de Referència

[1]	Anàlisi Funcional - Connector Serveis Funcionals - 16-Nov.doc	Document d'anàlisi dels connectors de serveis funcionals.
[2]	acces_serveis_validacio.pdf	Frontal Serveis Web PKI - Accés als serveis de validació.

Glossari

Descripció Detallada

Arquitectura i Components

Interfícies i Components Genérics

Es pot trobar tota la documentació JavaDoc y el codi font referent aquests components a les següents urls:

JavaDoc: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-connectors-root/canigo-connectors-catcert/apidocs/index.html
Codi Font: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-connectors-root/canigo-connectors-catcert/xref/index.html

Instal.lació i Configuració

Instal.lació

La instal.lació del connector requereix de la utilització de la llibreria 'canigo-connectors-catcert' i les dependències indicades a l'apartat 'Introducció-Versions i Dependències'.

La instal.lació es realitzarà seguint el procediment habitual per components/serveis canigo.

És necesari tenir accés a la intranet de la Generalitat per poder fer proves i/o utilitzar-lo.

Configuració

L'arxiu de configuració Maven2 del projecte (pom.xml) ha d'incloure la dependència amb el connector:

<dependency>
    <groupId>canigo.connectors</groupId>
    <artifactId>canigo-connectors-catcert</artifactId>
    <version>${pom.version}</version>
</dependency>

La configuració de l'accés als webservices de PSIS es fà mitjançant l'arxiu de propietats ValidateWSLocator.properties que conté les URLs dels dos webservices:

# URL PSIS test
#WS_URL_Locator=http://psisbeta.catcert.net/psis/catcert-test/dss
#WS_URL_Locator_PDF=http://psisbeta.catcert.net/psis/catcert-test/dsspdf
#URL PSIS Producció
WS_URL_Locator=http://psis.catcert.net/psis/catcert/dss
WS_URL_Locator_PDF=http://psis.catcert.net/psis/catcert/dsspdf  
TRANSPORT_CHUNKED=false

Serà necessari el fitxer de configuració de la pròpia aplicació que utilitza el connector catcert on inclourem la utilització dels web services:

 <bean name="psisBeanConfiguration" class="net.catcert.www.ValidateWS_wsdl.ValidateWSLocatorPSIS">
		<property name="validateWSPortAddress" value="${WS_URL_Locator}"/>
		<property name="validatePDFWSPortAddress" value="${WS_URL_Locator_PDF}"/>
		<property name="configTransferChunked" value="${TRANSPORT_CHUNKED}"/>
		<property name="logService" ref="loggingService"/>
</bean>

En el fitxer de configuració dels webservices canigo-services-webservices.xml s'importarà la configuracfió del bean del connector catcert i psis:

 <?xml version="1.0" encoding="UTF-8"?>
<beans xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd" 
xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <bean abstract="true" class="net.gencat.ctti.canigo.services.webservices.impl.ImportedInterfaceImpl" id="ImportedInterfaceDefinition"/>
  <bean abstract="true" class="net.gencat.ctti.canigo.services.webservices.impl.ExportedInterfaceImpl" id="ExportedInterfaceDefinition"/>

  <bean name="WebServicesService" class="net.gencat.ctti.canigo.services.webservices.impl.WebServicesServiceImpl">
	  	<property name="exportedInterfaces">
	      <list>
	      	    ...
	      </list>
	    </property>
		<property name="importedInterfaces">
			<list>
                                <bean parent="ImportedInterfaceDefinition">
					<property name="name" value="catcertWebService" />
					<property name="serviceLocator"	value="net.catcert.www.ValidateWS_wsdl.ValidateWSLocator"/>
					<property name="localInterface" value="net.catcert.www.ValidateWS_wsdl.ValidateWSPortType"/>
				</bean>
				<bean parent="ImportedInterfaceDefinition">
					<property name="name" value="psisWebService" />
					<property name="serviceLocatorImpl"	ref="psisBeanConfiguration"/>
					<property name="serviceLocator" value="net.catcert.www.ValidateWS_wsdl.ValidateWSLocatorPSIS"/>
					<property name="localInterface"  value="net.catcert.www.ValidateWS_wsdl.ValidateWSPortTypePSIS"/>
				</bean>
			</list>
		</property>
	</bean>
</beans>

Atenció

~~L'arxiu de propietats ValidateWSLocator.properties s'ha de trobar desplegat a l'arrel del directori classes, és a dir, a l'arrel de la carpeta resources de la nostra aplicació.~~
~~Si no es troba en aquesta ubicació no es tindrà en compte la configuració.~~
Actualització
A partir de la versió 2.3.5 el fitxer pot estar en una carpeta dintre del directori de recursos, recomanem: <PROJECT_ROOT>/src/main/resources/connectors/ValidateWSLocator.properties.
Per carregar aquest fitxer cal modificar l'XML del servei de configuració canigo-services-configuration.xml i afegir aquesta entrada:

<value>classpath:connectors/ValidateWSLocator.properties</value>

Utilització del Servei

Funcions Catcert

La utilització del Connector es basa principalment en la configuració. L'ús directe des dels clients es permet mitjançant les interfícies definides.

Per utilitzar el servei Catcert instanciarem un objecte ValidateWSPortType mitjançant el servei canigo web services. Cridant després a qualsevol dels mètodes que ValidateWSPortType presenta.

Exemple d'utilització:

public void testCATCERT() {
    logDebug("Test.testCATCERT inicio");
    BeanFactory beanFactory = new ClassPathXmlApplicationContext("webServicesContext.xml");
    WebServicesService service =
    (WebServicesService) beanFactory.getBean(WebServicesService.WEB_SERVICES_BEAN_FACTORY_KEY);

    ValidateWSPortType catcert = (ValidateWSPortType) service.getWebService("catcertWebService");
    assertNotNull(catcert);

    String respuesta = null;

    try {
        String xmlData = getXmlCertificationPKCS7SignatureInputData(certificate);
        log.debug(xmlData);
        log.debug(catcert.ping());
        respuesta = catcert.validate(xmlData);
    } catch (RemoteException e) {
        logError("Error en TestCatcert.testCanigoWebServicesGoogle "+ e.getMessage());
    }
    logDebug(respuesta);
    logDebug("Test.testCATCERT fin");
}

Funcions PSIS

Les funcions internes al connector per extraure el Hash i la Signatura d'un arxiu PDF estan disponibles com a mètodes estàtics en la classe net.gencat.ctti.canigo.util.Utils i son

public static List extractSignatureFromPDF(InputStream stream) throws Exception;
public static List extractSignatureFromPDF(byte[] pdfData) throws Exception;
public static List extractHashFromPDF(InputStream stream) throws Exception;
public static List extractHashFromPDF(byte[] pdfData) throws Exception;

Aquestes funcions retornen List de byte[] amb els Hash o les Signatures dels documents PDF que es passen com InputStream o com byte[]. En l'exemple de validació de signatura i hash es pot veure l'us d'aquestes funcions.
S'injecta per spring el servei de WebServices en l'action-servlet on es vol utilitzar el servei.

<bean name="/connectorsPsis" class="net.gencat.....PSISAction">
		<property name="logService" ref="loggingService"></property>
		<property name="pojoClass" value="net.gencat.....PSISPojo"></property>
		<!-- Connectors -->
		<property name="wss" ref="WebServicesService"></property>
		...
</bean>

A l'acció s'haurà de definir els getters i setters del Servei de Webservices.

private WebServicesService wss;public WebServicesService getWss() {
	return wss;
}
public void setWss(WebServicesService wss) {
	this.wss = wss;
}

Per utilitzar el servei PSIS instanciarem un objecte ValidateWSPortTypePSIS mitjançant el servei canigo web services. Cridant després a qualsevol dels mètodes que ValidateWSPortTypePSIS presenta.

ValidateWSPortTypePSIS psis = (ValidateWSPortTypePSIS) wss.getWebService("psisWebService");

Exemples d'utilització:
Funció ping, per verificar l'accés al servei PSIS:

public void testPing() throws Exception {
    logDebug("TestPsis.testPing inicio");
    try {
        log.debug(psis.ping());
    } catch (RemoteException e) {
        logError("Error en TestPsis.testPing " + e.getMessage());
        e.printStackTrace();
    }
    logDebug("TestPsis.testPing fin");
}

Realització d'una petició genèrica. Requereix com a paràmetre d'entrada un VerifyRequestDocument i retorna un VerifyResponseDocument.
En la documentació de PSIS (Guia bàsica pels integradors de PSIS) es descriuen les peticions possibles i es donen exemples de com construir-les.

public void testValidateRequestDocument() throws Exception {
    logDebug("TestPsis.testValidateRequestDocument inici");

    String fileName = "/test/resources/CAdESBES_detached.pdf";
    File file = new File(fileName);
    int length = (int) file.length();
    FileInputStream fis = new FileInputStream(file);
    byte[] pdfData = new byte[length];
    fis.read(pdfData);

    List lFirmas = Utils.extractSignatureFromPDF(pdfData);
    List lHash = Utils.extractHashFromPDF(pdfData);

    byte[] firma = (byte[])lFirmas.get(0);
    byte[] hash = (byte[])lHash.get(0);

    VerifyRequestDocument requestDocument = Utils.getValidateHashRequestDocument(firma, hash);
    VerifyResponseDocument responseDocument = psis.validateRequestDocument(requestDocument);

    logDebug("TestPsis.testValidateRequestDocument - Rebuda resposta PSIS");
    String r1 = responseDocument.getVerifyResponse().getResult().getResultMajor();
    String r2 = responseDocument.getVerifyResponse().getResult().getResultMinor();
    logDebug("TestPsis.testValidateRequestDocument - Result: " + r1 + " - " + r2);

    logDebug("TestPsis.testValidateRequestDocument fi");
}

Realització d'una petició genèrica sobre un PDF. Requereix com a paràmetre d'entrada un VerifyRequestDocument i retorna un VerifyResponseDocument.
En la documentació de PSIS (Guia bàsica pels integradors de PSIS) es descriuen les peticions possibles i es donen exemples de com construir-les.

public void testValidateRequestDocumentPDF() throws Exception {
    logDebug("TestPsis.testValidateRequestDocumentPDF inici");

    String fileName = "D:/CANIGO/CAdESBES_detached.pdf";
    File file = new File(fileName);
    int length = (int) file.length();
    FileInputStream fis = new FileInputStream(file);
    byte[] pdfData = new byte[length];
    fis.read(pdfData);

    VerifyRequestDocument requestDocument = Utils.getValidateRequestDocument(pdfData);
    VerifyResponseDocument responseDocument = psis.validateRequestDocumentPDF(requestDocument);

    String r1 = responseDocument.getVerifyResponse().getResult().getResultMajor();
    String r2 = responseDocument.getVerifyResponse().getResult().getResultMinor();

    logDebug("TestPsis.validateRequestDocumentPDF - Result: " + r1 + " - " + r2);
    logDebug("TestPsis.testValidateRequestDocumentPDF fi");
}

Càlcul del hash, extracció de la signatura i validació del hash i signatura:

public void testValidateSignatureHash() throws Exception {
    logDebug("TestPsis.testValidateSignatureHash inici");
    String fileName = "D:/CANIGO/CAdESBES_detached.pdf";
    File file = new File(fileName);
    int length = (int) file.length();
    FileInputStream fis = new FileInputStream(file);
    byte[] pdfData = new byte[length];
    fis.read(pdfData);

    List lFirmas = Utils.extractSignatureFromPDF(pdfData);
    List lHash = Utils.extractHashFromPDF(pdfData);
    byte[] firma = (byte[])lFirmas.get(0);
    byte[] hash = (byte[])lHash.get(0);

    String resultado = psis.validateSignatureHash(firma, hash);

    log.debug("Resultado= " + resultado);
    logDebug("TestPsis.testValidateSignatureHash fin");
}

Validació d'un arxiu PDF:

public void testValidatePDF() throws Exception {
    logDebug("TestPsis.testValidatePDF inici");
    log.debug(psis.validatePDF("D:/CANIGO/CAdESBES_detached.pdf"));
    logDebug("TestPsis.testValidatePDF fin");
}

Validació d'un pdf amb una signatura externa:

public void testValidateDetStr() throws Exception {
    logDebug("TestPsis.testValidateDetStr inici");
    log.debug(psis.validateDetStrPSIS("cadesDetached-PDF.pdf","signatureDetached.p7s"));
    logDebug("TestPsis.testValidateDetStr fin");
}

Integració amb Altres Serveis

Integració amb el Servei de Internacionalització

En els fitxers de configuració es defineixen claus que permeten especificar quins missatges retornar en cas errors. Per a poder traduir aquestes claus és necessari especificar que el connector usarà el Servei d'Internacionalització (veure Configuració).