2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FSecCert_CertService.h
20 * @brief This header file contains the declarations of CertService APIs.
22 * This header file contains the declarations of CertService APIs.
25 #ifndef _FSEC_CERT_INTERNAL_CERT_SERVICE_H_
26 #define _FSEC_CERT_INTERNAL_CERT_SERVICE_H_
28 #include <FOspConfig.h>
30 #include "FSecCert_CertTypes.h"
32 namespace Tizen { namespace Security { namespace Cert
37 * @brief This class is provide Services API for Certificate Management.
40 * The %_CertService class is used for to provide Certificate Management's Services API.
42 * For more information on the class features, see <a href="../com.osp.cppappprogramming.help/html/dev_guide/security/certificate_namespace.htm">Certificates</a>.
45 class _OSP_EXPORT_ _CertService
49 * This function opens the context identified by calling application.
52 * @return An error code.
53 * @param[in] type Calling application type.
54 * @param[out] pCertCtx Pointer to context as out parameter.
55 * @exception E_SUCCESS The method is successful.
56 * @exception E_INVALID_ARG The specified input parameter is invalid.
57 * @exception E_OUT_OF_MEMORY The memory is insufficient.
59 static result OpenContext(_CertContextType type, CertChainCtx* pCertCtx);
62 * This function closes the opened context.
65 * @return An error code.
66 * @param[in] certCtx Handle to certificate context.
67 * @exception E_SUCCESS The method is successful.
68 * @exception E_INVALID_ARG The specified input parameter is invalid.
70 static result CloseContext(CertChainCtx certCtx);
73 * This function adds the input certificate in the opened certificate context.
76 * @return An error code.
77 * @param[in] certCtx Handle to the certificate context.
78 * @param[in] pCertBuf Certificate pBuffer.
79 * @param[in] certLen Certificate pBuffer length.
80 * @exception E_SUCCESS The method is successful.
81 * @exception E_INVALID_ARG The specified input parameter is invalid.
82 * @exception E_OUT_OF_MEMORY The memory is insufficient.
83 * @exception E_SYSTEM A system error has occurred.
84 * - Certificate Link list operation error.
86 static result AddCertificate(CertChainCtx certCtx, byte* pCertBuf, int certLen);
89 * This function verifies the certificate chain in certificate context with respect to installed root certificates in the device.
92 * @return An error code.
93 * @param[in] certCtx Handle to certificate chain context.
94 * @param[out] pDomain Root certificate domain type.
95 * @exception E_SUCCESS The method is successful.
96 * @exception E_INVALID_ARG The specified input parameter is invalid.
97 * @exception E_SYSTEM A system error has occurred.
98 * - Certificate Link list operation error.
100 static result VerifyChain(CertChainCtx certCtx, _CertDomainType* pDomain);
103 * This function verifies the certificate chain in certificate context with respect to installed root certificates in the DB.
106 * @return An error code.
107 * @param[in] pCertCtx Handle to certificate chain context.
108 * @exception E_SUCCESS The method is successful.
109 * @exception E_INVALID_ARG The specified input parameter is invalid.
110 * @exception E_OUT_OF_MEMORY The memory is insufficient.
111 * @exception E_SYSTEM An unexpected system error has occurred.
113 static result VerifyCertificateChain(CertChainCtx pCertCtx);
116 * This function gets number of certificates in certificate chain represented by context.
119 * @return An error code.
120 * @param[in] certCtx Handle to certificate context.
121 * @param[out] pDepth Chain depth information.
122 * @exception E_SUCCESS The method is successful.
123 * @exception E_INVALID_ARG The specified input parameter is invalid.
125 static result GetChainDepth(CertChainCtx certCtx, int* pDepth);
128 * This function gets nth certificate handle of the chain represented by input context
131 * @return An error code.
132 * @param[in] certCtx Handle to certificate context.
133 * @param[in] nth Position of certificate.
134 * @param[out] phCerticate Pointer to handle of certificate.
135 * @exception E_SUCCESS The method is successful.
136 * @exception E_INVALID_ARG The specified input parameter is invalid.
137 * @exception E_SYSTEM An unexpected system error has occurred.
139 static result GetNthCert(CertChainCtx certCtx, int nth, CertificateHandle* phCerticate);
142 * This function breaks certificate chain buffer into individual certificate.
143 * It is assumed here that there is no Private Key in the Chain.
144 * Chain can contain multiple certificate including Device, Intermediate and CA Certificate.
145 * This will return a Structure HCertChainCtx containing all the certificates.
148 * @return An error code.
149 * @param[in] pCertChainBuffer Certificate chain buffer.
150 * @param[in] certChainLength Certificate chain buffer length.
151 * @param[out] pCertCtx Certificate chain list containing individual certificate.
152 * @exception E_SUCCESS The method is successful.
153 * @exception E_INVALID_ARG The specified input parameter is invalid.
154 * @exception E_OUT_OF_MEMORY The memory is insufficient.
155 * @exception E_SYSTEM An unexpected system error has occurred.
157 static result GetParsedCertificateChainN(char* pCertChainBuffer, int certChainLength, CertChainCtx* pCertCtx);
160 * This function retrieves the device certificate chain on the basis of Subject name of Device Certificate.
161 * This function retrieves the certificate chain on the basis of Subject name of Device Certificate as function
162 * parameters. If there are multiple cert chain from the same issuer, it will get all the cert chain and check
163 * with subject name to decide which chain is need to be returned.
166 * @return An error code.
167 * @param[in] pSubjectName Pointer to Subject name.
168 * @param[in] subjectNameLength Length of Subject name.
169 * @param[out] pCertChainCtx Pointer to certificate chain.
170 * @param[out] pPrivateKeyCtx Pointer to private key info.
171 * @exception E_SUCCESS The method is successful.
172 * @exception E_INVALID_ARG The specified input parameter is invalid.
173 * @exception E_OUT_OF_MEMORY The memory is insufficient.
174 * @exception E_SYSTEM An unexpected system error has occurred.
176 static result GetUserCertChainBySubjectName(char* pSubjectName, int subjectNameLength, CertChainCtx* pCertChainCtx, PrivateKeyCtx* pPrivateKeyCtx);
179 * This function returns the handle of certificate of input binary or base64 certificate pBuffer.
182 * @return An error code.
183 * @param[in] pBuffer Buffer of certificate.
184 * @param[in] bufLen Length of input pBuffer.
185 * @param[out] pCertHandle Handle to the certificate out.
186 * @exception E_SUCCESS The method is successful.
187 * @exception E_INVALID_ARG The specified input parameter is invalid.
188 * @exception E_OUT_OF_MEMORY The memory is insufficient.
189 * @exception E_SYSTEM An unexpected system error has occurred.
191 static result OpenCertificate(char* pBuffer, int bufLen, CertificateHandle* pCertHandle);
194 * This function closes the handle of certificate .
197 * @return An error code.
198 * @param[in] pCertHandle Handle to the certificate to close.
199 * @exception E_SUCCESS The method is successful.
200 * @exception E_INVALID_ARG The specified input parameter is invalid.
201 * @exception E_SYSTEM An unexpected system error has occurred.
202 * @remarks This function is not applicable to handle which is received by context APIs.
204 static result CloseCertificate(CertificateHandle* pCertHandle);
207 * This function verifies a certificate using given Public key.
210 * @return An error code.
211 * @param[in] certHandle Handle to certificate.
212 * @param[in] pPublickey Certificate Public Key.
213 * @param[in] keyLen Certificate Public Key length.
214 * @exception E_SUCCESS The method is successful.
215 * @exception E_INVALID_ARG The specified input parameter is invalid.
216 * @exception E_SYSTEM A system error has occurred.
217 * - Certificate Link list operation error.
219 static result VerifyCert(CertificateHandle certHandle, byte* pPublickey, int keyLen);
222 * This function gets certificate pBuffer using the certificate handle.
225 * @return An error code.
226 * @param[in] certHandle Handle to certificate.
227 * @param[out] pBuffer Pointer to certificate pBuffer.
228 * @param[out] certLen Output pBuffer length of certificate.
229 * @exception E_SUCCESS The method is successful.
230 * @exception E_INVALID_ARG The specified input parameter is invalid.
231 * @exception E_OUT_OF_MEMORY The memory is insufficient.
232 * @exception E_SYSTEM An unexpected system error has occurred.
234 static result GetCertBufferN(CertificateHandle certHandle, char*& pBuffer, int* certLen);
237 * This function returns database Id of Ca certificate for given certificate handle.
240 * @return An error code.
241 * @param[in] certHandle Handle to the certificate.
242 * @param[in] certType Type of certificate store.
243 * @param[out] certId Reference to integer to get certificate data Id.
244 * @exception E_SUCCESS The method is successful.
245 * @exception E_INVALID_ARG The specified input parameter is invalid.
246 * @exception E_OUT_OF_MEMORY The memory is insufficient.
247 * @exception E_SYSTEM An unexpected system error has occurred.
249 static result GetCaCertificateId(CertificateHandle certHandle, _CaCertType certType, int& certId);
252 * This function returns database Id of User certificate for given certificate handle.
255 * @return An error code.
256 * @param[in] certHandle Handle to the certificate.
257 * @param[out] certId Reference to integer to get certificate data Id.
258 * @exception E_SUCCESS The method is successful.
259 * @exception E_INVALID_ARG The specified input parameter is invalid.
260 * @exception E_OUT_OF_MEMORY The memory is insufficient.
261 * @exception E_SYSTEM An unexpected system error has occurred.
263 static result GetUserCertificateId(CertificateHandle certHandle, int& certId);
266 * This function returns information of certificate requested by _CertFieldType parameter.
269 * @return An error code.
270 * @param[in] certHandle Handle to the certificate.
271 * @param[in] field Type of combination of information required.
272 * @param[out] pCertInfo Pointer to certificate information structure.
273 * @exception E_SUCCESS The method is successful.
274 * @exception E_INVALID_ARG The specified input parameter is invalid.
275 * @exception E_OUT_OF_MEMORY The memory is insufficient.
276 * @exception E_SYSTEM An unexpected system error has occurred.
278 static result GetCertInfo(CertificateHandle certHandle, _CertFieldType field, _CertFieldInfos* pCertInfo);
281 * This function returns Public key of certificate in DER format.
284 * @return An error code.
285 * @param[in] certHandle Handle to the certificate.
286 * @param[out] pBuffer Buffer to contain public key.
287 * @param[in,out] pBufLen Length of Public Key.
288 * @exception E_SUCCESS The method is successful.
289 * @exception E_INVALID_ARG The specified input parameter is invalid.
290 * @exception E_SYSTEM An unexpected system error has occurred.
292 static result GetCertPublicKey(CertificateHandle certHandle, char* pBuffer, int* pBufLen);
295 * This function returns Signature of certificate.
298 * @return An error code.
299 * @param[in] certHandle Handle to the certificate.
300 * @param[out] pBuffer Buffer to contain Signature.
301 * @param[in,out] bufLen Length of Signature.
302 * @exception E_SUCCESS The method is successful.
303 * @exception E_INVALID_ARG The specified input parameter is invalid.
304 * @exception E_SYSTEM An unexpected system error has occurred.
306 static result GetCertSignature(CertificateHandle certHandle, char* pBuffer, int* pBufLen);
309 * This function returns Version of X509 certificate.
312 * @return certificate version number as integer, -1 in case of failure.
313 * @param[in] certHandle Handle to the certificate.
314 * @remarks The specific error code can be accessed using the GetLastResult() method.
316 static int GetCertVersion(CertificateHandle certHandle);
319 * This function provides certificate subject name given by a certificate handlder. It is complete certificate subject name buffer.
322 * @return An error code.
323 * @param[in] certificateHandle Handle to certificate.
324 * @param[out] ppSubjectNameRef Subject name buffer.
325 * @param[out] pSubjectNameLength Subject name length.
326 * @exception E_SUCCESS The method is successful.
327 * @exception E_INVALID_ARG The specified input parameter is invalid.
328 * @exception E_SYSTEM An unexpected system error has occurred.
330 static result GetSubjectNameN(CertificateHandle certificateHandle, byte*& ppSubjectNameRef, int* pSubjectNameLength);
333 * This function provides certificate issuer name given by a certificate handlder. It is complete certificate issuer name buffer.
336 * @return An error code.
337 * @param[in] certificateHandle Handle to certificate.
338 * @param[out] pIssuerNameRef Issuer name buffer.
339 * @param[out] pIssuerNameLength Subject name length.
340 * @exception E_SUCCESS The method is successful.
341 * @exception E_INVALID_ARG The specified input parameter is invalid.
342 * @exception E_SYSTEM An unexpected system error has occurred.
344 static result GetIssuerNameN(CertificateHandle certificateHandle, byte*& pIssuerNameRef, int* pIssuerNameLength);
347 * This function checks certificates validity.
350 * @return An error code.
351 * @param[in] certHandle Handle to the certificate.
352 * @param[out] pValidity Validity of certificate; Valid, Expired or Validity Yet to start.
353 * @exception E_SUCCESS The method is successful.
354 * @exception E_INVALID_ARG The specified input parameter is invalid.
355 * @exception E_SYSTEM An unexpected system error has occurred.
357 static result CheckCertValidity(CertificateHandle certHandle, _CertValidityType* pValidity);
360 * This function checks certificate type.
363 * @return An error code.
364 * @param[in] certHandle Handle to the certificate.
365 * @param[out] pCertType Type of certificate.
366 * @exception E_SUCCESS The method is successful.
367 * @exception E_INVALID_ARG The specified input parameter is invalid.
368 * @exception E_SYSTEM An unexpected system error has occurred.
370 static result CheckCertType(CertificateHandle certHandle, _CaCertType* pCertType);
373 * This function breaks certificate chain buffer into individual certificate.
374 * It is assumed here that there is no Private Key in the Chain.
375 * Chain can contain multiple certificate including Device, Intermediate and CA Certificate.
376 * This will return a Structure ppCertChainList containing all the certificates.
379 * @return An error code.
380 * @param[in] pCertChainBuffer Certificate chain buffer.
381 * @param[in] certChainLength Certificate chain buffer length.
382 * @param[out] ppCertChainListRef Certificate chain list containing individual certificate.
383 * @exception E_SUCCESS The method is successful.
384 * @exception E_INVALID_ARG The specified input parameter is invalid.
385 * @exception E_OUT_OF_MEMORY The memory is insufficient.
386 * @exception E_SYSTEM An unexpected system error has occurred.
388 static result MakeCertChainFromBufferN(char* pCertChainBuffer, int certChainLength, _CertRootList*& ppCertChainListRef);
391 * This function gets the certificate list information by requested format.
394 * @return An error code.
395 * @param[in] certFormat Format of requested certificates.
396 * @param[in,out] pCertList Pointer to pointer of Certificate list structure.
397 * @param[out] count Number of certificates in the list.
398 * @exception E_SUCCESS The method is successful.
399 * @exception E_INVALID_ARG The specified input parameter is invalid.
400 * @exception E_SYSTEM An unexpected system error has occurred.
402 static result GetCertListByFormatN(_CertFormat certFormat, _CertificateListInfo*& pCertList, int* count);
405 * This function gets the root certificate list information by requested certificate ID
408 * @return An error code.
409 * @param[in] certId Format of requested device certificates.
410 * @param[out] pCertList Pointer to pointer of Certificate list structure.
411 * @exception E_SUCCESS The method is successful.
412 * @exception E_INVALID_ARG The specified input parameter is invalid.
413 * @exception E_SYSTEM An unexpected system error has occurred.
415 static result GetCaCertListByCertIdN(int certId, _CertificateListInfo*& pCertList);
418 * This function retrieves domain certificate information.
421 * @return If success this function returns certId installed certificates, -1 in case of failure.
422 * @param[out] ppDcInfo information about domain certificate.
423 * @remarks The specific error code can be accessed using the GetLastResult() method.
425 static int GetDomainCertInfoN(_CertFieldInfos*& prDcInfo);
428 * This function retrieves certificate information given by a certificate ID.
431 * @return An error code.
432 * @param[in] certId Certificate ID.
433 * @param[out] pDcInfo Pointer to certificate information structure.
434 * @exception E_SUCCESS The method is successful.
435 * @exception E_INVALID_ARG The specified input parameter is invalid.
436 * @exception E_SYSTEM An unexpected system error has occurred.
438 static result GetCaCertInfoByCertId(int certId, _CertFieldInfos* pDcInfo);
441 * This function gets the user certificate list information by requested format.
444 * @return An error code.
445 * @param[in] certFormat Format of requested user certificates.
446 * @param[out] pUserCertListInfoTypesRef Pointer to pointer of Certificate list structure.
447 * @param[out] pCount Number of certificates in the list.
448 * @exception E_SUCCESS The method is successful.
449 * @exception E_INVALID_ARG The specified input parameter is invalid.
450 * @exception E_OUT_OF_MEMORY The memory is insufficient.
451 * @exception E_SYSTEM An unexpected system error has occurred.
453 static result GetUserCertListInfoTypesByFormatN(_CertFormat certFormat, _CertificateListInfo*& pUserCertListInfoTypesRef, int* pCount);
456 * This function retrieves all user certificate information.
459 * @return This function returns certId of installed user certificates.
460 * @param[out] pCertFieldInfosRef User certificate information.
461 * @remarks The specific error code can be accessed using the GetLastResult() method.
463 static int GetUserCertFieldInfoN(_CertFieldInfos*& pCertFieldInfosRef);
466 * This function provides the path of CRT file, which contains all the installed certificate in PEM format.
469 * @return Path of CRT file containing all certificates in PEM format.
471 static Tizen::Base::String GetCertificateCrtFilePath(void);
474 * This function frees the certificate list given by a certificate list.
477 * @return An error code.
478 * @param[in] pCertList Pointer to certificate link list.
479 * @exception E_SUCCESS The method is successful.
480 * @exception E_INVALID_ARG The specified input parameter is invalid.
482 static result FreeCertList(_CertificateListInfo* pCertList);
485 * This function frees the certificate info given by a struct _CertInfo.
488 * @return An error code.
489 * @param[in] pCertInfo Pointer to certificate info.
490 * @exception E_SUCCESS The method is successful.
492 static result FreeCertificateInfo(_CertInfo* pCertInfo);
495 * This function frees the root certificate list.
498 * @return An error code.
499 * @param[in] pRootCertList Pointer to root certificate link list.
500 * @exception E_SUCCESS The method is successful.
501 * @exception E_INVALID_ARG The specified input parameter is invalid.
503 static result FreeRootCertList(_CertRootList* pRootCertList);
506 * This function closes the opened private key context.
509 * @return An error code.
510 * @param[in] certCtx Handle to private key context.
511 * @exception E_SUCCESS The method is successful.
512 * @exception E_INVALID_ARG The specified input parameter is invalid.
514 static result ClosePrivateKeyContext(PrivateKeyCtx privateKeyCtx);
519 _CertService(const _CertService& rhs);
523 _CertService& operator =(const _CertService& rhs);
527 } } } //Tizen::Security::Cert
529 #endif // _FSEC_CERT_INTERNAL_CERT_SERVICE_H_