RSA low-level API

Change-Id: Id0d838d97f613d1c9caf1231efdd961c370f2aab

4 files changed, 276 insertions, 6 deletions

diff --git a/api/yaca/yaca_rsa.h b/api/yaca/yaca_rsa.h
new file mode 100755
index 0000000..621cdff
--- /dev/null
+++ b/api/yaca/yaca_rsa.h
@@ -0,0 +1,197 @@
+/*
+ *  Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
+ *
+ *  Contact: Krzysztof Jackiewicz <k.jackiewicz@samsung.com>
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License
+ */
+
+/**
+ * @file   yaca_rsa.h
+ * @brief  Advanced API for low-level RSA operations
+ */
+
+#ifndef YACA_RSA_H
+#define YACA_RSA_H
+
+#include <stddef.h>
+#include <yaca_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @addtogroup CAPI_YACA_RSA_MODULE
+ * @{
+ */
+
+/**
+ * @brief  Encrypts data using a RSA public key (low-level encrypt equivalent).
+ *
+ * @since_tizen 3.0
+ *
+ * @remarks  The @a ciphertext should be freed using yaca_free()
+ *
+ * @remarks  The key used has to be of a #YACA_KEY_TYPE_RSA_PUB type
+ *
+ * @remarks  The maximum length of plaintext depends on the key length and padding method,
+ *           see #yaca_padding_e for details
+ *
+ * @remarks  The @a plaintext can be NULL but then the @a plaintext_len must be 0
+ *
+ * @param[in]  padding         Padding method
+ * @param[in]  pub_key         Public RSA key (see yaca_key.h for key generation functions)
+ * @param[in]  plaintext       Plaintext to be encrypted
+ * @param[in]  plaintext_len   Length of the plaintext
+ * @param[out] ciphertext      Encrypted data, will be allocated by the library
+ * @param[out] ciphertext_len  Length of the encrypted data (may be larger than decrypted)
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Successful
+ * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
+ *                                       invalid padding, pub_key or plaintext_len)
+ * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
+ * @retval #YACA_ERROR_INTERNAL Internal error
+ *
+ * @see #yaca_key_type_e
+ * @see #yaca_padding_e
+ * @see yaca_rsa_private_decrypt()
+ * @see yaca_free()
+ */
+int yaca_rsa_public_encrypt(yaca_padding_e padding,
+                            const yaca_key_h pub_key,
+                            const char *plaintext,
+                            size_t plaintext_len,
+                            char **ciphertext,
+                            size_t *ciphertext_len);
+
+/**
+ * @brief  Decrypts data using a RSA private key (low-level decrypt equivalent).
+ *
+ * @since_tizen 3.0
+ *
+ * @remarks  The @a plaintext should be freed using yaca_free()
+ *
+ * @remarks  The key used has to be of a #YACA_KEY_TYPE_RSA_PRIV type
+ *
+ * @param[in]  padding         Padding method
+ * @param[in]  prv_key         Private RSA key matching the public one used to encrypt the data
+ * @param[in]  ciphertext      Ciphertext to be decrypted
+ * @param[in]  ciphertext_len  Length of ciphertext
+ * @param[out] plaintext       Decrypted data, will be allocated by the library
+ * @param[out] plaintext_len   Length of the decrypted data
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Successful
+ * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
+ *                                       invalid padding or prv_key), padding check failed
+ * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
+ * @retval #YACA_ERROR_INTERNAL Internal error
+ *
+ * @see #yaca_key_type_e
+ * @see #yaca_padding_e
+ * @see yaca_rsa_public_encrypt()
+ * @see yaca_free()
+ */
+int yaca_rsa_private_decrypt(yaca_padding_e padding,
+                             const yaca_key_h prv_key,
+                             const char *ciphertext,
+                             size_t ciphertext_len,
+                             char **plaintext,
+                             size_t *plaintext_len);
+
+/**
+ * @brief  Encrypts data using a RSA private key (low-level sign equivalent).
+ *
+ * @since_tizen 3.0
+ *
+ * @remarks  The @a ciphertext should be freed using yaca_free()
+ *
+ * @remarks  The key used has to be of a #YACA_KEY_TYPE_RSA_PRIV type
+ *
+ * @remarks  The maximum length of plaintext depends on the key length and padding method,
+ *           see #yaca_padding_e for details
+ *
+ * @remarks  The @a plaintext can be NULL but then the @a plaintext_len must be 0
+ *
+ * @param[in]  padding         Padding method
+ * @param[in]  prv_key         Private RSA key (see yaca_key.h for key generation functions)
+ * @param[in]  plaintext       Plaintext to be encrypted
+ * @param[in]  plaintext_len   Length of the plaintext
+ * @param[out] ciphertext      Encrypted data, will be allocated by the library
+ * @param[out] ciphertext_len  Length of the encrypted data (may be larger than decrypted)
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Successful
+ * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
+ *                                       invalid padding, prv_key or message_len)
+ * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
+ * @retval #YACA_ERROR_INTERNAL Internal error
+ *
+ * @see #yaca_key_type_e
+ * @see #yaca_padding_e
+ * @see yaca_rsa_public_decrypt()
+ * @see yaca_free()
+ */
+int yaca_rsa_private_encrypt(yaca_padding_e padding,
+                             const yaca_key_h prv_key,
+                             const char *plaintext,
+                             size_t plaintext_len,
+                             char **ciphertext,
+                             size_t *ciphertext_len);
+
+/**
+ * @brief  Decrypts data using a RSA public key (low-level verify equivalent).
+ *
+ * @since_tizen 3.0
+ *
+ * @remarks  The @a plaintext should be freed using yaca_free()
+ *
+ * @remarks  The key used has to be of a #YACA_KEY_TYPE_RSA_PUB type
+ *
+ * @param[in]  padding         Padding method
+ * @param[in]  pub_key         Public RSA key matching the private one used to encrypt the data
+ * @param[in]  ciphertext      Ciphertext to be decrypted
+ * @param[in]  ciphertext_len  Length of ciphertext
+ * @param[out] plaintext       Decrypted data, will be allocated by the library
+ * @param[out] plaintext_len   Length of the decrypted data
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Successful
+ * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
+ *                                       invalid padding or pub_key), padding check failed
+ * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
+ * @retval #YACA_ERROR_INTERNAL Internal error
+ *
+ * @see #yaca_key_type_e
+ * @see #yaca_padding_e
+ * @see yaca_rsa_private_encrypt()
+ * @see yaca_free()
+ */
+int yaca_rsa_public_decrypt(yaca_padding_e padding,
+                            const yaca_key_h pub_key,
+                            const char *ciphertext,
+                            size_t ciphertext_len,
+                            char **plaintext,
+                            size_t *plaintext_len);
+
+/**
+  * @}
+  */
+
+#ifdef __cplusplus
+} /* extern */
+#endif
+
+#endif /* YACA_RSA_H */
diff --git a/api/yaca/yaca_types.h b/api/yaca/yaca_types.h
index 2032936..bdd7f9e 100755
--- a/api/yaca/yaca_types.h
+++ b/api/yaca/yaca_types.h
@@ -634,14 +634,48 @@ typedef enum {
  * @since_tizen 3.0
  */
 typedef enum {
-	/** The total number of data bytes MUST be a multiple of block size */
+	/**
+	 * No padding at all. This method assumes that the input data already has a proper length for
+	 * a given cryptographic operation (e.g. it has been padded by the client). Suitable for
+	 * symmetric encrypt/decrypt operations as well as low-level RSA operations.
+	 */
 	YACA_PADDING_NONE = 0,
-	/** RSA X9.31 padding */
+
+	/**
+	 * X9.31 padding. Suitable for RSA sign/verify operation. Not supported in low-level
+	 * RSA operations.
+	 */
 	YACA_PADDING_X931,
-	/** RSA signature/verify operations */
+
+	/**
+	 * PKCS #1 v1.5 padding. Suitable for RSA sign/verify and low-level RSA operations.
+	 * For low-level operations the input must be at least 12 bytes shorter than the key length.
+	 */
 	YACA_PADDING_PKCS1,
-	/** RSA signature/verify operations */
+
+	/**
+	 * PKCS #1 PSS padding. Suitable for RSA sign/verify operations. Not supported in low-level
+	 * RSA operations.
+	 */
 	YACA_PADDING_PKCS1_PSS,
+
+	/**
+	 * EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty encoding parameter.
+	 * Suitable for low-level RSA public_encrypt/private_decrypt operations. For low-level
+	 * operations the input must be at least 42 bytes shorter than the key length.
+	 */
+	YACA_PADDING_PKCS1_OAEP,
+
+	/**
+	 * PKCS #1 v1.5 padding with an SSL-specific modification that denotes that the party
+	 * is SSL3 capable. It is used for rollback attack detection in SSLv3. If during decryption it
+	 * turns out that both parties are using #YACA_PADDING_PKCS1_SSL23 (both are communicating
+	 * using SSL2 and both are SSL3 capable) it is treated as a rollback attack and an error is
+	 * returned. Suitable for low-level RSA public_encrypt/private_decrypt operations. For
+	 * low-level operations the input must be at least 12 bytes shorter than the key length.
+	 */
+	YACA_PADDING_PKCS1_SSLV23,
+
 	/** PKCS #7 padding. Suitable for symmetric encrypt/decrypt operation. */
 	YACA_PADDING_PKCS7
 } yaca_padding_e;
diff --git a/doc/yaca_doc.h b/doc/yaca_doc.h
index 4b9751d..d8b3ae3 100755
--- a/doc/yaca_doc.h
+++ b/doc/yaca_doc.h
@@ -18,10 +18,11 @@
 /**
   * @ingroup CAPI_SECURITY_FRAMEWORK
   * @defgroup CAPI_YACA_MODULE YACA
-  * @brief    The YACA (Yet Another Crypto Api) provides a crypto function such as key management, data integrity and data en/decryption.
+  * @brief    The YACA (Yet Another Crypto Api) provides a crypto functions such as key management, data integrity, data en/decryption and low-level RSA operations.
   *           Key management provides APIs for generating secured key,importing a key trying to match it to the key_type specified and exporting a key to arbitrary format.
   *           Data Integrity provides Advanced/Simpled API for the integrity handling - HMAC, CMAC, message digests and digital signature.
   *           Data en/decryption provides Advanced/Simpled APIs for en/decrypting and sealing/opening a data.
+  *           RSA module provides advanced APIs for low-level encryption/decryption operations with asymmetric RSA keys.
   *
   * @section CAPI_YACA_MODULE_OVERVIEW Overview
   * <table>
@@ -42,17 +43,23 @@
   *     <td> @ref CAPI_YACA_SIMPLE_MODULE</td>
   *     <td> Provides simple APIs for cryptographic operations.</td>
   *   </tr>
+  *   <tr>
+  *     <td> @ref CAPI_YACA_RSA_MODULE</td>
+  *     <td> Provides APIs for low-level RSA operations.</td>
+  *   </tr>
   * </table>
   *
   * The yaca provides a crypto function such as key management, integrity handling and data en/decryption.
   * Key management provides APIs for generating secured key, importing a key trying to match it to the key type specified and exporting a key to arbitrary format.
   * Data Integrity provides Advanced/Simpled API for the integrity handling - HMAC, CMAC, message digest and digital signature.
   * Data en/decryption provides Advanced/Simpled APIs for en/decrypting a data and creating a IV.
+  * RSA module provides advanced APIs for low-level encryption/decryption operations with asymmetric RSA keys.
   *
-  * The yaca provides 3 types of API.
+  * The yaca provides 4 types of API.
   * - key management APIs : These APIs provides generating key using random number or password, importing a key trying to match it to the key_type specified and exporting a key to arbitrary format.
   * - data en/decryption APIs : These APIs provides Advanced/Simpled API for the data encryption.
   * - integrity APIs : These APIs provides creating a signature using asymmetric private key, verifying a signature using asymmetric public key, calculating a HMAC/CMAC of given message using symmetric key and calculating message digests of given message without key.
+  * - low-level RSA API : These APIs allow for low-level encryption/decryption operations with asymmetric RSA keys.
   *
   *
   */
diff --git a/doc/yaca_rsa_doc.h b/doc/yaca_rsa_doc.h
new file mode 100755
index 0000000..4012e68
--- /dev/null
+++ b/doc/yaca_rsa_doc.h
@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an AS IS BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#ifndef __TIZEN_CORE_YACA_RSA_DOC_H__
+#define __TIZEN_CORE_YACA_RSA_DOC_H__
+/**
+  * @ingroup CAPI_YACA_MODULE
+  * @defgroup CAPI_YACA_RSA_MODULE YACA Low-level RSA
+  * @brief    Provides APIs for low-level RSA operations.
+  *
+  * @section CAPI_YACA_RSA_MODULE_HEADER Required Header
+  * \#include <yaca/yaca_rsa.h>\n
+  *
+  * @section CAPI_YACA_RSA_MODULE_OVERVIEW Overview
+  * It provides advanced APIs for low-level encryption/decryption operations
+  * with asymmetric RSA keys.
+  *
+  */
+
+#endif /* __TIZEN_CORE_YACA_RSA_DOC_H__ */