SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
RSA encrypt/decrypt functions

Detailed Description

Macros

#define _SHARKSSLRSAKEY_FREE   1
 

Typedefs

typedef U8 * SharkSslRSAKey
 SharkSslRSAKey is an alias for the SharkSslCert type and is a private/public key converted by sharkssl_PEM_to_RSAKey or the command line tool SharkSslParseKey. More...
 

Functions

SHARKSSL_API SharkSslRSAKey sharkssl_PEM_to_RSAKey (const char *PEMKey, const char *passphrase)
 Convert an RSA private or public key in PEM format to the SharkSslRSAKey format. More...
 
SHARKSSL_API SharkSslKey sharkssl_PEM_extractPublicKey (const char *certPEM)
 Extract the public key form a certificate in PEM format. More...
 
SHARKSSL_API void SharkSslRSAKey_free (SharkSslRSAKey key)
 Release a SharkSslRSAKey allocated by functions sharkssl_PEM_to_RSAKey and sharkssl_PEM_extractPublicKey. More...
 
SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_public_encrypt (SharkSslRSAKey pubkey, const U8 *in, int len, U8 *out, int padding)
 Encrypt data using the public key or private key. More...
 
SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_private_decrypt (SharkSslRSAKey privkey, const U8 *in, int len, U8 *out, int padding)
 Decrypt ciphertext using the private key. More...
 
SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_PKCS1V1_5_sign_hash (SharkSslRSAKey privkey, U8 *sig, U16 *siglen, const U8 *hash, U8 hashID)
 Sign a hash using a private RSA key. More...
 
SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_PKCS1V1_5_verify_hash (SharkSslRSAKey pubkey, U8 *sig, U16 siglen, const U8 *hash, U8 hashID)
 Verify a signature hash using a public RSA key. More...
 
SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_private_decrypt_OAEP (SharkSslRSAKey privkey, U8 *in, int len, U8 hashID, U8 *out, const char *label, U16 labelLen)
 Decrypt ciphertext using the private key, padding is OAEP per RFC 8017. More...
 
SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_public_encrypt_OAEP (SharkSslRSAKey pubkey, const U8 *in, int len, U8 hashID, U8 *out, const char *label, U16 labelLen)
 Encrypt cleartext using the public key, padding is OAEP per RFC 8017. More...
 
SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_private_encrypt (SharkSslRSAKey privkey, const U8 *in, int len, U8 *out, int padding)
 Sign a message digest using the private key. More...
 
SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_public_decrypt (SharkSslRSAKey pubkey, const U8 *in, int len, U8 *out, int padding)
 Bring back a message digest using the public key or private key. More...
 

Macro Definition Documentation

◆ _SHARKSSLRSAKEY_FREE

#define _SHARKSSLRSAKEY_FREE   1

Typedef Documentation

◆ SharkSslRSAKey

typedef U8* SharkSslRSAKey

SharkSslRSAKey is an alias for the SharkSslCert type and is a private/public key converted by sharkssl_PEM_to_RSAKey or the command line tool SharkSslParseKey.

Function Documentation

◆ sharkssl_PEM_extractPublicKey()

SharkSslKey sharkssl_PEM_extractPublicKey ( const char *  certPEM)

Extract the public key form a certificate in PEM format.

Note: the converted value must be released by calling SharkSslKey_free, when no longer needed.

example:

{
SharkSslKey SslKey;
...
if (SslKey)
{
...
void SharkSslKey_free(SslKey);
}
}
#define SharkSslKey_free
Definition: SharkSSL.h:2626
SHARKSSL_API SharkSslKey sharkssl_PEM_extractPublicKey(const char *certPEM)
Extract the public key form a certificate in PEM format.
U8 * SharkSslKey
The SharkSslKey type.
Definition: SharkSSL.h:318
Returns
the certificate's public key in SharkSslKey (RSA or ECC) format or NULL if the conversion fails.
Parameters
certPEMconst char *; required NUL-terminated PEM certificate, or supported PEM public-key text; borrowed for the call.

◆ sharkssl_PEM_to_RSAKey()

SharkSslRSAKey sharkssl_PEM_to_RSAKey ( const char *  PEMKey,
const char *  passphrase 
)

Convert an RSA private or public key in PEM format to the SharkSslRSAKey format.

Note: the converted value must be released by calling SharkSslRSAKey_free, when no longer needed.

example:

{
SharkSslRSAKey RSAKey;
...
RSAKey = sharksslPEM_to_RSAKey(key, pass);
if (RSAKey)
{
...
void SharkSslRSAKey_free(RSAKey);
}
}
SHARKSSL_API void SharkSslRSAKey_free(SharkSslRSAKey key)
Release a SharkSslRSAKey allocated by functions sharkssl_PEM_to_RSAKey and sharkssl_PEM_extractPublic...
U8 * SharkSslRSAKey
SharkSslRSAKey is an alias for the SharkSslCert type and is a private/public key converted by sharkss...
Definition: SharkSSL.h:2100
Returns
the private/public key in SharkSslRSAKey format or NULL if the conversion fails.
Parameters
PEMKeyconst char *; required NUL-terminated PEM public/private key text of the matching algorithm, borrowed for the call.
passphraseconst char *; optional NUL-terminated password for an encrypted private key, or NULL.

◆ sharkssl_RSA_PKCS1V1_5_sign_hash()

SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_PKCS1V1_5_sign_hash ( SharkSslRSAKey  privkey,
U8 *  sig,
U16 *  siglen,
const U8 *  hash,
U8  hashID 
)

Sign a hash using a private RSA key.

Padding follows PKCS#1 V1.5 per RFC 8017 section 8.2.1.

Parameters
privkeyis the private key in SharkSslRSAKey format.
sigPointer to the buffer where the signature will be stored. The buffer size must be at least SharkSslRSAKey_size.
siglenPointer to store the length of the generated signature (output parameter).
hashPointer to the hash to sign.
hashIDIdentifier for the digest function used. Valid values:
  • SHARKSSL_HASHID_SHA256
  • SHARKSSL_HASHID_SHA384
  • SHARKSSL_HASHID_SHA512
Returns
0 upon successful completion, or an error value to be checked against sharkssl_RSA_RetVal.

◆ sharkssl_RSA_PKCS1V1_5_verify_hash()

SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_PKCS1V1_5_verify_hash ( SharkSslRSAKey  pubkey,
U8 *  sig,
U16  siglen,
const U8 *  hash,
U8  hashID 
)

Verify a signature hash using a public RSA key.

Padding follows PKCS#1 V1.5 per RFC 8017 section 8.2.2.

Parameters
pubkeyThe public key in SharkSslRSAKey format. A corresponding private key may also be used.
sigPointer to the signature to verify.
siglenThe length of the signature in bytes (input parameter).
hashPointer to the hash to verify against the signature.
hashIDIdentifier for the digest function used. Valid values:
  • SHARKSSL_HASHID_SHA256
  • SHARKSSL_HASHID_SHA384
  • SHARKSSL_HASHID_SHA512
Returns
0 upon successful verification, or an error value to be checked against sharkssl_RSA_RetVal.

◆ sharkssl_RSA_private_decrypt()

SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_private_decrypt ( SharkSslRSAKey  privkey,
const U8 *  in,
int  len,
U8 *  out,
int  padding 
)

Decrypt ciphertext using the private key.

Parameters
privkeyis the private key in SharkSslRSAKey format.
inthe ciphertext
lenis the length/size of parameter 'in'. This length must be exactly SharkSslRSAKey_size (key).
outthe decrypted ciphertext is copied to this buffer. The size of this buffer must be no less than SharkSslRSAKey_size (key)
paddingis one of SHARKSSL_RSA_PKCS1_PADDING or SHARKSSL_RSA_NO_PADDING
Returns
the size of the decrypted ciphertext, or -1 if any error occurs

◆ sharkssl_RSA_private_decrypt_OAEP()

SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_private_decrypt_OAEP ( SharkSslRSAKey  privkey,
U8 *  in,
int  len,
U8  hashID,
U8 *  out,
const char *  label,
U16  labelLen 
)

Decrypt ciphertext using the private key, padding is OAEP per RFC 8017.

Parameters
privkeyis the private key in SharkSslRSAKey format.
inthe ciphertext (must be in RAM since ITS CONTENT WILL BE MODIFIED)
lenis the length/size of parameter 'in'. This length must be exactly SharkSslRSAKey_size(privkey).
hashIDan identifier for the digest function used Allowed values are: SHARKSSL_HASHID_SHA1
outthe decrypted ciphertext is copied to this buffer. The size of this buffer must be no less than the expected decrypted text
labelis an optional label per RFC 8017 sec. 7.1.1. Use null string when empty.
labelLenis the length of the label. Specify 0 when label is empty
Returns
the size of the decrypted ciphertext, or <0 if any error occurs

◆ sharkssl_RSA_private_encrypt()

SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_private_encrypt ( SharkSslRSAKey  privkey,
const U8 *  in,
int  len,
U8 *  out,
int  padding 
)

Sign a message digest using the private key.

See RFC 8017 sec. 7.1.2

Parameters
privkeyis the private key in SharkSslRSAKey format.
incommonly, an algorithm identifier followed by a message digest
lenis the length/size of parameter 'in'. This length must be exactly SharkSslRSAKey_size (key) when selecting SHARKSSL_RSA_NO_PADDING or a value between 1 and (SharkSslRSAKey_size (key) - 11) when selecting SHARKSSL_RSA_PKCS1_PADDING.
outthe signature is copied to this buffer. The size of this buffer must be no less than SharkSslRSAKey_size (key)
paddingis one of SHARKSSL_RSA_PKCS1_PADDING or SHARKSSL_RSA_NO_PADDING
Returns
the size of the signature, or -1 if any error occurs

◆ sharkssl_RSA_public_decrypt()

SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_public_decrypt ( SharkSslRSAKey  pubkey,
const U8 *  in,
int  len,
U8 *  out,
int  padding 
)

Bring back a message digest using the public key or private key.

The private key includes the public key an can for this reason be used for this operation.

Parameters
pubkeyis the public key in SharkSslRSAKey format.
inthe RSA signature. Please notice that the RSA signature is modified by this function and must for this reason be in RAM.
lenis the length/size of parameter 'in'. This length must be exactly SharkSslRSAKey_size (key).
outthe message digest is copied to this buffer. The size of this buffer must be no less than SharkSslRSAKey_size (key)
paddingis one of SHARKSSL_RSA_PKCS1_PADDING or SHARKSSL_RSA_NO_PADDING
Returns
the size of the obtained message digest, or -1 if any error occurs

◆ sharkssl_RSA_public_encrypt()

SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_public_encrypt ( SharkSslRSAKey  pubkey,
const U8 *  in,
int  len,
U8 *  out,
int  padding 
)

Encrypt data using the public key or private key.

The private key includes the public key an can for this reason be used for encrypting the data.

Parameters
pubkeyis the public key in SharkSslRSAKey format.
inthe plaintext
lenis the length/size of parameter 'in'. This length must be exactly SharkSslRSAKey_size (key) when selecting SHARKSSL_RSA_NO_PADDING or a value between 1 and (SharkSslRSAKey_size (key) - 11) when selecting SHARKSSL_RSA_PKCS1_PADDING.
outthe encrypted ciphertext is copied to this buffer. The size of this buffer must be no less than SharkSslRSAKey_size (key)
paddingis one of SHARKSSL_RSA_PKCS1_PADDING or SHARKSSL_RSA_NO_PADDING
Returns
the size of the encrypted ciphertext, or -1 if any error occurs

◆ sharkssl_RSA_public_encrypt_OAEP()

SHARKSSL_API sharkssl_RSA_RetVal sharkssl_RSA_public_encrypt_OAEP ( SharkSslRSAKey  pubkey,
const U8 *  in,
int  len,
U8  hashID,
U8 *  out,
const char *  label,
U16  labelLen 
)

Encrypt cleartext using the public key, padding is OAEP per RFC 8017.

Parameters
pubkeyis the public key in SharkSslRSAKey format. The matching private key can be provided, too.
inthe cleartext (not required to be in RAM)
lenis the length/size of parameter 'in'. This length must be not greater than SharkSslRSAKey_size(pubkey) - (2 * labelLen) - 2.
hashIDan identifier for the digest function used Allowed values are: SHARKSSL_HASHID_SHA1
outthe encrypted cleartext is copied to this buffer. The size of this buffer must be SharkSslRSAKey_size(pubkey)
labelis an optional label per RFC 8017 sec. 7.1.1. Use null string when empty.
labelLenis the length of the label. Specify 0 when label is empty
Returns
the size of the encrypted ciphertext, or <0 if any error occurs

◆ SharkSslRSAKey_free()

void SharkSslRSAKey_free ( SharkSslRSAKey  key)

Release a SharkSslRSAKey allocated by functions sharkssl_PEM_to_RSAKey and sharkssl_PEM_extractPublicKey.

Parameters
keySharkSslRSAKey; dynamically allocated key returned by a conversion/creation API, or NULL. Do not pass static generated key arrays; release every borrower first.