RSA
[API]

Data Structures

struct  C4eRsaKeyPrv
 RSA private key. More...

Modules

 RSA Temp. Space Qualifiers
 

Temp. space qualifiers for RSA based cryptography.


Defines

#define C4E_RSA_TMP_NUM(tmpid, keylen)
 Calculate the number of temp. space elements of type C4eAlgo32Digit for RSA algorithms.
#define C4E_RSA_PKCS1V1_EBOH
 Minimum encoding overhead in a PKCS #1 v1.5 respective PEM (RFC 1423) encryption block, in bytes.
#define C4E_RSA_OAEP_EMOH(hlen)
 Minimum encryption overhead in a PKCS #1 v2.1 EME-OAEP encoded message, in bytes.
#define C4E_RSA_PSS_EMLEN(hlen, slen)
 Length of a PKCS #1 v2.1 EMSA-PSS (signature) encoded message, in bytes.

Functions

C4eSysStatus c4e_rsa_encrypt_pkcs1v1 (C4eDlcDomain *C4E_RESTRICT dom, C4E_CONST C4eElement *C4E_RESTRICT e, C4E_CONST C4eArchUint8 *C4E_RESTRICT plain, C4eArchSize len, C4eAlgo32Digit tmp[C4E_RESTRICT], C4eArchUint8 *C4E_RESTRICT cipher)
 RSA encryption of a plaintext octet string into a ciphertext octet string, compatible with PKCS #1 v1.5 (block type 2) and Privacy Enhancement for Internet Electronic Mail (PEM).
C4eSysStatus c4e_rsa_decrypt_pkcs1v1 (C4E_CONST C4eDlcDomain *C4E_RESTRICT dom, C4eRsaKeyPrv *key, C4E_CONST C4eArchUint8 *C4E_RESTRICT cipher, C4eAlgo32Digit tmp[C4E_RESTRICT], C4eArchUint8 *C4E_RESTRICT plain, C4eArchSize *C4E_RESTRICT plen)
 RSA decryption of a ciphertext octet string into a plain- text octet string, compatible with PKCS #1 v1.5 (block type 2) and Privacy Enhancement for Internet Electronic Mail (PEM).
C4eSysStatus c4e_rsa_sign_pkcs1v1 (C4E_CONST C4eDlcDomain *C4E_RESTRICT dom, C4eRsaKeyPrv *key, C4eHashId hid, C4E_CONST C4eArchUint8 *C4E_RESTRICT digest, C4eAlgo32Digit tmp[C4E_RESTRICT], C4eArchUint8 *C4E_RESTRICT signature)
 RSA signature of a digest, compatible with PKCS #1 v1.5 (block type 1).
C4eSysStatus c4e_rsa_verify_pkcs1v1 (C4eDlcDomain *C4E_RESTRICT dom, C4E_CONST C4eElement *C4E_RESTRICT e, C4eHashId hid, C4E_CONST C4eArchUint8 *C4E_RESTRICT digest, C4eAlgo32Digit tmp[C4E_RESTRICT], C4eArchUint8 *C4E_RESTRICT signature, C4eArchSize len)
 PKCS #1 v1.5 (block type 1) RSA signature verification.
C4eSysStatus c4e_rsa_encrypt_pkcs1v2 (C4eDlcDomain *C4E_RESTRICT dom, C4E_CONST C4eElement *C4E_RESTRICT e, C4eHashId hid, C4E_CONST C4eArchUint8 *C4E_RESTRICT plain, C4eArchSize len, C4eAlgo32Digit tmp[C4E_RESTRICT], C4eArchUint8 *C4E_RESTRICT cipher)
 RSA encryption of a plaintext octet string into a ciphertext octet string, compatible with PKCS #1 v2.1 (RSAES-OAEP), IEEE Std 1363 (IFES/EME1) and ISO 18033-2 (RSAES/REM1).
C4eSysStatus c4e_rsa_decrypt_pkcs1v2 (C4E_CONST C4eDlcDomain *C4E_RESTRICT dom, C4eRsaKeyPrv *key, C4eHashId hid, C4E_CONST C4eArchUint8 *C4E_RESTRICT cipher, C4eAlgo32Digit tmp[C4E_RESTRICT], C4eArchUint8 *C4E_RESTRICT plain, C4eArchSize *C4E_RESTRICT plen)
 RSA decryption of a ciphertext octet string into a plain- text octet string, compatible with PKCS #1 v2.1 (RSAES- OAEP), IEEE Std 1363 (IFES/EME1) and ISO 18033-2 (RSAES/REM1).
C4eSysStatus c4e_rsa_sign_pkcs1v2 (C4E_CONST C4eDlcDomain *C4E_RESTRICT dom, C4eRsaKeyPrv *key, C4eArchSize slen, C4eHashId hid, C4E_CONST C4eArchUint8 *C4E_RESTRICT digest, C4eAlgo32Digit tmp[C4E_RESTRICT], C4eArchUint8 *C4E_RESTRICT signature)
 RSA signature of a digest, compatible with PKCS #1 v2.1 signature scheme RSASSA-PSS.
C4eSysStatus c4e_rsa_verify_pkcs1v2 (C4eDlcDomain *C4E_RESTRICT dom, C4E_CONST C4eElement *C4E_RESTRICT e, C4eHashId hid, C4eArchUint8 *C4E_RESTRICT digest, C4eArchUint8 *C4E_RESTRICT signature, C4eArchSize len, C4eAlgo32Digit tmp[C4E_RESTRICT])
 PKCS #1 v2.1 RSA signature verification, according to scheme RSASSA-PSS.
C4eSysStatus c4e_rsa_keychk_prv (C4E_CONST C4eDlcDomain *C4E_RESTRICT dom, C4E_CONST C4eRsaKeyPrv *C4E_RESTRICT key, C4eAlgo32Digit tmp[C4E_RESTRICT])
 Private RSA key validity test.
C4eSysStatus c4e_rsa_keychk_pub (C4E_CONST C4eDlcDomain *C4E_RESTRICT dom, C4E_CONST C4eElement *C4E_RESTRICT e, C4eAlgo32Digit tmp[C4E_RESTRICT])
 Public RSA key validity test.

Define Documentation

#define C4E_RSA_TMP_NUM ( tmpid,
keylen   ) 

Calculate the number of temp. space elements of type C4eAlgo32Digit for RSA algorithms.

Calculates the number of C4eAlgo32Digit elements from the RSA field size (in bytes).

For dynamic memory allocation the recommended usage is: 

 C4E_RSA_TMP_NUM(C4E_RSA_TMPID_PKCS1_WORSTCASE, dom->m.len)

with C4E_RSA_TMPID_PKCS1_WORSTCASE as an example. For static memory reservation it might be used as: 

 C4E_RSA_TMP_NUM(C4E_RSA_TMPID_PKCS1_WORSTCASE,
                                    C4E_DLC_GF_BYTES_MAX)

in case C4E_DLC_GF_BYTES_MAX is defined.

Attention:
Do not forget to multiply the return value with C4E_ALGO32_DIGIT_SIZE, when dynamically allocating memory.
Note:
For best performance keylen should be a constant. In this case the compiler calculates the return value.
Parameters:
[in] tmpid Temp. space qualifier associated with the function, for which finally memory space shall be allocated. Pass in here one of the defines from RSA Temp. Space Qualifiers.
[in] keylen Key length (field size, in bytes) for which the number of C4eAlgo32Digit array elements has to be calculated.
Returns:
Number of elements of type C4eAlgo32Digit to be reserved (allocated) as temporary memory space.

Definition at line 254 of file c4e_rsa.h.

#define C4E_RSA_PKCS1V1_EBOH

Minimum encoding overhead in a PKCS #1 v1.5 respective PEM (RFC 1423) encryption block, in bytes.

The minimal overhead in encryption block EB is based on the following structure: 

 00 || BT || PS || 00, with sizeof(PS) >= 8

. In the special case that the encryption data length is zero, this value defines the minimum size of RSA modulus (as indicated in member m.len of C4eDlcDomain).

Definition at line 273 of file c4e_rsa.h.

#define C4E_RSA_OAEP_EMOH ( hlen   ) 

Minimum encryption overhead in a PKCS #1 v2.1 EME-OAEP encoded message, in bytes.

The minimal overhead in encoded message EM is based on the following OAEP structure: 

 0x00 || seed || lhash || 0x01

. In the special case that the encryption data length is zero, this value defines the minimum size of RSA modulus (as indicated in member m.len of C4eDlcDomain).

Parameters:
[in] hlen Digest length (in bytes) of used hash algorithm.
Returns:
Minimum length as described above.

Definition at line 293 of file c4e_rsa.h.

#define C4E_RSA_PSS_EMLEN ( hlen,
slen   ) 

Length of a PKCS #1 v2.1 EMSA-PSS (signature) encoded message, in bytes.

The length of encoded message EM is based on the following structure: 

 maskedDB || H || 0xBC

, with 

 maskedDB ::= PS || 0x01 || salt

. In the special case that the salt length is zero, the return value defines the minimum size of RSA modulus (as indicated in member m.len of C4eDlcDomain). If you set argument slen to zero, then the expression 

 dom->m.len - C4E_RSA_PSS_EMLEN(hlen, 0)

determines the maximum allowed length for the EMSA-PSS salt.

Note:
The returned value is a theoretical limit (except for maximum salt length calculation described in the note below), which reflects the PKCS #1 v2.1 EMSA-PSS encoding structure. But for example SHA-1 requires at minimum a 200-248 bit modulus (in this implementation, depending on C4E_ARCH_DIGIT_SIZE and the type C4eAlgo32Uint), which may be greater than the returned value - especially if the salt length is small. Because all signature routines check the size of RSA key at function entry, application of this macro at user-side is normally not needed.
Parameters:
[in] hlen Digest length (in bytes) of used hash algorithm.
[in] slen Length of salt (in bytes) to be used. Set this to zero to get the absolutely minimum.
Returns:
Minimum size of RSA modulus (in bytes) as described above.
See also:
c4e_rsa_sign_pkcs1v2()

Definition at line 331 of file c4e_rsa.h.

Function Documentation

C4eSysStatus c4e_rsa_encrypt_pkcs1v1 ( C4eDlcDomain *C4E_RESTRICT  dom,
C4E_CONST C4eElement *C4E_RESTRICT  e,
C4E_CONST C4eArchUint8 *C4E_RESTRICT  plain,
C4eArchSize  len,
C4eAlgo32Digit  tmp[C4E_RESTRICT],
C4eArchUint8 *C4E_RESTRICT  cipher 
)

RSA encryption of a plaintext octet string into a ciphertext octet string, compatible with PKCS #1 v1.5 (block type 2) and Privacy Enhancement for Internet Electronic Mail (PEM).

Note:
This encryption scheme is identified by OID: rsaEncryption ::= {pkcs-1 1}.
Deprecated:
Encryption based on PKCS #1 v1.5 is not recommended anymore (for further information see PKCS #1 v2.1).
Attention:
The domain parameter dom->m.val is temporary modified - so it must be writable. After function return it holds the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the public RSA key e must be assured by the caller, for example by using function c4e_rsa_keychk_pub().
The Random Number Generator (RNG) must be initialized at user side, then installed via function c4e_rng_install().
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() to calculate the number of elements. The following temp. space qualifiers are intended for that purpose:
Bibliography:
RSA Encryption Standard. PKCS #1 v1.5, RSA Laboratories, November 1993.
Bibliography:
Kaliski, B.: Public-Key Cryptography Standards (PKCS) #1: RSA Encryption Version 1.5. RFC 2313, IETF, March 1998
Bibliography:
Kent, S.: Privacy Enhancement for Internet Electronic Mail: Part III: Algorithms, Modes, and Identifiers. RFC 1423, IETF, February 1993.
Bibliography:
Rivest, R.L., A. Shamir und L.M. Adleman: A Method for Obtaining Digital Signatures and Public-Key Cryptosystems. Communications of the ACM, 21(2):120-126, February 1978.
Parameters:
[in] dom Pointer to domain parameters.
[in] e Pointer to RSA public key.
[in] plain Plaintext octet string, which shall be encrypted.
[in] len Length of plain text octet string in bytes.
tmp Array of temporary space elements (see preconditions for details on size).
[out] cipher Ciphertext octet string result, with implicit length of dom->m.len bytes.
Returns:
Status
Return values:
C4E_STATUS_OK If the operation was successful.
other If the operation has failed.
See also:
c4e_rsa_decrypt_pkcs1v1(), c4e_rsa_keychk_pub(), c4e_dlc_domchk(), C4E_RSA_TMP_NUM()
C4eSysStatus c4e_rsa_decrypt_pkcs1v1 ( C4E_CONST C4eDlcDomain *C4E_RESTRICT  dom,
C4eRsaKeyPrv *  key,
C4E_CONST C4eArchUint8 *C4E_RESTRICT  cipher,
C4eAlgo32Digit  tmp[C4E_RESTRICT],
C4eArchUint8 *C4E_RESTRICT  plain,
C4eArchSize *C4E_RESTRICT  plen 
)

RSA decryption of a ciphertext octet string into a plain- text octet string, compatible with PKCS #1 v1.5 (block type 2) and Privacy Enhancement for Internet Electronic Mail (PEM).

The RSA algorithm is based on modular exponentiation of big integer numbers. In case of decryption the expression $ y=x^d \bmod m $ transforms the cipher variable $ x $ into a plaintext number $ y $. This implementation uses the Chinese Remainder Theorem (CRT) in the following form:

\begin{align*} y_p &= (x \bmod p)^{d_p} \bmod p \\ y_q &= (x \bmod q)^{d_q} \bmod q \\ y &= y_q + q q_{\textup{inv}} (y_p - y_q) \end{align*}

Note:
This decryption scheme is identified by OID: rsaEncryption ::= {pkcs-1 1}.
Deprecated:
Encryption based on PKCS #1 v1.5 is not recommended anymore (for further information see PKCS #1 v2.1).
Attention:
The key members key->p and key->q are temporary modified - so they must be writable. After function return these members have the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the private RSA key key must be assured by the caller, either implicit or by using function c4e_rsa_keychk_prv().
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() to calculate the number of elements. The following temp. space qualifiers are intended for that purpose:
Bibliography:
RSA Encryption Standard. PKCS #1 v1.5, RSA Laboratories, November 1993.
Bibliography:
Kaliski, B.: Public-Key Cryptography Standards (PKCS) #1: RSA Encryption Version 1.5. RFC 2313, IETF, March 1998
Bibliography:
Kent, S.: Privacy Enhancement for Internet Electronic Mail: Part III: Algorithms, Modes, and Identifiers. RFC 1423, IETF, February 1993.
Bibliography:
Rivest, R.L., A. Shamir und L.M. Adleman: A Method for Obtaining Digital Signatures and Public-Key Cryptosystems. Communications of the ACM, 21(2):120-126, February 1978.
Parameters:
[in] dom Pointer to domain parameters.
[in] key Pointer to RSA private key.
[in] cipher Ciphertext octet string, which shall be decrypted.
tmp Array of temporary space elements (see preconditions for details on size).
[out] plain Plaintext octet string result of length *plen.
[in,out] plen Pointer to length variable which must be set to the length of cipher octet string (input) and returns the real length of plain (output) in bytes.
Returns:
Status.
Return values:
C4E_STATUS_OK If the operation was successful.
other If the operation has failed.
See also:
c4e_rsa_encrypt_pkcs1v1(), c4e_rsa_keychk_prv(), c4e_dlc_domchk(), C4E_RSA_TMP_NUM(), C4eRsaKeyPriv
C4eSysStatus c4e_rsa_sign_pkcs1v1 ( C4E_CONST C4eDlcDomain *C4E_RESTRICT  dom,
C4eRsaKeyPrv *  key,
C4eHashId  hid,
C4E_CONST C4eArchUint8 *C4E_RESTRICT  digest,
C4eAlgo32Digit  tmp[C4E_RESTRICT],
C4eArchUint8 *C4E_RESTRICT  signature 
)

RSA signature of a digest, compatible with PKCS #1 v1.5 (block type 1).

The RSA algorithm is based on modular exponentiation of big integer numbers. In case of a signature the expression $ y=x^d \bmod m $ transforms a PKCS #1 v1.5 encoded digest $ x $ into a signature $ y $. This implementation uses the Chinese Remainder Theorem (CRT) in the following form:

\begin{align*} y_p &= (x \bmod p)^{d_p} \bmod p \\ y_q &= (x \bmod q)^{d_q} \bmod q \\ y &= y_q + q q_{\textup{inv}} (y_p - y_q) \end{align*}

Note:
This signature scheme is identified by the OID(s):
  • sha1WithRsaEncryption ::= {pkcs-1 5};
  • sha224WithRsaEncryption ::= {pkcs-1 14};
  • sha256WithRsaEncryption ::= {pkcs-1 11}.
The minimum RSA modulus required by the PKCS #1 v1.5 signature scheme depends on the used hash algorithm:
  • 46 bytes (368 bit) for SHA-1;
  • 58 bytes (464 bit) for SHA-224;
  • 62 bytes (496 bit) for SHA-256.
Deprecated:
Signatures based on PKCS #1 v1.5 are not recommended anymore (for further information see PKCS #1 v2.1).
Attention:
The key members key->p and key->q are temporary modified - so they must be writable. After function return these members have the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the private RSA key key must be assured by the caller, either implicit or by using function c4e_rsa_keychk_prv().
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() to calculate the number of elements. The following temp. space qualifiers are intended for that purpose:
Bibliography:
RSA Encryption Standard. PKCS #1 v1.5, RSA Laboratories, November 1993.
Bibliography:
Kaliski, B.: Public-Key Cryptography Standards (PKCS) #1: RSA Encryption Version 1.5. RFC 2313, IETF, March 1998
Bibliography:
Rivest, R.L., A. Shamir und L.M. Adleman: A Method for Obtaining Digital Signatures and Public-Key Cryptosystems. Communications of the ACM, 21(2):120-126, February 1978.
Parameters:
[in] dom Pointer to domain parameters.
[in] key Pointer to RSA private key.
[in] hid Hash algorithm identifier of type C4eHashId.
[in] digest Digest calculated by the caller using one of the hash functions enumerated in C4eHashId, here identified by hid. The length of digest is implicit:

tmp Array of temporary space elements (see preconditions for details on size).
[out] signature Signature (octet string), with implicit length of dom->m.len bytes.
Returns:
Status
Return values:
C4E_STATUS_OK If the operation was successful.
other If the operation has failed.
See also:
c4e_rsa_verify_pkcs1v1(), c4e_rsa_keychk_prv(), c4e_dlc_domchk(), C4E_RSA_TMP_NUM(), C4eRsaKeyPriv
C4eSysStatus c4e_rsa_verify_pkcs1v1 ( C4eDlcDomain *C4E_RESTRICT  dom,
C4E_CONST C4eElement *C4E_RESTRICT  e,
C4eHashId  hid,
C4E_CONST C4eArchUint8 *C4E_RESTRICT  digest,
C4eAlgo32Digit  tmp[C4E_RESTRICT],
C4eArchUint8 *C4E_RESTRICT  signature,
C4eArchSize  len 
)

PKCS #1 v1.5 (block type 1) RSA signature verification.

The RSA algorithm is based on modular exponentiation of big integer numbers. In case of a signature verification the expression $ y=x^e \bmod m $ transforms a PKCS #1 v1.5 signature $ x $ back to the original digest $ y $, which then is compared against parameter digest.

Note:
This verification scheme is identified by the OID(s):
  • sha1WithRsaEncryption ::= {pkcs-1 5};
  • sha224WithRsaEncryption ::= {pkcs-1 14};
  • sha256WithRsaEncryption ::= {pkcs-1 11}, with
Deprecated:
Signatures based on PKCS #1 v1.5 are not recommended anymore (for further information see PKCS #1 v2.1).
Attention:
The domain parameter dom->m.val is temporary modified - so it must be writable. After function return it holds the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the public RSA key e must be assured by the caller, for example by using function c4e_rsa_keychk_pub().
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() to calculate the number of elements. The following temp. space qualifiers are intended for that purpose:
Bibliography:
RSA Encryption Standard. PKCS #1 v1.5, RSA Laboratories, November 1993.
Bibliography:
Kaliski, B.: Public-Key Cryptography Standards (PKCS) #1: RSA Encryption Version 1.5. RFC 2313, IETF, March 1998
Bibliography:
Rivest, R.L., A. Shamir and L.M. Adleman: A Method for Obtaining Digital Signatures and Public-Key Cryptosystems. Communications of the ACM, 21(2):120-126, February 1978.
Parameters:
[in] dom Pointer to domain parameters.
[in] e Pointer to RSA public key.
[in] hid Hash algorithm identifier of type C4eHashId.
[in] digest Digest calculated by the caller, using the hash function associated with hid. The length of digest is implicit:

tmp Array of temporary space elements (see preconditions for details on size).
[in,out] signature Signature to be verified (input). As output it holds the ASN.1 BER (DER) encoded DigestInfo defined in PKCS #1 v1.5 (which only is of interest in special applications).
[in] len Length of signature in bytes.
Returns:
Status
Return values:
C4E_STATUS_OK If the signature is valid.
other If the signature verification has failed.
See also:
c4e_rsa_sign_pkcs1v1(), c4e_rsa_keychk_pub(), c4e_dlc_domchk(), C4E_RSA_TMP_NUM()
C4eSysStatus c4e_rsa_encrypt_pkcs1v2 ( C4eDlcDomain *C4E_RESTRICT  dom,
C4E_CONST C4eElement *C4E_RESTRICT  e,
C4eHashId  hid,
C4E_CONST C4eArchUint8 *C4E_RESTRICT  plain,
C4eArchSize  len,
C4eAlgo32Digit  tmp[C4E_RESTRICT],
C4eArchUint8 *C4E_RESTRICT  cipher 
)

RSA encryption of a plaintext octet string into a ciphertext octet string, compatible with PKCS #1 v2.1 (RSAES-OAEP), IEEE Std 1363 (IFES/EME1) and ISO 18033-2 (RSAES/REM1).

This type of RSA encoding scheme uses Optimal Asymmetric Encryption Padding (OAEP) with Mask Generation Function MGF1 and an empty label.

Note:
This encryption scheme is identified by OID: id-RSAES-OAEP ::= {pkcs-1 7}. Multi-prime RSA, as specified in PKCS #1 v2.1, is not supported.
With OAEP padding (using MGF1) the smallest RSA modulus is of length C4E_RSA_OAEP_EMOH(hlen), with hlen for example C4E_SHA1_DIGEST_LEN or C4E_SHA256_DIGEST_LEN. For SHA-1/224/256 this means: the minimum modulus is 336/464/528 bit.
Attention:
The domain parameter dom->m.val is temporary modified - so it must be writable. After function return it holds the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the public RSA key e must be assured by the caller, for example by using function c4e_rsa_keychk_pub().
The Random Number Generator (RNG) must be initialized at user side, then installed via function c4e_rng_install().
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() to calculate the number of elements. The following temp. space qualifiers are intended for that purpose:
Bibliography:
RSA Cryptography Standard. PKCS #1 v2.1, RSA Laboratories, June 2002.
Bibliography:
Jonsson, J. and B. Kaliski: Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1. RFC 3447, IETF, February 2003
Bibliography:
Standard Specifications For Public-Key Cryptography. Std 1363-2000, IEEE, 2000.
Bibliography:
Information technology - Security techniques - Encryption algorithms - Part 2: Asymmetric ciphers. ISO 18033-2, 2006.
Bibliography:
M. Bellare and P. Rogaway: Optimal Asymmetric Encryption - How to Encrypt with RSA. In: Advances in Cryptology - EUROCRYPT 94, LNCS 950: 92-111, 1995, Springer-Verlag.
Bibliography:
Rivest, R.L., A. Shamir und L.M. Adleman: A Method for Obtaining Digital Signatures and Public-Key Cryptosystems. Communications of the ACM, 21(2):120-126, February 1978.
Parameters:
[in] dom Pointer to domain parameters.
[in] e Pointer to RSA public key.
[in] hid Hash algorithm identifier.
[in] plain Plaintext octet string, which shall be encrypted.
[in] len Length of plain text octet string in bytes.
tmp Array of temporary space elements (see preconditions for details on size).
[out] cipher Ciphertext octet string result, with implicit length of dom->m.len bytes. But notice that 4 extra bytes are used temporary after end of cipher.
Returns:
Status
Return values:
C4E_STATUS_OK If the operation was successful.
other If the operation has failed.
See also:
c4e_rsa_decrypt_pkcs1v2(), c4e_rsa_keychk_pub(), c4e_dlc_domchk(), C4E_RSA_TMP_NUM()
C4eSysStatus c4e_rsa_decrypt_pkcs1v2 ( C4E_CONST C4eDlcDomain *C4E_RESTRICT  dom,
C4eRsaKeyPrv *  key,
C4eHashId  hid,
C4E_CONST C4eArchUint8 *C4E_RESTRICT  cipher,
C4eAlgo32Digit  tmp[C4E_RESTRICT],
C4eArchUint8 *C4E_RESTRICT  plain,
C4eArchSize *C4E_RESTRICT  plen 
)

RSA decryption of a ciphertext octet string into a plain- text octet string, compatible with PKCS #1 v2.1 (RSAES- OAEP), IEEE Std 1363 (IFES/EME1) and ISO 18033-2 (RSAES/REM1).

This type of RSA encoding scheme uses Optimal Asymmetric Encryption Padding (OAEP) with Mask Generation Function MGF1 and an empty label.

Note:
This encryption scheme is identified by OID: id-RSAES-OAEP ::= {pkcs-1 7}. Multi-prime RSA, as specified in PKCS #1 v2.1, is not supported.
Attention:
The key members key->p and key->q are temporary modified - so they must be writable. After function return these members have the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the private RSA key key must be assured by the caller, either implicit or by using function c4e_rsa_keychk_prv().
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() to calculate the number of elements. The following temp. space qualifiers are intended for that purpose:
Bibliography:
RSA Cryptography Standard. PKCS #1 v2.1, RSA Laboratories, June 2002.
Bibliography:
Jonsson, J. and B. Kaliski: Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1. RFC 3447, IETF, February 2003
Bibliography:
Standard Specifications For Public-Key Cryptography. Std 1363-2000, IEEE, 2000.
Bibliography:
Information technology - Security techniques - Encryption algorithms - Part 2: Asymmetric ciphers. ISO 18033-2, 2006.
Bibliography:
M. Bellare and P. Rogaway: Optimal Asymmetric Encryption - How to Encrypt with RSA. In: Advances in Cryptology - EUROCRYPT 94, LNCS 950: 92-111, 1995, Springer-Verlag.
Bibliography:
Rivest, R.L., A. Shamir und L.M. Adleman: A Method for Obtaining Digital Signatures and Public-Key Cryptosystems. Communications of the ACM, 21(2):120-126, February 1978.
Parameters:
[in] dom Pointer to domain parameters.
[in] key Pointer to RSA private key.
[in] hid Hash algorithm identifier.
[in] cipher Ciphertext octet string, which shall be decrypted.
tmp Array of temporary space elements (see preconditions for details on size).
[out] plain Plaintext octet string result of length *plen. The maximum length is dom->m.len bytes. But notice that 4 extra bytes are used temporary after end of plain.
[in,out] plen Pointer to length variable which must be set to the length of cipher octet string (input) and returns the real length of plain (output) in bytes.
Returns:
Status
Return values:
C4E_STATUS_OK If the operation was successful.
other If the operation has failed.
See also:
c4e_rsa_encrypt_pkcs1v2(), c4e_rsa_keychk_prv(), c4e_dlc_domchk(), C4E_RSA_TMP_NUM(), C4eRsaKeyPriv
C4eSysStatus c4e_rsa_sign_pkcs1v2 ( C4E_CONST C4eDlcDomain *C4E_RESTRICT  dom,
C4eRsaKeyPrv *  key,
C4eArchSize  slen,
C4eHashId  hid,
C4E_CONST C4eArchUint8 *C4E_RESTRICT  digest,
C4eAlgo32Digit  tmp[C4E_RESTRICT],
C4eArchUint8 *C4E_RESTRICT  signature 
)

RSA signature of a digest, compatible with PKCS #1 v2.1 signature scheme RSASSA-PSS.

The RSA algorithm is based on modular exponentiation of big integer numbers. In case of a signature the expression $ y=x^d \bmod m $ transforms a PKCS #1 v2.1 EMSA-PSS (Probabilistic Signature Scheme) encoded digest $ x $ into a signature $ y $. This implementation uses the Chinese Remainder Theorem (CRT) in the following form:

\begin{align*} y_p &= (x \bmod p)^{d_p} \bmod p \\ y_q &= (x \bmod q)^{d_q} \bmod q \\ y &= y_q + q q_{\textup{inv}} (y_p - y_q) \end{align*}

Note:
This signature algorithm is identified by OID: id-RSASSA-PSS ::= {pkcs-1 10}. Multi-prime RSA, as specified in PKCS #1 v2.1, is not supported.
With EMSA-PSS encoding (using MGF1) the smallest RSA modulus would be of size C4E_RSA_PSS_EMLEN(hlen, slen), with hlen for example C4E_SHA256_DIGEST_LEN. For SHA-1/224/256 this means: the minimum modulus without any salt would be in theory at 176/240/272 bit, but the absolute minimum in this implementation is at 200-312 bit (depending on hash algorithm, C4E_ARCH_DIGIT_SIZE and the real type of C4eAlgo32Digit).
The larger the salt, the more the complexity of this scheme is near the theoretical difficulty of inverting the RSA algorithm (see IEEE Std 1363a-2004 for details).
Attention:
The key members key->p and key->q are temporarily modified - so they must be writable. After function return these members have the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the private RSA key key must be assured by the caller, either implicit or by using function c4e_rsa_keychk_prv().
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() to calculate the number of elements. The following temp. space qualifiers are intended for that purpose:
The Random Number Generator (RNG) must be initialized at user side, then installed via function c4e_rng_install().
Bibliography:
RSA Cryptography Standard. PKCS #1 v2.1, RSA Laboratories, June 2002.
Bibliography:
Jonsson, J. and B. Kaliski: Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1. RFC 3447, IETF, February 2003
Bibliography:
Standard Specifications For Public-Key Cryptography - Amendment 1: Additional Techniques. IEEE Std 1363a-2004.
Bibliography:
M. Bellare and P. Rogaway: The Exact Security of Digital Signatures - How to Sign with RSA and Rabin. In: Advances in Cryptology - EUROCRYPT 96, LNCS 1070: 399-416, 1996, Springer-Verlag.
Bibliography:
Rivest, R.L., A. Shamir and L.M. Adleman: A Method for Obtaining Digital Signatures and Public-Key Cryptosystems. Communications of the ACM, 21(2):120-126, February 1978.
Parameters:
[in] dom Pointer to domain parameters.
[in] key Pointer to RSA private key.
[in] slen Length of salt (random used in EMSA-PSS), which must be less than 

 dom->m.len - C4E_RSA_PSS_EMLEN(hlen, 0)

with hlen the length of digest (see digest).

[in] hid Hash algorithm identifier of type C4eHashId.
[in] digest Digest calculated by the caller using one of the hash functions enumerated in C4eHashId, here identified by hid. The length of digest is implicit:

tmp Array of temporary space elements (see preconditions for details on size).
[out] signature Signature (octet string), with implicit length of dom->m.len bytes. But notice that 6 extra bytes are used temporary after the end of signature. The caller must ensure that this additional memory space is available.
Returns:
Status
Return values:
C4E_STATUS_OK If the operation was successful.
other If the operation has failed.
See also:
c4e_rsa_verify_pkcs1v2(), c4e_rsa_keychk_prv(), c4e_dlc_domchk(), C4E_RSA_TMP_NUM(), C4E_RSA_PSS_EMLEN(), C4eRsaKeyPriv
C4eSysStatus c4e_rsa_verify_pkcs1v2 ( C4eDlcDomain *C4E_RESTRICT  dom,
C4E_CONST C4eElement *C4E_RESTRICT  e,
C4eHashId  hid,
C4eArchUint8 *C4E_RESTRICT  digest,
C4eArchUint8 *C4E_RESTRICT  signature,
C4eArchSize  len,
C4eAlgo32Digit  tmp[C4E_RESTRICT] 
)

PKCS #1 v2.1 RSA signature verification, according to scheme RSASSA-PSS.

The RSA algorithm is based on modular exponentiation of big integer numbers. In case of a signature verification the expression $ y=x^e \bmod m $ transforms a PKCS #1 v2.1 signature $ x $ back to the encoded digest $ y $, which then is decoded and compared against parameter digest.

Note:
This signature verification algorithm is identified by OID: id-RSASSA-PSS ::= {pkcs-1 10}. Multi-prime RSA, as specified in PKCS #1 v2.1, is not supported.
Attention:
The domain parameter dom->m.val is temporary modified - so it must be writable. After function return it holds the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the public RSA key e must be assured by the caller, for example by using function c4e_rsa_keychk_pub().
Even though len indicates the length of signature, there must be enough space for dom->m.len + 6 bytes in signature.
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() to calculate the number of elements. The following temp. space qualifiers are intended for that purpose:
Bibliography:
RSA Cryptography Standard. PKCS #1 v2.1, RSA Laboratories, June 2002.
Bibliography:
Jonsson, J. and B. Kaliski: Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1. RFC 3447, IETF, February 2003
Bibliography:
Standard Specifications For Public-Key Cryptography - Amendment 1: Additional Techniques. IEEE Std 1363a-2004.
Bibliography:
M. Bellare and P. Rogaway: The Exact Security of Digital Signatures - How to Sign with RSA and Rabin. In: Advances in Cryptology - EUROCRYPT 96, LNCS 1070: 399-416, 1996, Springer-Verlag.
Bibliography:
Rivest, R.L., A. Shamir and L.M. Adleman: A Method for Obtaining Digital Signatures and Public-Key Cryptosystems. Communications of the ACM, 21(2):120-126, February 1978.
Parameters:
[in] dom Pointer to domain parameters.
[in] e Pointer to RSA public key.
[in] hid Hash algorithm identifier of type C4eHashId.
[in] digest Digest calculated by the caller, using the hash function associated with hid. The length of digest is implicit:

[in] signature Signature to be verified (destroyed). Notice the preconditions on memory space for this buffer.
[in] len Length of signature in bytes.
tmp Array of temporary space elements (see preconditions for details on size).
Returns:
Status
Return values:
C4E_STATUS_OK If the signature is valid.
other If the signature verification has failed.
See also:
c4e_rsa_sign_pkcs1v1(), c4e_rsa_keychk_pub(), c4e_dlc_domchk(), C4E_RSA_TMP_NUM()
C4eSysStatus c4e_rsa_keychk_prv ( C4E_CONST C4eDlcDomain *C4E_RESTRICT  dom,
C4E_CONST C4eRsaKeyPrv *C4E_RESTRICT  key,
C4eAlgo32Digit  tmp[C4E_RESTRICT] 
)

Private RSA key validity test.

This function performs basic tests on a RSA private key, which:

  • ensure proper working of all RSA functions;
  • checks for simple error conditions;

associated with a RSA private key.

Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The caller must provide temporary memory space in array tmp[], using macro C4E_RSA_TMP_NUM() in conjunction with temp. space qualifier C4E_RSA_TMPID_KEY_CHECK.
All used big numbers in key must be normalized, e.g. by using functions c4e_elem_norm() or c4e_elem_os2e().
Bibliography:
NIST Special Publication 800-56B: Recommendation for Pair-Wise Key Establishment Schemes Using Integer Factorization Cryptography. 2009.
Parameters:
[in] dom Pointer to domain parameters.
[in] key Pointer to RSA private key to be tested.
tmp Array of temporary space elements (see preconditions for details on size).
Returns:
Validity status of key.
Return values:
C4E_STATUS_OK If the key seems to be valid.
other If the key is invalid.
See also:
C4eRsaKeyPriv
Todo:
If CRY4E supports key generation (may be in the future) then implement additional tests according to NIST SP800-56B.
C4eSysStatus c4e_rsa_keychk_pub ( C4E_CONST C4eDlcDomain *C4E_RESTRICT  dom,
C4E_CONST C4eElement *C4E_RESTRICT  e,
C4eAlgo32Digit  tmp[C4E_RESTRICT] 
)

Public RSA key validity test.

This function performs basic tests on a RSA public key e, which ensures proper working of all RSA functions:

  1. e must be greater than 1 and less than modulus dom->m.val;
  2. e must be odd.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
All used big numbers in key must be normalized, e.g. by using functions c4e_elem_norm() or c4e_elem_os2e().
Bibliography:
NIST Special Publication 800-56B: Recommendation for Pair-Wise Key Establishment Schemes Using Integer Factorization Cryptography. 2009.
Parameters:
[in] dom Pointer to domain parameters.
[in] e Pointer to RSA public key, to be tested.
tmp Array of temporary space elements ( (unused at the moment)
Returns:
Validity status of key.
Return values:
C4E_STATUS_OK If the key seems to be valid.
other If the key is invalid.
Todo:
If CRY4E supports key generation (may be in the future) then implement additional tests according to NIST SP800-56B.
Generated by Ralf Hoppe, Ginsterweg 49, 73230 Kirchheim unter Teck, Germany
on Sun Jun 7 14:10:52 2015 for CRY4E using doxygen 1.6.1