2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FSecCertICertificate.h
19 * @brief This is the header file for the %ICertificate interface.
21 * This header file contains the declarations of the %ICertificate interface.
23 #ifndef _FSEC_CERT_ICERTIFICATE_H_
24 #define _FSEC_CERT_ICERTIFICATE_H_
26 #include <FBaseString.h>
27 #include <FBaseByteBuffer.h>
28 #include <FSecIPublicKey.h>
30 namespace Tizen { namespace Security { namespace Cert
34 * @enum CertificateType
36 * Defines the type of security certificate.
42 ROOT_CA, /**< The Factory-supplied certificates for SSL: ROOT CA */
43 OPERATOR_DOMAIN, /**< The operator domain certificate */
44 TRUSTED_THIRD_PARTY_DOMAIN, /**< The trusted third party domain certificate*/
45 USER_CERT, /**< The user certificate */
46 UNKNOWN_TYPE = 10, /**< The unknown type certificate*/
50 * @enum ValidityPeriod
52 * Defines the certificate validity period.
58 VALIDITY_PERIOD_VALID, /**< The certificate is valid */
59 VALIDITY_PERIOD_EXPIRED, /**< The certificate has expired */
60 VALIDITY_PERIOD_NOT_YET_VALID, /**< The certificate period is not yet valid */
64 * @interface ICertificate
65 * @brief This interface manages a variety of identity certificates.
69 * The %ICertificate interface is an abstraction for certificates having different formats. For example, different types of
70 * certificates, such as X.509 and PGP, share general functionalities, namely encoding and verifying, and information like
71 * public keys. Despite containing different sets of information and having different ways for storing and retrieving them,
72 * the X.509, X.968, and WTLS certificates can all be implemented by using the %ICertificate interface.
74 * An identity certificate is a binding of a principal to a public key, which is vouched for by another principal.
75 * A principal represents an entity, such as an individual user, a group, or a corporation. @n
77 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/security/certificate_namespace.htm">Certificates</a>.
79 * The following example demonstrates how to use the %ICertificate interface.
85 * MyCertificate::Sample(void)
87 * X509Certificate *pCertificate = null;
88 * String serialNumber;
94 * ByteBuffer *pSignature = null;
95 * ByteBuffer *pFingerprint = null;
97 * result r = E_FAILURE;
99 * String fileName(Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/UTsSecurity/Security/Domain3Certs/TestCert1-1.der");
101 * FileAttributes attribute;
103 * r = file.Construct(fileName, L"r");
109 * r = file.GetAttributes(fileName, attribute);
115 * r = input.Construct((int)attribute.GetFileSize());
121 * r = file.Read(input);
129 * pCertificate = new X509Certificate;
130 * pCertificate->Construct(input);
132 * serialNumber = pCertificate->GetSerialNumber();
133 * algorithm = pCertificate->GetSignatureAlgorithm();
134 * start = pCertificate->GetNotBefore();
135 * end = pCertificate->GetNotAfter();
136 * subjectName = pCertificate->GetSubject();
137 * issuerName = pCertificate->GetIssuer();
139 * pSignature = pCertificate->GetSignatureN();
140 * if (pSignature == null)
145 * pFingerprint = pCertificate->GetFingerprintN();
146 * if (pFingerprint == null)
156 * delete pCertificate;
164 * delete pFingerprint;
172 class _OSP_EXPORT_ ICertificate
177 * This is the destructor for this class.
181 virtual ~ICertificate(void) {}
184 * Gets the format name for this certificate.
188 * @return The certificate format
190 virtual Tizen::Base::String GetFormat(void) const = 0;
193 * Gets the certificate type.
197 * @return The certificate type
198 * @exception E_SUCCESS The method is successful.
199 * @exception E_SYSTEM Either of the following conditions has occurred:
200 * - A system error has occurred.
201 * - The certificate link list operation has failed.
202 * @remarks The specific error code can be accessed using the GetLastResult() method.
204 virtual CertificateType GetType(void) const = 0;
207 * Gets the encoded form of the certificate. @n
208 * It is assumed that each certificate type has a single form of encoding. For example, X.509 certificates can be encoded as ASN.1 DER.
212 * @return A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
213 * else @c null if an error occurs
214 * @exception E_SUCCESS The method is successful.
215 * @exception E_OUT_OF_MEMORY The memory is insufficient.
216 * @exception E_SYSTEM Either of the following conditions has occurred:
217 * - A system error has occurred.
218 * - The certificate link list operation has failed.
219 * - The Tizen::Base::ByteBuffer operation has failed.
220 * @remarks The specific error code can be accessed using the GetLastResult() method.
222 virtual Tizen::Base::ByteBuffer* GetEncodedDataN(void) const = 0;
225 * Gets the fingerprint of the certificate. @n
226 * It is the hash value of the encoding of the certificate.
230 * @return A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
231 * else @c null if an error occurs
232 * @exception E_SUCCESS The method is successful.
233 * @exception E_OUT_OF_MEMORY The memory is insufficient.
234 * @exception E_SYSTEM Either of the following conditions has occurred:
235 * - A system error has occurred.
236 * - The certificate parsing operation has failed.
237 * - The Tizen::Base::ByteBuffer operation has failed.
238 * @remarks The specific error code can be accessed using the GetLastResult() method.
240 virtual Tizen::Base::ByteBuffer* GetFingerprintN(void) const = 0;
243 * Verifies whether the certificate is signed using the private key corresponding to the specified public key.
247 * @return @c true if the certificate is signed using the private key corresponding to the specified public key, @n
249 * @param[in] publicKey A reference to IPublicKey
250 * @exception E_SUCCESS The method is successful.
251 * @exception E_INVALID_ARG The specified @c publicKey is invalid or empty.
252 * @exception E_OUT_OF_MEMORY The memory is insufficient.
253 * @exception E_SYSTEM Either of the following conditions has occurred:
254 * - A system error has occurred.
255 * - The certificate parsing operation has failed.
256 * @remarks The specific error code can be accessed using the GetLastResult() method.
258 virtual bool Verify(const Tizen::Security::IPublicKey& publicKey) = 0;
261 * Gets the public key of this certificate.
265 * @return A pointer to the IPublicKey interface, @n
266 * else @c null if an error occurs
267 * @exception E_SUCCESS The method is successful.
268 * @exception E_OUT_OF_MEMORY The memory is insufficient.
269 * @exception E_KEY_NOT_FOUND The key is not found.
270 * @exception E_SYSTEM Either of the following conditions has occurred:
271 * - A system error has occurred.
272 * - The Tizen::Base::ByteBuffer operation has failed.
273 * @remarks The specific error code can be accessed using the GetLastResult() method.
275 virtual Tizen::Security::IPublicKey* GetPublicKeyN(void) const = 0;
278 * Gets the serial number of the certificate. @n
279 * The serial number is a unique integer assigned by the Certification Authority (CA) to each certificate (that is, the issuer name and serial number
280 * must identify a unique certificate). @n
282 * This is defined in ASN.1 as demonstrated in the following code:
285 * serialNumber CertificateSerialNumber.
287 * CertificateSerialNumber ::= INTEGER
290 * Since the serial number can be greater than the system's maximum defined value for @c int, the output parameter type
291 * is @c ByteBuffer, instead of @c int.
295 * @return The serial number of the certificate
296 * @exception E_SUCCESS The method is successful.
297 * @exception E_OUT_OF_MEMORY The memory is insufficient.
298 * @exception E_SYSTEM Either of the following conditions has occurred:
299 * - A system error has occurred.
300 * - The method has failed to get the certificate serial number information.
301 * @remarks The specific error code can be accessed using the GetLastResult() method.
303 virtual Tizen::Base::String GetSerialNumber(void) const = 0;
306 * Checks whether the certificate is currently valid. @n
307 * It is valid if the current date and time are within the validity period of the certificate. The validity period consists
308 * of two date and time values: the initial date and time, and the final date and time for the validity of the certificate. @n
310 * This is defined in ASN.1 as demonstrated in the following code:
315 * Validity ::= SEQUENCE {
316 * notBefore CertificateValidityDate,
317 * notAfter CertificateValidityDate }
319 * CertificateValidityDate ::= CHOICE {
321 * generalTime GeneralizedTime }
326 * @return The validity period of the certificate
327 * @exception E_SUCCESS The method is successful.
328 * @exception E_SYSTEM Either of the following conditions has occurred:
329 * - A system error has occurred.
330 * - The certificate link list operation has failed.
331 * @remarks The specific error code can be accessed using the GetLastResult() method.
333 virtual ValidityPeriod CheckValidityPeriod(void) = 0;
337 * Gets the notBefore value of Tizen::Base::String type from the validity period of the certificate. @n
338 * This value represents the date and time before which the certificate is not valid.
342 * @return A string representing the date and time value before which the certificate is not valid
343 * @exception E_SUCCESS The method is successful.
344 * @exception E_OUT_OF_MEMORY The memory is insufficient.
345 * @exception E_SYSTEM Either of the following conditions has occurred:
346 * - A system error has occurred.
347 * - The method has failed to get the certificate validity information.
348 * @remarks The specific error code can be accessed using the GetLastResult() method.
349 * @see Tizen::Security::Cert::X509Certificate::CheckValidityPeriod() for relevant ASN.1 definitions
351 virtual Tizen::Base::String GetNotBefore(void) const = 0;
355 * Gets the notAfter value of Tizen::Base::String type from the validity period of the certificate. @n
356 * This value represents the date and time after which the certificate is not valid.
360 * @return A string representing the date and time value after which the certificate is not valid
361 * @exception E_SUCCESS The method is successful.
362 * @exception E_OUT_OF_MEMORY The memory is insufficient.
363 * @exception E_SYSTEM Either of the following conditions has occurred:
364 * - A system error has occurred.
365 * - The method has failed to get the certificate validity information.
366 * @remarks The specific error code can be accessed using the GetLastResult() method.
367 * @see Tizen::Security::Cert::X509Certificate::CheckValidityPeriod() for relevant ASN.1 definitions
369 virtual Tizen::Base::String GetNotAfter(void) const = 0;
372 * Gets the name of the issuer of the certificate.
376 * @return The name of the issuer of the certificate
377 * @exception E_SUCCESS The method is successful.
378 * @exception E_OUT_OF_MEMORY The memory is insufficient.
379 * @exception E_SYSTEM Either of the following conditions has occurred:
380 * - A system error has occurred.
381 * - The method has failed to get the certificate issuer information.
382 * @remarks The specific error code can be accessed using the GetLastResult() method.
384 virtual Tizen::Base::String GetIssuer(void) const = 0;
387 * Gets the subject name of the certificate.
391 * @return The subject name of the certificate
392 * @exception E_SUCCESS The method is successful.
393 * @exception E_OUT_OF_MEMORY The memory is insufficient.
394 * @exception E_SYSTEM Either of the following conditions has occurred:
395 * - A system error has occurred.
396 * - The method has failed to get the certificate issuer information.
397 * @remarks The specific error code can be accessed using the GetLastResult() method.
399 virtual Tizen::Base::String GetSubject(void) const = 0;
402 * Gets the signature of the certificate.
406 * @return A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
407 * else @c null if an error occurs
408 * @exception E_SUCCESS The method is successful.
409 * @exception E_OUT_OF_MEMORY The memory is insufficient.
410 * @exception E_SYSTEM Either of the following conditions has occurred:
411 * - A system error has occurred.
412 * - The certificate link list operation has failed.
413 * - The Tizen::Base::ByteBuffer operation has failed.
414 * @remarks The specific error code can be accessed using the GetLastResult() method.
416 virtual Tizen::Base::ByteBuffer* GetSignatureN(void) const = 0;
420 // This method is for internal use only. Using this method can cause behavioral, security-related,
421 // and consistency-related issues in the application.
423 // This method is reserved and may change its name at any time without prior notice.
427 virtual void ICertificate_Reserved1(void) {}
430 // This method is for internal use only. Using this method can cause behavioral, security-related,
431 // and consistency-related issues in the application.
433 // This method is reserved and may change its name at any time without prior notice.
437 virtual void ICertificate_Reserved2(void) {}
440 // This method is for internal use only. Using this method can cause behavioral, security-related,
441 // and consistency-related issues in the application.
443 // This method is reserved and may change its name at any time without prior notice.
447 virtual void ICertificate_Reserved3(void) {}
451 } } } //Tizen::Security::Cert
453 #endif //_FSEC_CERT_ICERTIFICATE_H_