Functions - gavincabbage/grsa GitHub Wiki
Home | Data Structures | Tools
The GRSA library supports key generation, encryption and digital authentication through its core functions. These include grsa_generate_keypair(), grsa_encrypt(), grsa_decrypt(), grsa_sign() and grsa_verify(). Administrative tasks are also provided for through miscellaneous helper functions. All functions return 0 on success, or -1 if a negative result is required. On error, values are returned based on error codes defined in grsa.h. Test for specific error codes, or pass the return value to grsa_perror() for more details.
Please note that while the library allows the programmer to use the RSA algorithm as a block cipher, this is not wise in practice. Generally, the library should be used to encrypt or decrypt small messages, less than the size of the key. For instance, in a hybrid asymmetric/symmetric system, the GRSA library could be used to encrypt and decrypt symmetric session keys for secure communication between parties.
Key Generation
Generate a GRSA keypair
Return a pointer to a GRSA keypair structure containing public and private keys of the given length and public exponent. Pass 0 to use the default public exponent as defined in grsa.h. Return zero on success, non-zero on error.
Note: Memory is allocated for the keypair buffer in this function.
int grsa_generate_keypair
(
grsa_keypair **keypair, /* Pointer to keypair buffer to populate. */
const mp_bitcnt_t bits, /* Size of key to be generated in bits. */
unsigned long pub_exp /* Public exponent to be used. */
);
Verify a GRSA keypair
Verify that the given keypair structure is a valid RSA key by encrypting and decrypting a randomly generated block of data. Return 0 on successful positive key verification and -1 on successful negative key verification. Return greater than 0 on error.
int grsa_verify_keypair
(
const grsa_keypair *keypair /* Keypair to test. */
);
Encryption & Decryption
Encrypt a data buffer
Use the given GRSA public key to encrypt a data buffer. Blocks of the specified blocksize are encoded according to the given encoding scheme before encryption. After memory allocation, write the encrypted data to the given ciphertext buffer, which must be initialized to NULL. Pass an unsigned integer pointer as the second argument to save the length of the computed ciphertext, or NULL to discard. Return 0 on success, non-zero on error.
Note: Memory is allocated for the ciphertext buffer in this function.
int grsa_encrypt
(
uchar **ciphertext, /* Pointer to ciphertext buffer to populate. */
uint *ciphertext_len, /* Length of computed ciphertext in bytes. */
const uchar *plaintext, /* Plaintext buffer to be encrypted. */
const uint plaintext_len, /* Length of plaintext buffer. */
const grsa_key *key, /* Public key to be used during encryption. */
uint encoding, /* Encoding scheme to use. */
uint blocksize /* Size of message blocks to be encrypted. */
);
Decrypt a data buffer
Use the given RSA private key to decrypt an encrypted data buffer. After memory allocation, write the decrypted plaintext to the given plaintext buffer, which must be initialized to NULL. Pass an unsigned integer pointer as the second argument to save the length of the computed plaintext, or NULL to discard. Return 0 on success, non-zero on error.
Note: Memory is allocated for the plaintext buffer in this function.
int grsa_decrypt
(
uchar **plaintext, /* Pointer to plaintext buffer to populate. */
uint *plaintext_len, /* Length of computed plaintext in bytes. */
const uchar *ciphertext, /* Ciphertext buffer to be decrypted. */
const uint ciphertext_len, /* Length of ciphertext buffer. */
const grsa_key *key, /* Private key to be used for decryption. */
uint encoding, /* Encoding scheme to use. */
uint blocksize /* Size of message blocks to be decrypted */
);
Digital Signing & Signature Verification
Sign a data buffer
Use the given RSA private key to sign a hash digest of a data buffer. After memory allocation, write the signed digest to the given signature buffer, which must be initialized to NULL. The computed signature can be verified with grsa_verify(). Return 0 on success, non-zero on error.
Note: Memory is allocated for the signature buffer in this function.
int grsa_sign
(
uchar **signature, /* Pointer to signature buffer to populate. */
uint *sig_len, /* Length of computed signature. */
const uchar *data, /* Data buffer to sign. */
const uint msg_len, /* Length of data buffer. */
const grsa_key *key /* Private key used to sign digest. */
);
Verify a data buffer's signature
Use the given RSA public key to verify the a data buffer's digital signature. After decrypting the signature, a new digest is computed from the the data buffer and the two digests are compared. Return 0 on successful positive signature verification and -1 on successful negative signature verification. Return greater than 0 on error.
int grsa_verify
(
const uchar *signature, /* Signature buffer to be verified. */
const uint sig_len, /* Length of signature buffer. */
const uchar *data, /* Signed plaintext buffer. */
const uint data_len, /* Length of plaintext buffer. */
const grsa_key *key /* Public key used to verify signature. */
);
Miscellaneous
Export a GRSA key to a data buffer.
Write the given key structure to the given buffer. The buffer is formatted into three segments: 4 bytes contain the key size, followed by two segments holding the modulus and exponent respectively. Each of the latter segments are keysize bytes long. Return 0 on success, non-zero on error.
Note: Memory is allocated for the export buffer in this function.
int grsa_export
(
uchar **buffer, /* Pointer to buffer to populate. */
uint *buffer_len, /* Length of data written to buffer. */
const grsa_key *key /* Key to export. */
);
Import a data buffer into a GRSA key.
Read the given data buffer into a GRSA key structure. The buffer is expected to formatted as described and implemented in grsa_export(). Return 0 on success, non-zero on error.
Note: Memory is allocated for the key buffer in this function.
int grsa_import
(
grsa_key **key, /* Pointer to key structure to populate. */
const uchar *buffer, /* Data buffer to import. */
const uint buffer_len /* Length of data buffer. */
);
Free a GRSA key structure.
Clear the GMP integer's representing the key's modulus and exponent and free all memory allocated to the key buffer.
void grsa_clrkey
(
grsa_key *key /* Key to be cleared. */
);
Free a GRSA keypair structure.
Clear the keypair's public and private keys and free all memory allocated to the keypair buffer.
void grsa_clrkeypair
(
grsa_keypair *keypair /* Keypair to be cleared. */
);
Print a success/error message.
Display a message to stderr based on the given return value from the source function. A positive value indicates an error, while 0 and -1 indicate successful execution.
void grsa_perror
(
const char *src, /* Source function. */
int retval /* Return value on which to elaborate. */
);
Home | Data Structures | Tools
Gavin Cabbage, 2013.
Please see the included MIT License for more information.