Guide de l'application cliente des Web Services de ...esante.gouv.fr/sites/default/files/...Cliente_WebServices_V1.1.5.pdf · Guide application cliente – Webservices de consultation

Spécifications Fonctionnelles Détaillées

Guide de l’application cliente des Web Services de l’Annuaire Santé

Identification du document

Référence Annuaire_sante_fr_Guide_App_Cliente_WebServices_V1.1.5.docx

Date de création 15/05/2013

Date de dernière mise à jour 04/12/2013

Etat Validé

Version V1.1.5

Classification Confidentiel - Non public

Nombre de pages 21

Historique du document

Version Date Auteur Commentaires

V0.0.1 15/05/13 ASIP Santé Initialisation du document

V1.0.0 28/06/13 ASIP Santé Version pour diffusion

Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13

Classification : public 2 / 21

Documents de référence

Référence Descriptif

[ref 1] Annuaire_sante_fr_DSFT_WebServices_Consultation Dossier des spécifications Fonctionnelles et techniques des Webservices du repertoire annuaire.santé.fr

[ref 2] NAS-Ressources terminologiques utilisées par le RASS NAS - Ressources terminologiques associées aux données publiées par le répertoire annuaire.sante.fr

[ref.3 ] CI-SIS : EVOLUTION DU VIHF : PROFIL POUR ANNUAIRE DE PROFESSIONNEL DE SANTÉ

CI-SIS : Evolution du VIHF : profil pour annuaire de professionnel de santé

http://esante.gouv.fr/sites/default/files/NAS-Ressources_terminologiques_des_donnees_RPPS_V1.0.0.pdf

http://esante.gouv.fr/sites/default/files/EVOLUTIONVIHF-PROFIL_Annuaire_20130614_v1.0.0.pdf

http://esante.gouv.fr/sites/default/files/EVOLUTIONVIHF-PROFIL_Annuaire_20130614_v1.0.0.pdf



Sommaire

1. Introduction ..................................................................................................................... 4

1.1 Objet du document ..................................................................................................................... 4

1.2 Documents relatifs ...................................................................................................................... 4

1.3 Fonctions implémentées ............................................................................................................. 4

1.4 Avertissement ............................................................................................................................. 4

2. Application cliente ............................................................................................................ 5

2.1 Contenu....................................................................................................................................... 5

2.2 Description des sources .............................................................................................................. 5

2.2.1 Dossier src/main/java .................................................................................................... 5

2.2.2 Dossier src/main/resources ........................................................................................... 7

2.2.3 Dossier src/test/java ...................................................................................................... 7

2.2.4 Dossier src/test/resources ............................................................................................. 8

2.3 Description détaillée des classes ................................................................................................ 8

2.3.1 Dossier src/main/java .................................................................................................... 8

2.3.2 Dossier src/test/java .................................................................................................... 11

2.4 Configuration de l’application cliente ....................................................................................... 12

2.4.1 Fichier de configuration ............................................................................................... 12

2.4.2 Authentification ........................................................................................................... 13

2.4.3 Utilisation derrière un proxy ........................................................................................ 14

3. Principes de fonctionnement .......................................................................................... 14

3.1 Connexion sécurisée TLS mutuelle ........................................................................................... 14

3.2 Authentification directe (carte CPS) ......................................................................................... 15

3.2.1 Extraction des informations de la carte CPS ................................................................ 15

3.2.2 Signature des données avec la carte CPS ..................................................................... 15

3.3 Authentification indirecte (certificats établissement) .............................................................. 16

3.3.1 Obtenir l’accès aux méthodes du certificat PKCS12 .................................................... 16

3.4 Jeton VIHF ................................................................................................................................. 16

3.4.1 Structure du jeton VIHF................................................................................................ 16

3.4.2 Construction du jeton VIHF .......................................................................................... 16

4. Installation de l’application cliente ................................................................................. 18

4.1 Prérequis ................................................................................................................................... 18

4.2 Installation ................................................................................................................................ 18

4.3 Remarques ................................................................................................................................ 19

4.4 Configuration de l’application cliente ....................................................................................... 19

4.5 Exécution des tests ................................................................................................................... 19

5. Tests avec SoapUI ........................................................................................................... 21



1. Introduction

1.1 Objet du document

La lecture des spécifications des contrats d’interfaces des Web Services permettant la consultation des données rattachées aux personnes morales et physiques de l’Annuaire Santé, est un prérequis à la compréhension de l’application cliente.

1.2 Documents relatifs

Dossier de spécifications fonctionnelles et techniques détaillées des Web Services de consultation.

Cadre d’interopérabilité des SIS (Volet Synchrone pour Client Lourd).

1.3 Fonctions implémentées

Les principales fonctions implémentées par l’application cliente sont :

Authentification par carte ou par certificat serveur ;

Génération d’un jeton VIHF ;

Etablissement d’une connexion sécurisée TLS ;

Génération des requêtes Soap des clients des quatre web services de consultation des données des personnes physiques et des personnes morales :

1. Client du Web Service de recherche de personnes physiques ;

2. Client du Web Service de consultation des données d’une ou de plusieurs personnes physiques ;

3. Client du Web service de recherche de personnes morales ;

4. Client du Web Service de consultation des données d’une ou de plusieurs personnes morales.

1.4 Avertissement

Les codes sources sont fournis « tels quels », sans support. L’attention du partenaire est appelée sur les modalités d’utilisation du code exemple. Ce dernier est fourni à titre d’information permettant au partenaire de réaliser librement l’adaptation personnalisée nécessaire à la création de l’interfaçage de son logiciel. L’ASIP Santé en garantit la pertinence intrinsèque mais pas l’utilisation in situ chez le partenaire. Le partenaire est seul responsable des bonnes conditions de son utilisation et libre de s’inspirer des éléments fournis et de les adapter par ses propres moyens à la situation particulière de la solution logicielle qu’il développe. Ainsi notamment, il est déconseillé de procéder par voie de copier-coller du code à partir des exemples fournis. L’ASIP Santé décline toute responsabilité en cas de mauvaise mise en œuvre du code exemple.



2. Application cliente

2.1 Contenu

L’application cliente est livrée sous forme d’archive au format zip : annuaire-sante-webservices-client-

<version>-src.zip, contenant un projet Java configuré sous l’IDE Eclipse. L’archive décompressée donne lieu au dossier annuaire-sante-webservices-client-<version>, dont le contenu est le suivant :

Dossier Description

.settings Dossier de configuration du projet Eclipse

Certificates Dossier contenant les certificats P12 et les keystore d’authentification

repo Dossier contenant une structure de repository Maven propre au projet pour embarquer le jar client des Web Services de consultation annuaire-sante-wsclient-<version>.jar, ce dernier contient les fichiers WSDL et XSD des Web Services

src/main/java Dossier contenant les sources des classes java

src/main/resources Dossier contenant les ressources utiles à l’exécution des classes de l’application cliente (fichiers de configurations, keystores,...)

src/test/java Dossier contenant les sources des classes java des tests JUnit des services (permet l’exécution des web-services)

src/test/resources Dossier contenant les ressources utiles à l’exécution des classes de test (fichiers de test, ...)

.classpath Fichier de configuration du classpath du projet Eclipse

.project Fichier de configuration principal du projet Eclipse

pom.xml Fichier de configuration Maven pour le projet

assembly.xml Fichier de configuration de l’assemblage des sources pour Maven

2.2 Description des sources

L’application cliente contient les packages suivants :

2.2.1 Dossier src/main/java

Ce dossier est le dossier source principal de l’application cliente. Il contient les packages suivants :

2.2.1.1 Package fr.sante.annuaire.webservices.client.authentification

Ce package contient la classe de service d'appel au gestionnaire du jeton VIHF et de la connexion TLS.



2.2.1.2 Package fr.sante.annuaire.webservices.client.certificate

Ce package contient les classes représentant les données contenues dans le certificat ainsi que la classe GetX509CertificateInfo permettant de les extraire d’un certificat X509.

2.2.1.3 Package fr.sante.annuaire.webservices.client.common.vihf

Ce package contient les classes représentant le jeton VIHF.

2.2.1.4 Package fr.sante.annuaire.webservices.client.consultation

Ce package contient les classe d’implémentation des clients des Web Services de consultation de(s) personne(s) morale(s) et physique(s).

2.2.1.5 Package fr.sante.annuaire.webservices.client.examples.donnees

Ce package contient la classe récupérant les données d'exemple d’un professionnel de santé depuis sa carte CPS ou depuis le fichier de configuration.

2.2.1.6 Package fr.sante.annuaire.webservices.client.exception

Ce package contient une classe d’exception générique utilisée par les clients des web services

2.2.1.7 Package fr.sante.annuaire.webservices.client.pkcs11

Ce package contient toutes les classes nécessaires pour accéder à la carte CPS via le wrapper PKCS11.

2.2.1.8 Package fr.sante.annuaire.webservices.client.pkcs12

Le package pkcs12 contient la classe Pkcs12Impl implémentant l’interface Pkcs12 offrant l’accès au certificat PKCS12. Ce certificat se trouve dans les ressources du projet.

2.2.1.9 Package fr.sante.annuaire.webservices.client.recherche

Ce package contient les classe d’implémentation des clients des Web Services de recherche de(s) personne(s) morale(s) et physique(s).

2.2.1.10 Package fr.sante.annuaire.webservices.client.security.vihf

Ce package contient les classe d’implémentation du jeton VIHF à l’aide de la librairie OpenSAML.

Remarque : les données du VIHF sont à valoriser dynamiquement en fonction des données de l’utilisateur connecté (lues sur la carte CPS en authentification directe ou récupérées du fichier de configuration en authentification indirecte).

2.2.1.11 Package fr.sante.annuaire.webservices.client.soapservice

Ce package contient la classe qui gère la mise en place du VIHF dans les messages et la connexion.

2.2.1.12 Package fr.sante.annuaire.webservices.client.util

Ce package est un utilitaire où l’on retrouve différentes classes nécessaires au projet.



2.2.1.13 Package fr.sante.annuaire.webservices.client.vihf

Ce package contient les différents handlers de VIHF.

2.2.1.14 Package fr.sante.annuaire.webservices.client.xades

Ce package contient des classes nécessaires à la signature XAdES.

2.2.2 Dossier src/main/resources

Ce dossier est le dossier de ressources principal de l’application cliente. Il contient les éléments suivants :

2.2.2.1 Package fr.sante.annuaire.webservices.client.xades

Ce package contient notamment des fichiers magasins de certificat Java (mot de passe = « changeit ») permettant de fournir la « chaine de certification » des certificats de signature CPS2bis 2020 (racine des certificats de personnes morales) ou CPS2ter 2020 (racine des cartes CPx, prorogée en 2012), dans la signature XAdES (éléments fils de SigningCertificate) :

Fichier Contenu

truststoreCps.jks AC racines des certificats réels

truststoreCpsTest.jks AC racines des certificats de test ; inutile en production

keystoreCps.jks AC intermédiaires des certificats réels

keystoreCpsTest.jks AC intermédiaires des certificats de test ; inutile en production

2.2.2.2 Fichier config.properties

Le fichier config.properties contient les propriétés utilisées par l’application cliente (URL des services, chemins des certificats, etc…).

2.2.2.3 Fichier cxf-client.xml

Le fichier cxf-client.xml contient la configuration CXF (framework des Web Services)

2.2.2.4 Fichier log4j.xml

Le fichier log4j.xml contient la configuration pour les logs.

2.2.3 Dossier src/test/java

Ce dossier est le dossier source de test de l’application cliente. Il contient les packages suivants :

2.2.3.1 Package fr.sante.annuaire.webservices.client.test

Ce package contient les classe d’implémentation des tests des Web Services de consultation et de recherche des personnes morales et physiques.

2.2.3.2 Package fr.sante.annuaire.webservices.client.test.util

Package utilitaire où l’on retrouve une classe de constantes pour les classes de test.



2.2.4 Dossier src/test/resources

Ce dossier est le dossier de ressources de test de l’application cliente. Il contient les éléments suivants :

2.2.4.1 Package fr.sante.annuaire.webservices.client.consultation

Ce package contient les fichiers de test des Web Services de consultation des personnes morales et physiques. Il s’agit de fichiers properties contenant les critères de consultation des personnes morales ou physiques.

2.2.4.2 Package fr.sante.annuaire.webservices.client.recherche

Ce package contient les fichiers de test des Web Services de recherche des personnes morales et physiques. Il s’agit de fichiers properties contenant les critères de recherche des personnes morales ou physiques.

2.3 Description détaillée des classes

2.3.1 Dossier src/main/java

Nom du package / Nom de la classe

Java

Fonction

fr.sante.annuaire.webservices.client.authentification

Package des services d’authentification

LoginService.java Classe de service d'appel au gestionnaire du jeton VIHF et de la connexion TLS.

fr.sante.annuaire.webservices.client.certificate

Package utilitaire pour extraction de données d’un certificat

GetX509CertificateInfo.java Classe extractrice de données du certificat

Issuer.java Classe représentant l’objet Issuer du certificat

Subject.java Classe représentant l’objet Subject du certificat

fr.sante.annuaire.webservices.client.common.vihf

Package contenant les classes utilitaires pour la génération du VIHF (classes et énumérations)

CommonCode.java Classe implémentant un élément générique pour le VIHF

IdStructureType.java Enumération pour les types d'identifiants structures

IdUserType.java Enumération pour les types d'identifiants des acteurs

ModeAcces.java Enumération pour les modes d'accès




Java

Fonction

ProfilUtilisateur.java Classe implémentant l’élément ProfilUtilisateur

PurposeOfUse.java Classe implémentant l’élément PurposeOfUse

Role.java Classe implémentant l’élément Role pour les professions et spécialités

RoleItf.java Interface de l’élément Role

VIHF.java Interface de l’objet VIHF

VIHFProfil.java Classe implémentant l’élément VIHFProfil

fr.sante.annuaire.webservices.client.consultation

Package contenant les classes d’implémentation des clients des Web Services de consultation PP et PM

ConsultationPMClient.java Classe représentant un client du web service de consultation PM

ConsultationPPClient.java Classe représentant un client du web service de consultation PP

fr.sante.annuaire.webservices.client.examples.donnees

Package contenant les données en exemple

PSSampleData.java Classe regroupant des données d’exemple du PS (carte CPS) suivant le type d’authentification

fr.sante.annuaire.webservices.client.exception

Package contenant une classe d’exception générique utilisée par les clients des web services

AnnuaireSanteWebServiceClientException.java

Classe d’exception générique utilisée par les clients des web services

fr.sante.annuaire.webservices.client.pkcs11

Package regroupant tout ce qui concerne le pkcs11 (lecteur de carte CPS)

Pkcs11.java Interface pour utiliser la carte pkcs11

PKCS11Tools.java Classe utilitaire pour le pkcs11

fr.sante.annuaire.webservices.client.pkcs11.cps

Package contenant les classes spécifiques à la carte CPS

CPSCard.java Classe permettant de charger la Cryptolib dans le provider PkCS11 sun

fr.sante.annuaire.webservices.client.pkcs11.impl

Package regroupant les implémentations de l’interface pkcs11

Pkcs11Impl.java Implémentation du pkcs11 permettant de ne charger qu’une seule fois la




Java

Fonction

Cryptolib

fr.sante.annuaire.webservices.client.pkcs12

Package regroupant tout ce qui concerne le pkcs12 (certificat serveur)

Pkcs12.java Interface pour utiliser un certificat pkcs12

fr.sante.annuaire.webservices.client.pkcs12.impl

Package regroupant les implémentations de l’interface pkcs12

Pkcs12Impl.java Implémentation du pkcs12 permettant de charger un certificat

fr.sante.annuaire.webservices.client.recherche

Package contenant les classes d’implémentation des clients des Web Services de recherche PP et PM

RecherchePMClient.java Classe représentant un client du web service de recherche PM

RecherchePPClient.java Classe représentant un client du web service de recherche PP

fr.sante.annuaire.webservices.client.security.vihf

Package contenant la représentation du jeton VIHF

Helper.java Permet de créer des exceptions compréhensibles pour le VIHF

VIHFFields.java Enumération des champs du VIHF

VIHFImpl.java Implémentation du jeton VIHF

fr.sante.annuaire.webservices.client.security.vihf.handlers

Package contenant les handlers du jeton VIHF

VIHFClientHandler.java Classe représentant un VIHF client (hérite de VIHFHandler)

VIHFHandler.java Superclasse du Handler VIHF

fr.sante.annuaire.webservices.client.soapservice

Package contenant la classe qui gère la mise en place du VIHF dans les messages et la connexion

SetTLSAndVIHF.java

Classe qui gère la mise en place du VIHF dans les messages et la connexion TLS (tunnel TLS persistant avec cxf).

fr.sante.annuaire.webservices.client.util

Package regroupant les classes utilitaires de l’application cliente

BaseClient.java Classe de base pour les clients des Web Services




Java

Fonction

Constants.java Classe de constantes pour clients des Web Services

Properties.java Classes permettant de charger une propriété se trouvant dans src/main/resources/config.properties

SSLKeyManagers.java Manager de clés pour la connexion TLS avec un certificat serveur

fr.sante.annuaire.webservices.client.vihf

Package contenant les différents handlers VIHF (exemples de jetons VIHF)

KSClientHandler.java Handler pour VIHF signé par carte CPS (usage futur)

NotSignedClientHandler.java Handler VIHF non signé (authentification directe)

P11ClientHandler.java Handler pour VIHF signé par carte CPS (usage futur)

SoftwareCertificateClientHandler.java Handler VIHF non signé avec certificat pkcs12 (authentification indirecte)

fr.sante.annuaire.webservices.client.xades

Package contenant les classes de construction de signature Xades

CpsPathBuilder.java Classe permettant de gérer la chaine de certification des cartes CPS à ajouter aux signatures XAdES

2.3.2 Dossier src/test/java


Java

Fonction

fr.sante.annuaire.webservices.client.test

Package contenant les classe d’implémentation des tests des Web Services

AllTests.java Classe qui fait appel à tous les tests implémentés

ConsultationPMTest.java Classe d’implémentation de test de la consultation des PM

ConsultationPPTest.java Classe d’implémentation de test de la consultation des PP

RecherchePMTest.java Classe d’implémentation de test de la recherche des PM

RecherchePPTest.java Classe d’implémentation de test de la recherche des PP

fr.sante.annuaire.webservices.client.test.util

Package contenant les classes utilitaires




Java

Fonction

Constants.java Classe de constantes pour les classes de test

2.4 Configuration de l’application cliente

2.4.1 Fichier de configuration

Les paramètres de configuration de l’application cliente se trouvent dans le fichier config.properties, il convient de, les bien renseigner, avant d’exécuter l’application cliente.

Paramètre Description Requis ?

SERVER_URL Il s’agit de l’URL racine des Web Services cibles

Oui

CERTIFICATE_TYPE Il s’agit du type du certificat, les valeurs possibles sont : CPS (certificat de la carte) et P12 (certificat serveur)

Oui

CPS_MODULE Il s’agit du chemin absolu sur le poste client du module PKCS11, celui-ci doit être installé sur le poste client (Cryptolib). Ce chemin peut différer d’un système à un autre, valeurs possibles :

C:/WINDOWS/system32/cps_pkcs11_w32.dll

C:/WINNT/cps_pkcs11_w32.dll

C:/WINNT/system32/cps_pkcs11_w32.dll

C:/Windows/SysWOW64/cps3_pkcs11_w32.dll

Oui

si CERTIFICATE_TYPE =CPS

CPS_PWD Il s’agit du code PIN de la carte CPS Oui

si CERTIFICATE_TYPE = CPS

CPS_SIGN_VIHF Indique si le jeton VIHF doit être signé ou pas, la valeur doit être positionnée à « false »

Oui

si CERTIFICATE_TYPE = CPS

AUTHENTIFICATION_CERTIFICATE_PATH Il s’agit du chemin du certificat P12 servant à l’authentification

Oui

si CERTIFICATE_TYPE = P12

AUTHENTIFICATION_PASSWORD Il s’agit du mot de passe du certificat P12 servant à l’authentification

Oui


SERVER_TRUSTSTORE_PATH Il s’agit du chemin du fichier keystore (magasin de clefs) qui stocke les clefs

Oui



Paramètre Description Requis ?

privés des certificats

SERVER_TRUSTSTORE_PASSWORD Il s’agit du mot de passe du fichier keystore (magasin de clefs) qui stocke les clefs privés des certificats

Oui

PROXY_HOST Configuration du proxy (hôte) si le poste client est derrière un proxy

Oui

si utilisation de l’application derrière un proxy

PROXY_PORT Configuration du proxy (port) si le poste client est derrière un proxy

Oui

si utilisation de l’application derrière un proxy

IDENTIFIANT_STRUCTURE Identifiant de l’établissement de santé ou du cabinet depuis lequel, la requête a été émise

Non

SECTEUR_ACTIVITE Secteur d’activité dans lequel exerce l’utilisateur

Non

PROFIL_UTILISATEUR Profil de l’utilisateur Oui

PROFIL_UTILISATEUR_PERIMETRE Contexte métier ou périmètre de l’utilisateur

Oui

si le profil de l’utilisateur nécessite la détermination d’un périmètre.

IDENTITE_UTILISATEUR Identité de l’utilisateur dans le cas d’une authentification indirecte (ex : nom, prénom)

Oui


PATH_TO_SAVE Chemin des fichiers des réponses générées en sortie

Oui

2.4.2 Authentification

L’application cliente fonctionne avec deux modes d’authentification :

1. Authentification directe avec une carte CPS de test 2. Authentification indirecte avec des certificats de structure (certificats serveur).

L’application cliente est livrée en mode authentification directe CPS par défaut. Dans ce mode, un lecteur de carte fonctionnel avec une carte CPS de test insérée est un prérequis à l’exécution de l’application cliente (code PIN = 1234 configuré par défaut).

Pour utiliser des certificats de structure, le fichier config.properties doit être modifié comme suit :

Le paramètre « CERTIFICATE_TYPE » doit être positionné à la valeur « P12 »

Copier les certificats p12 en votre possession dans le répertoire Certificates de l’application cliente



Préciser le nom et le mot de passe du fichier p12 à utiliser dans les variables : AUTHENTIFICATION_CERTIFICATE_PATH et AUTHENTIFICATION_PASSWORD.

2.4.3 Utilisation derrière un proxy

Si l’application cliente est exécutée derrière un proxy, il est nécessaire de renseigner les champs PROXY_HOST et PROXY_PORT du fichier de configuration (décommenter les paramètres en supprimant le caractère « # »).

3. Principes de fonctionnement

3.1 Connexion sécurisée TLS mutuelle

La connexion sécurisée entre l’application cliente et l’Annuaire Santé s’effectue via une authentification TLS mutuelle. Les certificats utilisés pour cette opération sont le certificat de la carte CPS ou le certificat établissement côté client et le certificat de l’Annuaire Santé côté serveur.

Dans la version initiale de l’Annuaire Santé, la connexion TLS est réalisée à partir des certificats des personnes morales. Les certificats autorisés sont déclarés manuellement dans la configuration de l’Annuaire Santé. Le processus de mise œuvre est détaillée dans le guide d’utilisation de la plate-forme de tests des web services : « ANST_BUILD_TEC_Procedure-Utilisation

PF de tests des WebServices_20130515_V0.0.1.docx »

Le fichier de configuration cxf-client.xml situé dans le dossier src/main/resources configure les paramètres CXF. L’implémentation des actions nécessaires à la connexion sécurisée se trouve dans la classe SetTLSAndVIHF du package fr.sante.annuaire.webservices.client.soapservice.

Paramètres CXF :

afin que le canal reste ouvert côté client (pour éviter les sollicitations de la carte CPS) le paramètre Connection="Keep-Alive" est positionné : <http:conduit name="*.http-conduit">

<http:client ... Connection="Keep-Alive" ... />

</http:conduit>

afin de permettre à l’application cliente de voir les flux échangés (capture des trames entrantes / sortantes en debug uniquement, ne pas utiliser en environnement de production), les paramètres suivants sont positionnés (les trames sont envoyées dans la sortie standard) : <cxf:bus>

…

<cxf:inInterceptors>

<ref bean="loggingInInterceptor" />

</cxf:inInterceptors>

<cxf:outInterceptors>

<ref bean="loggingOutInterceptor" />

</cxf:outInterceptors>

<cxf:inFaultInterceptors>

<ref bean="loggingInInterceptor" />

</cxf:inFaultInterceptors>

<cxf:outFaultInterceptors>

<ref bean="loggingOutInterceptor" />

</cxf:outFaultInterceptors>

</cxf:bus>

La fonction setTLS :



récupère le certificat d’authentification ;

crée un X509TrustManager ;

crée un contexte TLS contenant le X509TrustManager et le certificat d’authentification ;

récupère le client TLS de la transaction ;

construit un contexte TLS adapté à l’Annuaire Santé;

définit ce contexte TLS comme étant celui du conduit HTTPS du client récupéré.

3.2 Authentification directe (carte CPS)

Pour tester ce mode d’authentification par carte CPS, le fichier config.properties doit être configuré en mode CPS (voir paramètre CERTIFICATE_TYPE).

Pour accéder à la carte CPS, la librairie cryptographique CPS (Cryptolib) est requise sur le poste, ainsi qu’un lecteur de carte correctement configuré. Il est nécessaire d’utiliser la version 5.x.x du package de la Cryptolib. Le paramétrage de la Cryptolib dépend de la plateforme cible (voir paramètre CPS_MODULE).

L’accès PKCS11 offert par la librairie CPS étant sous la forme d’une librairie externe (cps_pkcs11_w32.dll sous Windows, voir la documentation de la librairie CPS pour plus de précisions sur les autres systèmes), il est nécessaire d’utiliser un wrapper ou un provider pour y accéder en java. Dans l’application cliente, nous avons utilisé le provider PKCS11 fourni par Sun (sun.security.pkcs11.SunPKCS11).

Le certificat de la carte est extrait au premier accès, puis l’accès à la carte ne se fait ensuite que pour effectuer des signatures.

3.2.1 Extraction des informations de la carte CPS

Tous les accès à la carte CPS se font dans la classe CPSCard qui est elle-même appelée par la classe PKCS11Impl du package fr.sante.annuaire.webservices.client.pkcs11.impl. L’extraction des données se fait dans la fonction init de CPSCard et se déroule de la façon suivante :

1. Ajout du provider de la carte CPS aux providers accessibles 2. Chargement du Keystore de la carte avec le code PIN 3. Récupération de la liste des alias du Keystore 4. Mise en place en mémoire des informations en fonction du nom de leur alias

Il ne reste plus qu’à appeler les getters de CPSCard pour récupérer les informations nécessaires.

3.2.2 Signature des données avec la carte CPS

La signature des données se base sur l’objet PrivateKey signaturePrivateKey que l’on a obtenu ci-dessus.

Afin de signer, nous utilisons la classe Signature fournie de base avec java et permettant de signer à partir d’une clé privée.

En réalité, avec un lecteur de carte PKCS11, nous n’obtenons pas réellement la clé privée mais un token établissant le lien avec la carte.

La signature s’effectue dans la fonction sign de la classe CPSCard.

La procédure de signature est la suivante :

1. Création d’un objet Signature en précisant le mécanisme de signature 2. Initialisation de l’objet en lui passant la clé de signature 3. Mise en place des données à signer



4. Signature des données et récupération de la signature.

3.3 Authentification indirecte (certificats établissement)

Pour tester ce mode d’authentification par certificat établissement, le fichier config.properties doit être configuré en mode P12 (voir paramètre CERTIFICATE_TYPE).

Pour les certificats d’établissement (certificats « serveur ») PKCS12 dans l’application cliente, nous avons utilisé les fonctionnalités offertes par java.

3.3.1 Obtenir l’accès aux méthodes du certificat PKCS12

La procédure pour obtenir l’accès à un certificat PKCS12 est la suivante :

1. Récupération de l'instance du dépôt de clés gérant les certificats PKCS12 2. Initialisation du dépôt avec le certificat fourni (sous forme de fichier) et le code PIN du

certificat.

Dans l’application cliente, nous récupérons ensuite directement la clé et le certificat afin de pouvoir les réutiliser rapidement (voir la fonction login de la classe Pkcs12Impl du package fr.sante.annuaire.webservices.client.pkcs12.impl).

3.4 Jeton VIHF

3.4.1 Structure du jeton VIHF

Le jeton VIHF se trouve dans le package fr.sante.annuaire.webservices.client.security.vihf. La classe VIHFFields liste les champs du jeton VIHF sous la forme d’une énumération.

La classe VIHFImpl représente le jeton VIHF et offre un constructeur ainsi que des fonctions pour le créer en se basant sur la bibliothèque openSaml.

Le package fr.sante.annuaire.webservices.client.security.vihf.handlers contient les différentes classes handlers utilisés par l’application cliente.

3.4.2 Construction du jeton VIHF

La construction du jeton VIHF se fait dans la classe SetTLSAndVIHF du package fr.sante.annuaire.webservices.client.soapservice. La fonction AddVIHF se charge de se logger si possible sur le certificat P12 (le jeton VIHF n’est pas signé) puis appelle la fonction de création de handler correspondante (NotSignedClientHandler dans le cas de la carte CPS et SoftwareCertificateClientHandler pour le certificat serveur).

Ces deux classes héritent des classes du package : fr.sante.annuaire.webservices.client.security.vihf.

handlers et fixent des valeurs exemples dans le VIHF. Le VIHF doit être valorisé correctement à partir des données issues de la carte CPS (cas de l’authentification directe) ou du certificat établissement (cas de l’authentification indirecte).

Ces handlers sont ensuite rattachés au service SOAP à l’aide d’un objet SOAPBinding (voir fonction AddVIHF).

Le rattachement du VIHF est effectué juste avant l’envoi de la requête SOAP.

Les informations présentes dans le jeton VIHF sont utilisées pour l’identification du détenteur de carte (Inscription préalable dans l’Annuaire Santé). Le contenu du jeton VIHF est stocké comme élément de preuve.





4. Installation de l’application cliente

4.1 Prérequis

Les composants cryptographiques CPS doivent être installés (version 5.x.x du package au minimum). La mise à jour des composants cryptographiques peut se faire en utilisant l'outil de DMP compatibilité.

Disposer de l'IDE Eclipse version Juno (4.2) ou ultérieure

Configurer l'encodage du workspace d’Eclipse pour utiliser l’UTF-8 : o Aller sur Window -> Preferences -> General -> Workspace o Dans Text File encoding, définir « UTF-8 » comme encoding par défaut du workspace

pour les fichiers textes o Aller sur General -> Content Types sur le menu à gauche o Sélectionner Text -> Java Properties Files dans la zone Content types o Saisir « UTF-8 » dans le champ Default encoding (en bas de la fenêtre) o Cliquer sur le bouton Update à droite du champ Default encoding o Cliquer sur le bouton OK

Installer un JDK 1.6 U4 ou supérieur en mode 32 bits (le mode 64 bits n'est pas compatible), ce JDK doit être aussi installé dans l’IDE Eclipse

Un plugin de Maven (M2E - Maven Integration for Eclipse) doit être installé sur Eclipse

Configurer le plugin pour utiliser l’installation de Maven embarquée v3.0.4 ou supérieure

Configurer de préférence le plugin pour ne pas utiliser un fichier de configuration settings.xml, afin de ne prendre en compte que les repositories de Maven définis dans le pom.xml du projet (cela accélère la construction du projet).

4.2 Installation

1. Décompresser l'archive annuaire-sante-webservices-client-x.x.x-src.zip dans un workspace 2. Ouvrir Eclipse en se positionnant sur ce workspace 3. Importer le projet : menu File -> Import... -> General -> Existing Projects into Workspace 4. Cliquer sur le bouton Next 5. Sélectionner la racine du workspace 6. Sélectionner le projet annuaire-sante-webservices-client-x.x.x 7. Cliquer sur le bouton Finish 8. Créer une configuration Maven : Aller sur le menu Run -> Run Configurations… 9. Se positionner sur Maven Build 10. Faire un clic droit -> New 11. Saisir annuaire-sante-webservices-client dans le champ Name 12. Sélectionner le projet annuaire-sante-webservices-client-x.x.x à l'aide du bouton Browse

Workspace... dans le champ Base directory 13. Saisir -X clean install eclipse:clean eclipse:eclipse dans le champ Goals 14. Cocher la case Skip Tests 15. Aller sur l’onglet JRE 16. Sélectionner le JDK du workspace par défaut s’il correspond bien à un jdk (1.6 U4 ou

supérieur) complet (pas seulement un JRE) en mode 32 bits, sinon sélectionner le bon jdk en cochant Alternate JRE et sélectionner le à partir de la liste déroulante

17. Aller sur l'onglet Refresh 18. Cocher la case Refresh resources upon completion 19. Cliquer sur le bouton Run 20. Attendre la fin du build



21. Le message BUILD SUCCESS doit apparaître à la fin du build

4.3 Remarques

La javadoc est disponible sous le dossier doc/apidocs

Si besoin de regénérer la javadoc, créer une configuration Maven comme ci-dessus avec comme cible javadoc:javadoc et l'exécuter

Si besoin de repackager les sources du projet, créer une configuration Maven comme ci-dessus avec comme cible assembly:single et l'exécuter

4.4 Configuration de l’application cliente

Editer le fichier src/main/resources/config.properties

Suivre la procédure de Configuration de l’application cliente (§2.4)

4.5 Exécution des tests

L’application cliente est fournie avec un jeu de tests sous forme de fichiers de propriétés, ces fichiers correspondent aux critères en entrée, de la consultation ou de la recherche des personnes morales et physiques. Les modèles de ces fichiers se trouvent sous le dossier src/test/resources/fr/sante/annuaire/webservices/client/templates :

1. consultationPMTemplate.properties pour le Web service de consultation des personnes morales

2. consultationPPTemplate.properties pour le Web service de consultation des personnes physiques

3. recherchePMTemplate.properties pour le Web service de recherche des personnes morales 4. recherchePPTemplate.properties pour le Web service de consultation des personnes

physiques

Les fichiers de test fournis avec l’application cliente se trouvent dans les dossiers suivants :

1. src/test/resources/fr/sante/annuaire/webservices/client/consultation pour la consultation des personnes morales et physiques.

2. src/test/resources/fr/sante/annuaire/webservices/client/recherche pour la recherche des personnes morales et physiques.

Ces fichiers correspondent à différents cas de test de consultation et de recherche de personnes morales et physiques. A l’exécution des tests, les classes ci-dessous, se trouvant sous le package src/main/java/fr/sante/annuaire/webservices/client/test/ permettent de lire le contenu des dossiers ci-dessus :

1. ConsultationPMTest.java pour les fichiers de test de consultation de personnes morales 2. ConsultationPPTest.java les fichiers de test de consultation de personnes physiques 3. RecherchePMTest.java les fichiers de test de recherche de personnes morales 4. RecherchePPTest.java les fichiers de test de recherche de personnes physiques

Ces classes correspondent à des classes de test JUnit qui peuvent être exécutées séparément ou toutes à la fois.

Pour exécuter le test d’une classe avec Eclipse, faire un clic droit sur la classe puis Run As > JUnit Test (Junit 4 doit être configuré par défaut)



Pour exécuter tous les tests avec Eclipse, faire un clic droit sur la classe AllTests se situant dans le même package puis Run As > JUnit Test

Pour exécuter tous les tests avec Maven, créer une configuration Maven semblable à celle décrite dans l’installation du projet et mettre comme cibles (goals) : test

Les résultats de tests sont produits sous forme de fichiers XML situés à l’emplacement défini par le paramètre PATH_TO_SAVE dans le fichier config.properties. Ces fichiers correspondent aux réponses des requêtes Soap envoyés aux Web Services.



5. Tests avec SoapUI

Les web services peuvent être testés à partir de l’application SoapUI. Pour se faire l’option suivante doit être positionnée dans le fichier soapUI-X.X.X.vmoptions :

-Dsun.security.ssl.allowUnsafeRenegotiation=true

Le keystore fournit dans les sources doit également être positionné dans les préférences SoapUI (« SSL Settings »)