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