API Method -getCertificate

Purpose

Use the “getCertificate” method for retrieving the x509 certificate created with your account based on the serial number passed.

Type of Method

POST

Request URL

http://www.example.com/emCAServices/rest/getCertificate

Request Input Parameters

Parameter	Presence	Data Type	Description
signature	M	String	Certificate serial number has to be signed with PFX shared by us. Pass Signed certificate serial number i.e., PKCS#7 data.
userName	M	String	You need to pass username that is registered with emCA for API process.
password	M	String	You need to pass the password that is registered with emCA for API process.

Sample JSON Object

requestData
{
"signature": " axcns/EEczS5nGivHuOHFabnKQhsRNPJLQq7AJnQtGWbl7DgU9WoSLbHf4cvBKozlMnU5E7XOwkxhbQm NQrxv12KAG2F5OYvZosUXaLbp0g3T1V3YRXn3KV74cPY7LM4uO62eHEWJ80PYB+pmXOPxLqGFPNsdvZ/
A+HPkuHpTnnjmUxqO8hDuHEc1y00hxJvasDEXzNU5SuDNWADQNYn45SJU+6H+9ty4GTfzjrNRaLvLHNQ gQ1lFkYEU5Fra8QiZWDqeH6F4h6D+CspxpGxFp4jqOddBvWhWmutSobjJItxEuRjCKaE2w/SPAguY9JK udlFmuPz0uIV4BAkTwFgKw==",
" userName" : "username" " password" : "password "

}

Parameter	Presence	Data Type	Description
requestData	M	String	All the request input parameters mentioned above should be converted to JSON object and encrypted with AES 256 key shared with you by the emCA team. Pass Encrypted JSON Object.
userName	M	String	You need to pass username that is registered with emCA for API process.

Header Details

Key	Presence	Value	Description
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:

Request Body:

Content-Type : application/json
emKey	: 47b54594063957de22fce0aeddd51a6adf4a80aa

{
 
"requestData":"Q/5rvKIZvoMfuZQnysxcGawX4wC1xRttkCHEExreOwUCltgPG0FmsAbEmNHgHvdM2A 7Vadyks2IDACydZDRG9rS/uq93IO3KMAyazof7IJXz31c3LiXorwiRksUFOrH2IqYbqI1q88Sf3rnxoTd q8oaOzYB2LoNPh8dZihJyDIR33BccF1Dg/sS/UAwxJ3fjbPzRJpFcqhi2FX1IS8TxyW2PZtPyLtSddyDF xliryGv8RMmVem6NdJYeNHcYo82qHtszdepvIWCi/DLCqs1alR9TcOsKQ8skBTUQY5xfiuONm68zytXBl F+MIAB40Wsw/12zywoCe2z14wqA/mvzF6Jd/Cw3059NfW8FtmBS502ty4l+kSDallVUCSFP9b9Drsh4q/ giwT+zHa/SQ3LWCFkjDLaB/OMzMaZfAFwm27/mDB4mSWVMPzMo8CDBvNNNekeV6lSeKSJ7rEbR2JJYIeL zQFp++Dvnp0KZHZu5r+muXAPFCnsDj3MbLrpvbdl3VYKjtDCu0MXi/LX787pStPvr9coMmHTCwja5p7Rw I7Ji/nbOnVpT8f2ylx/Rq7vTFRGAqnFmEK5HAkN6Owdf/dKaKUtifXzJqgjYft0NS7uoXbEJWbb4I86Aq LhsPbqqN2zlOXZIaYLvkoleo//gAcevv6ZS3jk5rkhueR44ablyv5nhgQ25Fhg5cqu4hxUBOi1MRXk5Rp A6RZkaz+DPGSsJJ4+yKzTEnxhUZvnqzeFEf1cvIU3Fx9PLmvrQ50cE28AdNu749WOUyjq/eZCFC1rmY6K yThU4ng49S+iqCrUiIIF+McgjbuVPRvy0M9eYi9HpVOduV7XEI2zrRLpID0ueVwo/j6XePsofLvk/5J/x T9S8Ge6wgVNQzkO47eLi2VEPf5OXRopBaSLFZ1SPIgBVumlSnPgLfdNVOirJjhqMyADZrXgoAw3c+YTqR hsRDAhtPKx90Qtw643eLEi/1ujz9ZxB6yzTvFYnh05eaM+N08QVlEJcS+z84vqnY6/+8746T6Ct/tDrLd FCNVvveSEPVCujbE6LI6pzAnNuHWZoFYoDjANRTDuS8m3LY3mcC24cTJnNTt7a/hF6IsUj0ygfVctkpAT XvW9p1m4p6BpYmXFSP6w0nMvKnHd+Uy2R3qykk/1R6YoZbaG9dM3LrAqqAILkYNucL32xZCbSSKX6HIQt Z0WMAfTubYXLsDnAZCLeph1P+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) is retrieved.

• First the emCA service will validate username and password and check 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
response	String	Returns JSON Object

JSON Object Contains below parameters

Parameter	Data Type	Description
status	String	Returns Status of the request as success, if x509 certificate is available with respect to your account and serial number passed. Returns status of the request as failure when authentication fails or unregistered user tries to call the API
result	String	Returns In case of success: base 64 encoded x509 certificate data In case of failure: error message will be displayed.
subscriberId	String	Returns Subscriber Id
requestId	String	Return Request ID null.

Response JSON Format

Sample:
Success:
Response Body(Is Manual Authorization Enabled is “not“ checked from emCA)
{
"status":"success",
"result":" base 64 encoded x509 certificate	data"
“subscriberId”:”XXX” "requestId": null 
}


Response Body (Is Manual Authorization Enabled is checked from emCA )
{
"status": "Success",
"result": " your request proceded sucssusfully", "subscriberId": "XXXX",
"requestId": “XXXX”,
}
Failure:
{
"status":"failure", "result":"<Error message>" “subscriberId”:null
"requestId": null
}

Sample Base64 encoded x509 certificate data

"MIIF8jCCBNqgAwIBAgIDLceWMA0GCSqGSIb3DQEBDQUAMIHOMRwwGgYDVQQDExNDQSBDZXJ0aWZpY2F0Z
SAyMDE4MR4wHAYDVQQzExUzcmQgRmxvb3IsIFNhaSBBcmNhZGUxIzAhBgNVBAkTGk91dGVyIFJpbmcgUm9 hZCwgQmFuZ2Fsb3JlMRIwEAYDVQQIEwlLYXJuYXRha2ExDzANBgNVBBETBjU2MDEwMzEdMBsGA1UECxMUQ
2VydGlmeWluZyBBdXRob3JpdHkxGDAWBgNVBAoTD2VNdWRocmEgTGltaXRlZDELMAkGA1UEBhMCSU4wHhc NMTgwNDIzMDUyNzU2WhcNMTkwNDIzMDUyNzU2WjCBxTEmMCQGCSqGSIb3DQEJARMXZ3ZjLnRodWxhc2lAZ W11ZGhyYS5jb20xSTBHBgNVBAUTQDI0OUM2NUMyOUEwOTk3QkU1MDI0RjQxMDJFOUE2M0ExNUJEQzZDOTF
COTgyNkI3NkY1QTE3Nzg1RDVFNDNEQzAxEzARBgNVBAMTClRodWxhc2lHVkMxCzAJBgNVBAgTAklOMQ8wD QYDVQQREwY1NjAxMDMxEDAOBgNVBAoTB2VtdWRocmExCzAJBgNVBAYTAklOMIIBIjANBgkqhkiG9w0BAQE FAAOCAQ8AMIIBCgKCAQEAuPTB+4hzhe1N39Enxr7M0w2MUF1SkIsJ/GCedIZx2+2mMr5PRc2bJaDdGz2V8
4R72Qo5Ip2IbE3cpZoAJC7SADw7wgcMLD43C0hZcOVudtbGBR4cua4KVg5Yxv01czkykBP8RWoUm4zzHKw 59pdmT8VVoRWL5MsqgpXfYRo3ww600vJBXKKdzxwbLTZcNZiqNqvSPDQqXUJxD1CMw517c42RKr9MByfCw
uxJOTvqX38nLuzlAhtWteuoMDJzKZ9pxTaGOnJYLa7NyuhKPE/3LU1sRQlXLHofEYdHF1yuPvg6mpMc9vc yt8P++1kjmKqsrWEV/FhNlDrMi99cm7kKtQIDAQABo4IB3jCCAdowDAYDVR0TAQH/BAIwADAfBgNVHSMEG DAWgBTSSTNBL5qAHGduRbBeL0KICGMpmTAdBgNVHQ4EFgQUrse8FS90nKb28BBKvyUerfJZczkwCwYDVR0 PBAQDAgUgMHoGCCsGAQUFBwEBBG4wbDBFBggrBgEFBQcwAoY5aHR0cDovL3d3dy5lLW11ZGhyYS5jb20vc mVwb3NpdG9yeS9jYWNlcnRzL0MySVNDQTIwMTQuY3J0MCMGCCsGAQUFBzABhhdodHRwOi8vb2NzcC5lbXV kaHJhLmNvbTCBtwYDVR0gBIGvMIGsMFgGBmCCZGQCAjBOMEwGCCsGAQUFBwICMEAePgBOAG8AdABpAGMAZ QAgAFQAZQB4AHQAPQBDAGwAYQBzAHMAIAAyACAAQwBlAHIAdABpAGYAaQBjAGEAdABlMFAGB2CCZGQBCAI
wRTBDBggrBgEFBQcCARY3aHR0cDovL3d3dy5lLW11ZGhyYS5jb20vcmVwb3NpdG9yeS9jcHMvZS1NdWRoc mFfQ1BTLnBkZjBHBgNVHR8EQDA+MDygOqA4hjZodHRwOi8vd3d3LmUtbXVkaHJhLmNvbS9yZXBvc2l0b3J 5L2NybHMvQzJJU0NBMjAxNC5jcmwwDQYJKoZIhvcNAQENBQADggEBAGWRqd19occ772Ci8AqHTVJnj3yuF Ej3cLTbP5YuvY20TNQ9wRLrF2Q6sldsbpLS60wNlsu2kONyu18+pdSPuudDqoR672GmP32AO1SlwsjTK3F Cl8y9vj7+lnTFdcMDrQJ8e4dtMkObL2tCShuKAbALl3bdytM5l3zqf7/6utjXUcY6No7huXEVCdCQEskZ3 qiGd41ya/S92I46IgPv/yH0wERr6ZPeFG0hVYkuMwtJ59xlZDJ6C4YPWP9U8isK77ngSDR/KUGD8om9JQt JQuwpXj8vl+MXvz3gi774PRltkXVTmeCOyhRfZwwkj96i0b07msvjVGnw0xLSow0Qzhg="

Error Messages

Error Message	Description
invalid input ~ Signature does not contain valid data	If signature parameter (CSR) contains invalid data (Subject DN details, key algorithm & size, pfx password)
Signature verification failed	If signature parameter (certificate serial number) contains invalid certificate serial number.
Insufficient data	If data to create PFX does not contain required details of selected certificate profile
No Data Found For <serial number>	If no certificate is available for requested certificate serial number