webservices EJBCA

<note>Consulter également la page sur SOAPUI, décrivant la mise en place de SOAPUI spécifiquement pour EJBCA. Cela est une solution pour tester rapidement un webservices</note>

Liste des méthodes

Méthode	Description
editUser	Création / édition d'une entité. Cela correspond à l'utilisation du lien “Requête de certificat” dans le cas d'une création, et du lien “Gestion entité” (disponible lors d'une recherche) pour une entité déjà existante
checkRevocationStatus
findUser	Permet la recherche d'entité, voir l'exemple
findCert	Récupèrer la liste des certificats d'une entité
revokeUser	Permet de revoquer tous les certificats d'une entité
revokeCert	Permet de revoquer un certificat
revokeToken
pkcs10Req	Émission d'un certificat (en mode décentralisé) à partir d'une requête de certificat (PKCS#10/CSR)
pkcs12Req	Émission d'un certificat (en mode centralisé), la biclé sera générée par EJBCA, correspond à un type de token P12/PEM/JKS

Utilisation des méthodes

editUser

Exemple de requête

Voici un exemple de message SOAP (généré par SOAPUI) pour créer une entité (ou modifier une entité existante) :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.protocol.core.ejbca.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:editUser>
         <arg0>
            <caName>NewUI</caName>
            <certificateProfileName>ENDUSER</certificateProfileName>
            <clearPwd>true</clearPwd>
            <email>bbonfils@linagora.com</email>
            <endEntityProfileName>EMPTY</endEntityProfileName>
            <keyRecoverable>true</keyRecoverable>
            <password>foo123</password>
            <sendNotification>false</sendNotification>
            <status>10</status>
            <subjectDN>cn=Demo</subjectDN>
            <tokenType>P12</tokenType>
            <username>demo</username>
         </arg0>
      </ws:editUser>
   </soapenv:Body>
</soapenv:Envelope>

Description des paramètres userInfo

Paramètre	Description
caName	Nom court de l'AC (liste disponible dans le menu “Edit/Créer AC”)
certificateProfileName	Nom du profil de certificat (liste disponible dans le menu “Profil de certificats”)
clearPwd	Booléan (true / false) pour activer le stockage en clair du mot de passe dans la base de donnée, nécessaire pour une utilisation en batch par exemple
email	Adresse email du porteur du certificat
endEntityProfileName	Nom du profil d'entité
keyRecoverable	Booléan (true / false) activant le recouvrement de clé. Ne peut pas être utilisé avec un token du type USERGENERATED
password	Mot de passe de l'entité
statuts	Statut de l'entité (cf tableau)
subjectDN	DN du porteur du certificat
tokenType	Type de token (USERGENERATED, P12, PEM, JKS)
username	Nom de l'entité

Description des statuts

Valeur	Nom	Description
10	NEW	L'entité est prête à accueillir un nouveau certificat
11	FAILED	Le certificat de l'entité n'a pu être généré
20	INITIALIZED
30	INPROCESS	Le certificat est en cours de création
40	GENERATED	Le certificat a été correctement généré
50	REVOKED	L'entité est revoquée
60	HISTORICAL	L'entité est archivée
70	KEYRECOVERY	L'entité est en cours de recouvrement

L'ensemble des statuts est décris dans le fichier src/java/org/ejbca/core/model/ra/UserDataConstants.java des sources d'EJBCA.

Description des codes d'erreur

Les codes d'erreur suivant peuvent potentiellement être retournés (dans une exception de type EjbcaException) :

Code	Description
CA_NOT_EXISTS	L'entité de certification n'existe pas
EE_PROFILE_NOT_EXISTS	Le profile d'entité finale n'existe pas
CERT_PROFILE_NOT_EXISTS	Le profile de certificat n'existe pas
HARD_TOKEN_ISSUER_NOT_EXISTS	Le pilote du hard token n'existe pas
UNKOWN_TOKEN_TYPE	Le type de token n'existe pas
INTERNAL_ERROR	Erreur interne (technique)

Tous ces codes d'erreurs peuvent être retrouvés dans EJBCA dans la classe org.ejbca.core.ErrorCode

findUser

Le webservice findUser est l'équivalent webservices de la page listendentities.jsp, il permet de faire une rercherche des entités dans EJBCA.

Exemple de requête

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.protocol.core.ejbca.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:findUser>
         <!--Optional:-->
         <arg0>
            <matchtype>1</matchtype>
            <matchvalue>cat</matchvalue>
            <matchwith>0</matchwith>
         </arg0>
      </ws:findUser>
   </soapenv:Body>
</soapenv:Envelope>

Description des paramètres

Argument	Type	Description
matchtype	Entier (de 0 à 2)	Définis la méthode de correspondance utilisé. Il existe 3 valeurs : 0, pour EQUALS, 1 pour BEGINSWITH, 2 pour CONTENTS
matchvalue	Chaîne de caractère	Valeur utilisée pour la recherche
matchwith	Entier (de 0 à 20)	Correspond au type de champ utilisé pour la recherche (voir tableau suivant pour la liste des valeurs possibles)

Description des paramètres matchwith

Valeur	Description
0	USERNAME
1	EMAIL
2	STATUS
3	ENDENTITYPROFILE
4	CERTIFICATEPROFILE
5	CA
6	TOKEN
7	DN
8	UID
9	COMMONNAME
10	DNSERIALNUMBER
11	GIVENNAME
12	INITIALS
13	SURNAME
14	TITLE
15	ORGANIZATIONALUNIT
16	ORGANIZATION
17	LOCALE
18	STATE
19	DOMAINCOMPONENT
20	COUNTRY

Description des codes d'erreur

Les codes d'erreur suivant peuvent potentiellement être retournés (dans une exception de type EjbcaException) :

Code	Description
INTERNAL_ERROR	Erreur interne (technique)

Tous ces codes d'erreurs peuvent être retrouvés dans EJBCA dans la classe org.ejbca.core.ErrorCode

findCerts

Cette méthode permet de récupérer l'ensemble des certificats associés à une entité.

Exemple de requête

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.protocol.core.ejbca.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:findCerts>
         <!--Optional:-->
         <arg0>cat00</arg0>
         <arg1>false</arg1>
      </ws:findCerts>
   </soapenv:Body>
</soapenv:Envelope>

Description des paramètres

Argument	Type	Description
arg0	Chaîne de caractère	Nom de l'entité
arg1	Boolean (true/false)	Si vrai, cette méthode ne retourne que les certificats valides

Description des codes d'erreur

Les codes d'erreur suivant peuvent potentiellement être retournés (dans une exception de type EjbcaException) :

Code	Description
INTERNAL_ERROR	Erreur interne (technique)

Tous ces codes d'erreurs peuvent être retrouvés dans EJBCA dans la classe org.ejbca.core.ErrorCode

pkcs10Req

Émission d'un certificat (en mode décentralisé) à partir d'une requête de certificat (PKCS#10/CSR).

Description des paramètres

Argument	Type	Description
arg0	Chaîne de caractère	Nom de l'entité
arg1	Chaîne de caractère	Mot de passe de l'entité
arg2	Chaîne de caractère	PKCS10 en base 64
arg3	Chaîne de caractère	hardTokenSN (peut être null)
arg4	Chaîne de caractère	Type de réponse

Description des paramètres type de réponse

Valeur	Description
CERTIFICATE	Un certificat encodé en base 64
PKCS7	Un PKCS7 encodé en base 64
PKCS7WITHCHAIN	Un PKCS7 avec la chaine de certification complète encodé en base 64

Description des codes d'erreur

Les codes d'erreur suivant peuvent potentiellement être retournés (dans une exception de type EjbcaException) :

Code	Description
INVALID_KEY	La clé fournie est invalide
ILLEGAL_KEY	La clé fournie est illégale (trop courte …)
USER_WRONG_STATUS	L'utilisateur n'est pas dans le bon statut
LOGIN_ERROR	Erreur de login (user/password)
CA_NOT_EXISTS	L'authoritée de certification n'existe pas
SIGNATURE_ERROR	Erreur de signature
INVALID_KEY_SPEC	Le type de clé spécifié est invalide
BAD_USER_TOKEN_TYPE	Le type de token utilisateur est invalide
INTERNAL_ERROR	Erreur interne (technique)

Tous ces codes d'erreurs peuvent être retrouvés dans EJBCA dans la classe org.ejbca.core.ErrorCode

pkcs12Req

Émission d'un certificat (en mode centralisé), la biclé sera générée par EJBCA, correspond à un type de token P12/PEM/JKS.

Description des paramètres

Argument	Type	Description
arg0	Chaîne de caractère	Nom de l'entité
arg1	Chaîne de caractère	Mot de passe de l'entité
arg2	Chaîne de caractère	hardTokenSN (peut être null)
arg3	Chaîne de caractère	Spécification de la clé (exemple taille de la clé RSA ⇒1024, prime192v1 pour ECDSA)
arg4	Chaîne de caractère	Algorythme de chiffrement de la clé (RSA, ECDSA)

Description des codes d'erreur

Les codes d'erreur suivant peuvent potentiellement être retournés (dans une exception de type EjbcaException) :

Code	Description
CA_NOT_EXISTS	L'authoritée de certification n'existe pas
ILLEGAL_KEY	La clé fournie est illégale (trop courte …)
LOGIN_ERROR	Erreur de login (user/password)
USER_WRONG_STATUS	L'utilisateur n'est pas dans le bon statut (pour cette opération)
BAD_USER_TOKEN_TYPE	Le type de clé spécifié est invalide
INTERNAL_ERROR	Erreur interne (technique)

Tous ces codes d'erreurs peuvent être retrouvés dans EJBCA dans la classe org.ejbca.core.ErrorCode

revokeUser

Permet de revoquer tout les certificat d'une entité EJBCA.

Description des paramètres

Argument	Type	Description
arg0	Chaîne de caractère	Nom de l'entité
arg1	Entier	Raison de la révocation
arg2	Boolean (true/false)	Si vrai, l'entité doit être supprimé a l'issue de la révocation de tous les certificats

Description des codes d'erreur

Les codes d'erreur suivant peuvent potentiellement être retournés (dans une exception de type EjbcaException) :

Code	Description
INTERNAL_ERROR	Erreur interne (technique)

Tous ces codes d'erreurs peuvent être retrouvés dans EJBCA dans la classe org.ejbca.core.ErrorCode

revokeCert

Permet de revoquer un certificat

Description des paramètres

Argument	Type	Description
arg0	Chaîne de caractère	DN de l'AC
arg1	Chaîne de caractère	SerialNumber du certificat
arg2	Entier	Raison de la révocation

Description des paramètres Raison de la révocation

Valeur	Description
-1	Non révoqué
0	Non spécifié
1	Clé compromise
2	Authorité de certification compromise
3	Changement d'affiliation
4	Remplacé
5	Cessation d'activité
6	CERTIFICATEHOLD
7	Non utilisé
8	REMOVEFROMCRL
9	PRIVILEGESWITHDRAWN
10	Authorité d'attribut compromise

Description des codes d'erreur

Les codes d'erreur suivant peuvent potentiellement être retournés (dans une exception de type EjbcaException) :

Code	Description
CERT_WRONG_STATUS	Statut de certificat erroné
INTERNAL_ERROR	Erreur interne (technique)

Tous ces codes d'erreurs peuvent être retrouvés dans EJBCA dans la classe org.ejbca.core.ErrorCode