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 FSecCertICertificate.h
20 * @brief This is the header file for the %ICertificate interface.
22 * This header file contains the declarations of the %ICertificate interface.
24 #ifndef _FSEC_CERT_ICERTIFICATE_H_
25 #define _FSEC_CERT_ICERTIFICATE_H_
27 #include <FBaseString.h>
28 #include <FBaseByteBuffer.h>
29 #include <FSecIPublicKey.h>
31 namespace Tizen { namespace Security { namespace Cert
35 * @enum CertificateType
37 * Defines the type of certificate.
43 ROOT_CA, /**< The Factory-supplied certificates for SSL: ROOT CA */
44 OPERATOR_DOMAIN, /**< The Operator Domain */
45 TRUSTED_THIRD_PARTY_DOMAIN, /**< The Trusted Third Party Domain */
46 USER_CERT, /**< The User Certificates */
47 UNKNOWN_TYPE = 10, /**< The unknown type */
51 * @enum ValidityPeriod
53 * Defines the validity period.
59 VALIDITY_PERIOD_VALID, /**< The validity period */
60 VALIDITY_PERIOD_EXPIRED, /**< The expiry period */
61 VALIDITY_PERIOD_NOT_YET_VALID, /**< The period that is not yet valid */
65 * @interface ICertificate
66 * @brief This interface manages a variety of identity certificates.
70 * The %ICertificate interface is an abstraction for certificates having different formats. For example, different types of certificates, such as X.509 and PGP, share
71 * general functionalities, namely encoding and verifying, and some type of information like 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 format of this certificate
190 virtual Tizen::Base::String GetFormat(void) const = 0;
193 * Gets the certificate type.
197 * @return The type of this certificate
198 * @exception E_SUCCESS The method is successful.
199 * @exception E_SYSTEM A system error has occurred. @n
200 * The certificate link list operation has failed.
201 * @remarks The specific error code can be accessed using the GetLastResult() method.
203 virtual CertificateType GetType(void) const = 0;
206 * Gets the encoded form of the certificate. @n
207 * 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.
211 * @return A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
212 * else @c null if an error occurs
213 * @exception E_SUCCESS The method is successful.
214 * @exception E_OUT_OF_MEMORY The memory is insufficient.
215 * @exception E_SYSTEM A system error has occurred. @n
216 * The certificate link list operation or the
217 * Tizen::Base::ByteBuffer operation has failed.
218 * @remarks The specific error code can be accessed using the GetLastResult() method.
220 virtual Tizen::Base::ByteBuffer* GetEncodedDataN(void) const = 0;
223 * Gets the fingerprint of the certificate. @n
224 * It is the hashed value of the encoding of the certificate.
228 * @return A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
229 * else @c null if an error occurs
230 * @exception E_SUCCESS The method is successful.
231 * @exception E_OUT_OF_MEMORY The memory is insufficient.
232 * @exception E_SYSTEM A system error has occurred. @n
233 * The certificate parsing operation or
234 * the Tizen::Base::ByteBuffer operation has failed.
235 * @remarks The specific error code can be accessed using the GetLastResult() method.
237 virtual Tizen::Base::ByteBuffer* GetFingerprintN(void) const = 0;
240 * Verifies whether the certificate is signed using the private key corresponding to the specified public key.
244 * @return @c true if the certificate is signed using the private key corresponding to the specified public key, @n
246 * @param[in] publicKey A reference to IPublicKey
247 * @exception E_SUCCESS The method is successful.
248 * @exception E_INVALID_ARG The specified @c publicKey is invalid or empty.
249 * @exception E_OUT_OF_MEMORY The memory is insufficient.
250 * @exception E_SYSTEM A system error has occurred. @n
251 * The certificate parsing operation has failed.
252 * @remarks The specific error code can be accessed using the GetLastResult() method.
254 virtual bool Verify(const Tizen::Security::IPublicKey& publicKey) = 0;
257 * Gets the public key of this certificate.
261 * @return A pointer to the IPublicKey interface, @n
262 * else @c null if an error occurs
263 * @exception E_SUCCESS The method is successful.
264 * @exception E_OUT_OF_MEMORY The memory is insufficient.
265 * @exception E_KEY_NOT_FOUND The key is not found.
266 * @exception E_SYSTEM A system error has occurred. @n
267 * The Tizen::Base::ByteBuffer operation has failed.
268 * @remarks The specific error code can be accessed using the GetLastResult() method.
270 virtual Tizen::Security::IPublicKey* GetPublicKeyN(void) const = 0;
273 * Gets the @c serialNumber value from the certificate. @n
274 * The serial number is an integer assigned by the Certification Authority (CA) to each certificate. It is unique for each certificate issued by a
275 * given CA (that is, the issuer name and serial number must identify a unique certificate). @n
277 * The ASN.1 definition for this is as follows:
280 * serialNumber CertificateSerialNumber.
282 * CertificateSerialNumber ::= INTEGER
285 * Since the serial number can be greater than the system's maximum value for @c int, the output parameter type is @c ByteBuffer, instead of @c int.
289 * @return The serial number of the certificate
290 * @exception E_SUCCESS The method is successful.
291 * @exception E_OUT_OF_MEMORY The memory is insufficient.
292 * @exception E_SYSTEM A system error has occurred. @n
293 * The method has failed to get the certificate serial number information.
294 * @remarks The specific error code can be accessed using the GetLastResult() method.
296 virtual Tizen::Base::String GetSerialNumber(void) const = 0;
299 * Checks whether the certificate is currently valid. @n
300 * It is valid if the current date and time are within the validity period given in the certificate. @n
301 * The validity period consists of two date and time values: the initial date and time, and the final date and time until the validity of the certificate. @n
303 * It is defined in ASN.1 as:
308 * Validity ::= SEQUENCE {
309 * notBefore CertificateValidityDate,
310 * notAfter CertificateValidityDate }
312 * CertificateValidityDate ::= CHOICE {
314 * generalTime GeneralizedTime }
319 * @return The validity period of the certificate
320 * @exception E_SUCCESS The method is successful.
321 * @exception E_SYSTEM A system error has occurred. @n
322 * The certificate link list operation has failed.
323 * @remarks The specific error code can be accessed using the GetLastResult() method.
325 virtual ValidityPeriod CheckValidityPeriod(void) = 0;
329 * Gets the notBefore value of Tizen::Base::String type from the validity period of the certificate. @n
330 * This value represents the date and time before which the certificate is not valid.
334 * @return A string representing the date and time value before which the certificate is not valid
335 * @exception E_SUCCESS The method is successful.
336 * @exception E_OUT_OF_MEMORY The memory is insufficient.
337 * @exception E_SYSTEM A system error has occurred. @n
338 * The method has failed to get the certificate validity information.
339 * @remarks The specific error code can be accessed using the GetLastResult() method.
340 * @see Tizen::Security::Cert::X509Certificate::CheckValidityPeriod() for relevant ASN.1 definitions
342 virtual Tizen::Base::String GetNotBefore(void) const = 0;
346 * Gets the notAfter value of Tizen::Base::String type from the validity period of the certificate. @n
347 * This value represents the date and time after which the certificate is not valid.
351 * @return A string representing the date and time value after which the certificate is not valid
352 * @exception E_SUCCESS The method is successful.
353 * @exception E_OUT_OF_MEMORY The memory is insufficient.
354 * @exception E_SYSTEM A system error has occurred. @n
355 * The method has failed to get the certificate validity information.
356 * @remarks The specific error code can be accessed using the GetLastResult() method.
357 * @see Tizen::Security::Cert::X509Certificate::CheckValidityPeriod() for relevant ASN.1 definitions
359 virtual Tizen::Base::String GetNotAfter(void) const = 0;
362 * Gets the name of the issuer of the certificate.
366 * @return The name of the issuer of the certificate
367 * @exception E_SUCCESS The method is successful.
368 * @exception E_OUT_OF_MEMORY The memory is insufficient.
369 * @exception E_SYSTEM A system error has occurred. @n
370 * The method has failed to get the certificate issuer information.
371 * @remarks The specific error code can be accessed using the GetLastResult() method.
373 virtual Tizen::Base::String GetIssuer(void) const = 0;
376 * Gets the subject name of the certificate.
380 * @return The subject name of the certificate
381 * @exception E_SUCCESS The method is successful.
382 * @exception E_OUT_OF_MEMORY The memory is insufficient.
383 * @exception E_SYSTEM A system error has occurred. @n
384 * The method has failed to get the certificate issuer information.
385 * @remarks The specific error code can be accessed using the GetLastResult() method.
387 virtual Tizen::Base::String GetSubject(void) const = 0;
390 * Gets the signature of the certificate.
394 * @return A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
395 * else @c null if an error occurs
396 * @exception E_SUCCESS The method is successful.
397 * @exception E_OUT_OF_MEMORY The memory is insufficient.
398 * @exception E_SYSTEM A system error has occurred. @n
399 * The certificate link list operation or
400 * the Tizen::Base::ByteBuffer operation has failed.
401 * @remarks The specific error code can be accessed using the GetLastResult() method.
403 virtual Tizen::Base::ByteBuffer* GetSignatureN(void) const = 0;
407 // This method is for internal use only. Using this method can cause behavioral, security-related,
408 // and consistency-related issues in the application.
410 // This method is reserved and may change its name at any time without prior notice.
414 virtual void ICertificate_Reserved1(void) {}
417 // This method is for internal use only. Using this method can cause behavioral, security-related,
418 // and consistency-related issues in the application.
420 // This method is reserved and may change its name at any time without prior notice.
424 virtual void ICertificate_Reserved2(void) {}
427 // This method is for internal use only. Using this method can cause behavioral, security-related,
428 // and consistency-related issues in the application.
430 // This method is reserved and may change its name at any time without prior notice.
434 virtual void ICertificate_Reserved3(void) {}
438 } } } //Tizen::Security::Cert
440 #endif //_FSEC_CERT_ICERTIFICATE_H_