RSA encrypt/decrypt functions

Detailed Description

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.

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.
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_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...

Function Documentation

sharkssl_PEM_extractPublicKey()

SHARKSSL_API 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;   
   ...
   SslKey = sharkssl_PEM_extractPublicKey(cert);
   if (SslKey)
   {
      ...
      void SharkSslKey_free(SslKey);
   }
}

Returns

the certificate's public key in SharkSslKey (RSA or ECC) format or NULL if the conversion fails.

sharkssl_PEM_to_RSAKey()

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.

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);
   }
}

Returns

the private/public key in SharkSslRSAKey format or NULL if the conversion fails.

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

privkey	is the private key in SharkSslRSAKey format.
sig	Pointer to the buffer where the signature will be stored. The buffer size must be at least SharkSslRSAKey_size.
siglen	Pointer to store the length of the generated signature (output parameter).
hash	Pointer to the hash to sign.
hashID	Identifier 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

pubkey	The public key in SharkSslRSAKey format. A corresponding private key may also be used.
sig	Pointer to the signature to verify.
siglen	The length of the signature in bytes (input parameter).
hash	Pointer to the hash to verify against the signature.
hashID	Identifier 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

privkey	is the private key in SharkSslRSAKey format.
in	the ciphertext
len	is the length/size of parameter 'in'. This length must be exactly SharkSslRSAKey_size (key).
out	the decrypted ciphertext is copied to this buffer. The size of this buffer must be no less than SharkSslRSAKey_size (key)
padding	is 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_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

privkey	is the private key in SharkSslRSAKey format.
in	commonly, an algorithm identifier followed by a message digest
len	is 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.
out	the signature is copied to this buffer. The size of this buffer must be no less than SharkSslRSAKey_size (key)
padding	is 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

pubkey	is the public key in SharkSslRSAKey format.
in	the RSA signature. Please notice that the RSA signature is modified by this function and must for this reason be in RAM.
len	is the length/size of parameter 'in'. This length must be exactly SharkSslRSAKey_size (key).
out	the message digest is copied to this buffer. The size of this buffer must be no less than SharkSslRSAKey_size (key)
padding	is 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

pubkey	is the public key in SharkSslRSAKey format.
in	the plaintext
len	is 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.
out	the encrypted ciphertext is copied to this buffer. The size of this buffer must be no less than SharkSslRSAKey_size (key)
padding	is one of SHARKSSL_RSA_PKCS1_PADDING or SHARKSSL_RSA_NO_PADDING

Returns

the size of the encrypted ciphertext, or -1 if any error occurs