webservices EJBCA======

<note>Consulter également la page sur [[outils: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 ^
| [[ws#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 | |
| [[ws#findUser]] | Permet la recherche d'entité, voir l'exemple |
| [[ws#findCert]] | Récupèrer la liste des certificats d'une entité |
| [[ws#revokeUser]] | Permet de revoquer tous les certificats d'une entité | 
| [[ws#revokeCert]] | Permet de revoquer un certificat | 
| revokeToken | |
| [[ws#pkcs10Req]] | Émission d'un certificat (en mode décentralisé) à partir d'une requête de certificat (PKCS#10/CSR) | 
| [[ws#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) :

<code xml>
<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>
</code>


====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é |
| [[ws#Description des statuts|statuts]] | Statut de l'entité (cf [[ws#Description des statuts|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====

<code xml>
<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>
</code>

====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====

<code xml>
<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>
</code>

====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''