RayCrypto API

Detailed Description

Cryptographic functions, including RSA, ECC, AES, hashing, etc..

RayCrypto offers developers a rich selection of cryptographic technologies, methods including RSA and elliptic curve, symmetric algorithms like 3DES and AES, message authentication, hashing and pseudorandom number generation.

Modules
	MD5
	MD5 cryptographic hash.
	SHA1
	SHA1 cryptographic hash.
	SHA256
	SHA256 cryptographic hash.
	SHA384
	SHA384 cryptographic hash.
	SHA512
	SHA512 cryptographic hash.
	HMAC
	HMAC keyed-hash message authentication code (in conjunction with: MD5,SHA1,SHA256,SHA384,SHA512)
	ARC4
	ARC4.
	DES
	DES.
	AES
	AES.
	AES-GCM
	AES-GCM.
	AES-CCM
	AES-CCM.
	POLY1305
	POLY1305.
	CHACHA20
	CHACHA20.
	ECDSA sign/verify functions
	See Signing and Verifying Binaries for an example of how to use the ECDSA ECDSA sign/verify functions.
	RSA encrypt/decrypt functions

Enumerations
enum	sharkssl_PEM_RetVal {   SHARKSSL_PEM_OK = 0 , SHARKSSL_PEM_OK_PUBLIC = 1 , SHARKSSL_PEM_ALLOCATION_ERROR = - 3000 , SHARKSSL_PEM_KEY_PARSE_ERROR ,   SHARKSSL_PEM_KEY_WRONG_IV , SHARKSSL_PEM_KEY_WRONG_LENGTH , SHARKSSL_PEM_KEY_PASSPHRASE_REQUIRED , SHARKSSL_PEM_KEY_UNRECOGNIZED_FORMAT ,   SHARKSSL_PEM_KEY_UNSUPPORTED_FORMAT , SHARKSSL_PEM_KEY_UNSUPPORTED_MODULUS_LENGTH , SHARKSSL_PEM_KEY_UNSUPPORTED_EXPONENT_LENGTH , SHARKSSL_PEM_KEY_UNSUPPORTED_ENCRYPTION_TYPE ,   SHARKSSL_PEM_KEY_CERT_MISMATCH , SHARKSSL_PEM_CERT_UNRECOGNIZED_FORMAT , SHARKSSL_PEM_CERT_UNSUPPORTED_TYPE , SHARKSSL_PEM_KEY_UNSUPPORTED_VERSION ,   SHARKSSL_PEM_KEY_REQUIRED , SHARKSSL_PEM_KEY_PRIVATE_KEY_REQUIRED , SHARKSSL_PEM_INTERNAL_ERROR }
	Return values from function sharkssl_PEM. More...

Functions
SHARKSSL_API sharkssl_PEM_RetVal	sharkssl_PEM (const char *certPEM, const char *keyPEM, const char *passphrase, SharkSslCert *sharkSslCert)
	Create a SharkSslCert certificate by using a certificate and key in PEM format. More...
SHARKSSL_API int	sharkssl_PEM_PBKDF2 (U8 *dk, const char *passphrase, const char *salt, U32 saltLen, U32 iterations, U16 dkLen, U8 hashID)
	sharkssl_PEM_PBKDF2 (output, passphrase, salt, salt_len, iterations, dkLen, hashID) Derives a key from a passphrase using the PBKDF2 algorithm as specified in RFC 8018 section 5.2. More...
SHARKSSL_API int	sharkssl_X25519_createKeyPair (U8 privateKey[SHARKSSL_X25519_KEY_LEN], U8 publicKey[SHARKSSL_X25519_KEY_LEN])
	Create an X25519 private/public key pair. More...
SHARKSSL_API int	sharkssl_X25519_sharedSecret (const U8 privateKey[SHARKSSL_X25519_KEY_LEN], const U8 peerPublicKey[SHARKSSL_X25519_KEY_LEN], U8 sharedSecret[SHARKSSL_X25519_KEY_LEN])
	Calculate an X25519 shared secret. More...

Enumeration Type Documentation

sharkssl_PEM_RetVal

enum sharkssl_PEM_RetVal

Return values from function sharkssl_PEM.

Enumerator
SHARKSSL_PEM_OK	OK.
SHARKSSL_PEM_OK_PUBLIC	OK_PUBLIC.
SHARKSSL_PEM_ALLOCATION_ERROR	ALLOCATION_ERROR.
SHARKSSL_PEM_KEY_PARSE_ERROR	KEY_PARSE_ERROR.
SHARKSSL_PEM_KEY_WRONG_IV	KEY_WRONG_IV.
SHARKSSL_PEM_KEY_WRONG_LENGTH	KEY_WRONG_LENGTH.
SHARKSSL_PEM_KEY_PASSPHRASE_REQUIRED	KEY_PASSPHRASE_REQUIRED.
SHARKSSL_PEM_KEY_UNRECOGNIZED_FORMAT	KEY_UNRECOGNIZED_FORMAT.
SHARKSSL_PEM_KEY_UNSUPPORTED_FORMAT	KEY_UNSUPPORTED_FORMAT.
SHARKSSL_PEM_KEY_UNSUPPORTED_MODULUS_LENGTH	KEY_UNSUPPORTED_MODULUS_LENGTH.
SHARKSSL_PEM_KEY_UNSUPPORTED_EXPONENT_LENGTH	KEY_UNSUPPORTED_EXPONENT_LENGTH.
SHARKSSL_PEM_KEY_UNSUPPORTED_ENCRYPTION_TYPE	KEY_UNSUPPORTED_ENCRYPTION_TYPE.
SHARKSSL_PEM_KEY_CERT_MISMATCH	KEY_CERT_MISMATCH.
SHARKSSL_PEM_CERT_UNRECOGNIZED_FORMAT	CERT_UNRECOGNIZED_FORMAT.
SHARKSSL_PEM_CERT_UNSUPPORTED_TYPE	CERT_UNSUPPORTED_TYPE.
SHARKSSL_PEM_KEY_UNSUPPORTED_VERSION	KEY_UNSUPPORTED_VERSION.
SHARKSSL_PEM_KEY_REQUIRED	KEY_REQUIRED.
SHARKSSL_PEM_KEY_PRIVATE_KEY_REQUIRED	A PRIVATE KEY IS REQUIRED.
SHARKSSL_PEM_INTERNAL_ERROR	INTERNAL ERROR.

Function Documentation

sharkssl_PEM()

SHARKSSL_API sharkssl_PEM_RetVal sharkssl_PEM	(	const char *	certPEM,
		const char *	keyPEM,
		const char *	passphrase,
		SharkSslCert *	sharkSslCert
	)

Create a SharkSslCert certificate by using a certificate and key in PEM format.

example:

int addMyCert(SharkSsl *shark)
{
   SharkSslCert *sharkCert;
   // The two following functions illustrate how a certificate and
   // key can be read from a file system and inserted into an
   // allocated buffer.
   char *cert=readMyCertFromFileSystem();
   char *key=readMyKeyFromFileSystem();
   if(sharkssl_PEM(cert,key,NULL,&sharkCert))
      return -1;
   free(cert);
   free(key);
   // You may redesign the code and keep a reference to the
   // SharkSslCert object if you design a system using dynamic objects
   // i.e. if you later plan on releasing the SharkSSL object and
   // the SharkSslCert object. You cannot release the SharkSslCert
   // object before releasing the SharkSSL object.
   SharkSsl_addCertificate(shark,sharkCert);
   return 0;
}

sharkssl_PEM_PBKDF2()

SHARKSSL_API int sharkssl_PEM_PBKDF2	(	U8 *	dk,
		const char *	passphrase,
		const char *	salt,
		U32	saltLen,
		U32	iterations,
		U16	dkLen,
		U8	hashID
	)

sharkssl_PEM_PBKDF2 (output, passphrase, salt, salt_len, iterations, dkLen, hashID) Derives a key from a passphrase using the PBKDF2 algorithm as specified in RFC 8018 section 5.2.

This function performs the Password-Based Key Derivation Function 2 (PBKDF2) to derive a key from a given passphrase. The derived key is computed by iterating the specified hash function over the passphrase and salt.

Parameters

dk	pointer to the buffer where the derived key will be stored
passphrase	pointer to the passphrase (null-terminated string) used to derive the key
salt	pointer to the salt string used in the key derivation process
saltLen	length of the salt in bytes
iterations	number of iterations to perform in the key derivation process
dkLen	desired length of the derived key in bytes.
hashID	identifier for the digest function to use; allowed values are: SHARKSSL_HASHID_SHA512, SHARKSSL_HASHID_SHA384, SHARKSSL_HASHID_SHA256

Returns

0 on success, or a non-zero error code on failure

sharkssl_X25519_createKeyPair()

SHARKSSL_API int sharkssl_X25519_createKeyPair	(	U8	privateKey[SHARKSSL_X25519_KEY_LEN],
		U8	publicKey[SHARKSSL_X25519_KEY_LEN]
	)

Create an X25519 private/public key pair.

Parameters

privateKey	receives the 32-byte private key. The key must be treated as opaque and passed unchanged to sharkssl_X25519_sharedSecret.
publicKey	receives the 32-byte RFC 7748 little-endian public u-coordinate.

Returns

zero on success and nonzero on error.

Note

The SharkSSL random number generator must be initialized and seeded before calling this function.

privateKey and publicKey must point to separate, non-overlapping 32-byte buffers.

sharkssl_X25519_sharedSecret()

SHARKSSL_API int sharkssl_X25519_sharedSecret	(	const U8	privateKey[SHARKSSL_X25519_KEY_LEN],
		const U8	peerPublicKey[SHARKSSL_X25519_KEY_LEN],
		U8	sharedSecret[SHARKSSL_X25519_KEY_LEN]
	)

Calculate an X25519 shared secret.

Parameters

privateKey	a 32-byte private key generated by sharkssl_X25519_createKeyPair. The key must be passed unchanged to this function.
peerPublicKey	the peer's 32-byte RFC 7748 public key.
sharedSecret	receives the 32-byte shared secret.

Returns

zero on success and nonzero on error. An all-zero shared secret is rejected.