# API Method - revoke

**Purpose**

Use the “revoke” method for revoking the x509 certificates based on the certificate serial number.

#### Type of Method

POST

#### Request URL

[http://www.example.com/emCAServices/rest/revoke](http://www.example.com/emCAServices/rest/revoke)

#### Request Post data Input Parameter

JSON Object Contains below parameters

<table data-header-hidden><thead><tr><th width="129">Parameter</th><th width="108">Presence</th><th width="112">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Presence</td><td>Data Type</td><td>Description</td></tr><tr><td><p> </p><p>userName</p></td><td>M</td><td><p> </p><p>String</p></td><td><p> </p><p>You need to pass username that is registered with emCA for API process.</p></td></tr><tr><td><p> </p><p>password</p></td><td>M</td><td><p> </p><p>String</p></td><td><p> </p><p>You need to pass the password that is registered with emCA for API process.</p></td></tr><tr><td><p> </p><p>signature</p></td><td>M</td><td><p> </p><p>String</p></td><td><p> </p><p>Pass the signature (signed data) in section 5 i.e., PKCS#7 data Signed Certificate Serial Number</p></td></tr><tr><td>remarks</td><td>M</td><td>String</td><td>   Pass your reason for revocation of certificate</td></tr><tr><td><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p>revokeMode</p></td><td><p> </p><p> </p><p> </p><p>M</p></td><td><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p>Integer</p></td><td><p>Pass the below values</p><p> </p><p>                        0 for - Unspecified</p><p>1   for - Key Compromise</p><p>2   for - CA compromise</p><p>3   for - Affiliation</p><p>4   for - Superseded</p><p>5   for - Cessation of operation</p><p>9   for - Privilege withdrawn</p><p>10   for - AA Compromise</p></td></tr></tbody></table>

#### Sample JSON Object

&#x20;

<table data-header-hidden><thead><tr><th width="155">Parameter</th><th width="105">Presence</th><th width="114">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Presence</td><td>Data Type</td><td>Description</td></tr><tr><td>requestData</td><td>M</td><td>String</td><td><p>All the request input parameters mentioned above should be converted to JSON object and encrypted with AES 256 key shared with you by emCA team.</p><p>Pass Encrypted JSON Object.</p></td></tr><tr><td>userName</td><td>M</td><td>String</td><td><p> </p><p>You need to pass username that is registered with emCA for API process.</p></td></tr></tbody></table>

#### Header Details

&#x20;

| Key                | Presence | Value        | Text                                                                                              |
| ------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------- |
| Application / JSON | M        | Content-Type | Type of request should be in JSON Format.                                                         |
| Authentication Key | M        | emKey        | emKey is an encoded key (Refer section 4 for generating Authentication Key using command prompt). |

#### Sample Request Data

```
Header:
Content-Type : application/json
emKey	: 47b54594063957de22fce0aeddd51a6adf4a80aa
Request Body:
{
"requestData" :
"Q/5rvKIZvoMfuZQnysxcGawX4wC1xRttkCHEExreOwUCltgPG0FmsAbEmNHgHvdM2A7Vadyks2IDACy dZDRG9rS/uq93IO3KMAyazof7IJXz31c3LiXorwiRksUFOrH2IqYbqI1q88Sf3rnxoTdq8oaOzYB2LoN Ph8dZihJyDIR33BccF1Dg/sS/UAwxJ3fjbPzRJpFcqhi2FX1IS8TxyW2PZtPyLtSddyDFxliryGv8RMm Vem6NdJYeNHcYo82qHtszdepvIWCi/DLCqs1alR9TcOsKQ8skBTUQY5xfiuONm68zytXBlF+MIAB40Ws w/12zywoCe2z14wqA/mvzF6Jd/Cw3059NfW8FtmBS502ty4l+kSDallVUCSFP9b9Drsh4q/giwT+zHa/ SQ3LWCFkjDLaB/OMzMaZfAFwm27/mDB4mSWVMPzMo8CDBvNNNekeV6lSeKSJ7rEbR2JJYIeLzQFp++Dv np0KZHZu5r+muXAPFCnsDj3MbLrpvbdl3VYKjtDCu0MXi/LX787pStPvr9coMmHTCwja5p7RwI7Ji/nb OnVpT8f2ylx/Rq7vTFRGAqnFmEK5HAkN6Owdf/dKaKUtifXzJqgjYft0NS7uoXbEJWbb4I86AqLhsPbq qN2zlOXZIaYLvkoleo//gAcevv6ZS3jk5rkhueR44ablyv5nhgQ25Fhg5cqu4hxUBOi1MRXk5RpA6RZk az+DPGSsJJ4+yKzTEnxhUZvnqzeFEf1cvIU3Fx9PLmvrQ50cE28AdNu749WOUyjq/eZCFC1rmY6KyThU 4ng49S+iqCrUiIIF+McgjbuVPRvy0M9eYi9HpVOduV7XEI2zrRLpID0ueVwo/j6XePsofLvk/5J/xT9S 8Ge6wgVNQzkO47eLi2VEPf5OXRopBaSLFZ1SPIgBVumlSnPgLfdNVOirJjhqMyADZrXgoAw3c+YTqRhs RDAhtPKx90Qtw643eLEi/1ujz9ZxB6yzTvFYnh05eaM+N08QVlEJcS+z84vqnY6/+8746T6Ct/tDrLdF CNVvveSEPVCujbE6LI6pzAnNuHWZoFYoDjANRTDuS8m3LY3mcC24cTJnNTt7a/hF6IsUj0ygfVctkpAT XvW9p1m4p6BpYmXFSP6w0nMvKnHd+Uy2R3qykk/1R6YoZbaG9dM3LrAqqAILkYNucL32xZCbSSKX6HIQ tZ0WMAfTubYXLsDnAZCLeph1P+fjnkbgrpizkQg==",
"userName" : "username"
}

```

#### Process

* When request is received by emCA service, we will decrypt the request JSON Object with same AES key that is shared to the client.
* After successful decryption, request JSON object (Signed serial number + Username + Password + revokeMode + remarks) is retrieved.
* First emCA service will validate username and password and check if the IP Address used for request and registered with the user are same.
* If it is same then signed data (signature) is validated by checking whether serial number is signed by pfx which is registered for the specific user.
* If validation fails at any point in processing the request, the emCA service will throw error /failure message.

#### Response Parameters

| Parameter               | Data Type             | Description                        |
| ----------------------- | --------------------- | ---------------------------------- |
| <p> </p><p>response</p> | <p> </p><p>String</p> | <p> </p><p>Returns JSON Object</p> |

**JSON Object Contains below parameters.**

<table data-header-hidden><thead><tr><th width="149">Parameter</th><th width="127">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Data Type</td><td>Description</td></tr><tr><td><p> </p><p> </p><p>status</p></td><td><p> </p><p> </p><p>String</p></td><td><p> </p><p>Returns Status of the request as success if certificate revocation is successful.</p><p>Returns status of the request as failure when authentication fails or unregistered user tries to call the API</p></td></tr><tr><td><p> </p><p> </p><p>result</p></td><td><p> </p><p> </p><p>String</p></td><td><p> </p><p>Returns</p><p>In case of success: “Certificate revoked successfully” message will be displayed.</p><p>In case of failure: error message will be displayed.</p></td></tr><tr><td><p> </p><p>subscriberId</p></td><td>String</td><td><p> </p><p>Returns Subscriber Id</p></td></tr><tr><td><p> </p><p>requestId</p></td><td>String</td><td><p> </p><p>Return Request ID null.</p></td></tr></tbody></table>

**Response JSON Format**

```
Sample:
Success:
Response Body(Is Manual Authorization Enabled is “not“ checked from emCA)
{
"status":"success", "result":"revoked"
“subscriberId”:”XXX” "requestId": null 
}


Response Body ()
{
"status": "Success",
"result": " revoked ", "subscriberId": "XXXX", "requestId": “XXXX” 
}
Failure:
{
"status":"failure", "result":"<Error message>" “subscriberId”:null
"requestId": null,
}
```

#### Error Messages

| Error Message                                         | Description                                                                                    |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| CRL does not exist                                    | If CRL is not created for Issuer certificate                                                   |
| Certificate already revoked                           | If user certificate is already revoked                                                         |
| <p> </p><p>Signature verification failed</p>          | If signature parameter (certificate serial number) contains invalid certificate serial number. |
| <p> </p><p>No Data Found For &#x3C;serial number></p> | If no certificate is available for requested certificate serial number                         |
