--- /dev/null
+/*
+ * 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 */
* @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;
/**
* @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>
* <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.
*
*
*/
--- /dev/null
+/*
+ * 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__ */
projects / platform / core / security / yaca.git / commitdiff