Talk:Random Numbers

2016-07-11T21:57:29Z

Drankinatty: /* Should we be promoting a commercial company? */

==Is RAND_poll part of the public API?==

I have removed the question about whether RAND_poll is considered part of the public API. The "rand" module contains two header files: rand.h and rand_locl.h. The first becomes part of the deployment when you install OpenSSL, whilst the latter does not. This is a common theme throughout the library. Basically anything in the *_locl.h header files should be considered private to the library, whilst anything that gets deployed should be considered part of the public API. Since RAND_poll is in rand.h (which gets deployed during installation) it should be considered part of the public API.

--[[User:Matt|Matt]] 12:26, 9 March 2013 (UTC)

: I think it would be good to get a clear statement of what constitutes the public API, because I'm getting conflicting messages. You state that anything in an installed header file is part of the public API. However, [[Contributions#Code_Maturity]] implies that functions are not part of the API until they are documented. Since RAND_poll is not documented, that interpretation would suggested that RAND_poll is not yet "cast in stone" and is subject to change.

: --[[User:Ppelleti|Ppelleti]] 00:03, 19 March 2013 (UTC)

:: I don't think there is a conflict between what I said above, and what it says on [[Contributions#Code_Maturity]]. That page merely says that the API might not have completely settled down which might be the reason why there isn't any documentation. It doesn't say that the API is not "public" until its been documented.

:: --[[User:Matt|Matt]] 21:05, 19 March 2013 (UTC)

::: Sidestepping the semantics of what it means to be "public", the real question I'm getting at is whether we should be encouraging people to use RAND_poll? Or did the OpenSSL developers leave RAND_poll undocumented on purpose?

::: --[[User:Ppelleti|Ppelleti]] 20:33, 20 March 2013 (UTC)

:::: Well in my personal opinion, we should not avoid undocumented functions merely because they are undocumented. If you're going to do that you might as well forget anything that involves elliptic curve keys! :-)

:::: --[[User:Matt|Matt]] 20:41, 20 March 2013 (UTC)

::::: Matt, Ppelleti - I *thought* the indicator was capital versus lowercase. <tt>RAND_poll</tt> is public, <tt>rand_poll</tt> is private and should not be used. I believe Viktor said the same some time ago on the OpenSSL Users mailing list. I can't find the reference at the moment.

::::: I also think presence/lack of documentation is a poor indicator. There's lots of stuff that's public that does not really have a man page.

::::: [[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 18:52, 4 June 2015 (UTC)

==Should we be promoting a commercial company?==

I am a little concerned about the link to entropykey. Should we be promoting a commercial company? Whilst the text reads fine at the moment it could be the "thin end of the wedge". This is a wiki after all. What's to stop other companies coming along and adding links to their products? How will we then decide which edits are ok, and which not? We don't want the page degenerating into a long list of products. Should we not have a policy of "no commerical endorsements"?

--[[User:Matt|Matt]] 12:33, 9 March 2013 (UTC)

: The intent was to provide a link to an inexpensive, high quality random source. Do you want to start a table *with* prices at the bottom of the page? Prices are important because some of this gear is expensive. $40 UK is dirt cheap for a FIPS approved generator. [[User:Jwalton|Jwalton]] 18:33, 30 March 2013 (UTC)

: No, I think a table would be worse. Leave it for now, we can review if it turns into a problem --[[User:Matt|Matt]] 08:28, 31 March 2013 (UTC)

==No RAND_save_file function In Library==
This page contains reference to ''RAND_save_file'' and is not consistent with the Manual:RAND load file(3) page (and there is no prototype found with `grep -d skip RAND_save_file /usr/include/openssl/*`)

[[User:Drankinatty|Drankinatty]] ([[User talk:Drankinatty|talk]]) 21:57, 11 July 2016 (UTC)

Talk:EVP Symmetric Encryption and Decryption

2015-06-05T04:11:00Z

Drankinatty: Created page with "-- updated example to build without warnings ~~~~"

-- updated example to build without warnings [[User:Drankinatty|Drankinatty]] ([[User talk:Drankinatty|talk]]) 04:11, 5 June 2015 (UTC)

EVP Symmetric Encryption and Decryption

2015-06-05T04:10:17Z

Drankinatty: /* Setting it up */

The [[Libcrypto API|libcrypto]] library within OpenSSL provides functions for performing symmetric encryption and decryption operations across a wide range of algorithms and modes. This page walks you through the basics of performing a simple encryption and corresponding decryption operation.

In order to perform encryption/decryption you need to know:
* Your algorithm
* Your mode
* Your key
* Your Initialisation Vector (IV)

This page assumes that you know what all of these things mean. If you don't then please refer to [[Basics of Encryption]].

==Setting it up==

The code below sets up the program. In this example we are going to take a simple message ("The quick brown fox jumps over the lazy dog"), and then encrypt it using a predefined key and IV. In this example the key and IV have been hard coded in - in a real situation you would never do this! Following encryption we will then decrypt the resulting ciphertext, and (hopefully!) end up with the message we first started with. This program expects two functions to be defined: "encrypt" and "decrypt". We will define those further down the page.

#include <openssl/conf.h>
#include <openssl/evp.h>
#include <openssl/err.h>
#include <string.h>

int main (void)
{
/* Set up the key and iv. Do I need to say to not hard code these in a
* real application? :-)
*/

/* A 256 bit key */
unsigned char *key = (unsigned char *)"01234567890123456789012345678901";

/* A 128 bit IV */
unsigned char *iv = (unsigned char *)"01234567890123456";

/* Message to be encrypted */
unsigned char *plaintext =
(unsigned char *)"The quick brown fox jumps over the lazy dog";

/* Buffer for ciphertext. Ensure the buffer is long enough for the
* ciphertext which may be longer than the plaintext, dependant on the
* algorithm and mode
*/
unsigned char ciphertext[128];

/* Buffer for the decrypted text */
unsigned char decryptedtext[128];

int decryptedtext_len, ciphertext_len;

/* Initialise the library */
ERR_load_crypto_strings();
OpenSSL_add_all_algorithms();
OPENSSL_config(NULL);

/* Encrypt the plaintext */
ciphertext_len = encrypt (plaintext, strlen ((char *)plaintext), key, iv,
ciphertext);

/* Do something useful with the ciphertext here */
printf("Ciphertext is:\n");
BIO_dump_fp (stdout, (const char *)ciphertext, ciphertext_len);

/* Decrypt the ciphertext */
decryptedtext_len = decrypt(ciphertext, ciphertext_len, key, iv,
decryptedtext);

/* Add a NULL terminator. We are expecting printable text */
decryptedtext[decryptedtext_len] = '\0';

/* Show the decrypted text */
printf("Decrypted text is:\n");
printf("%s\n", decryptedtext);

/* Clean up */
EVP_cleanup();
ERR_free_strings();

return 0;
}

The program sets up a 256 bit key and a 128 bit IV. This is appropriate for the 256-bit AES encryption that we going to be doing in CBC mode. Make sure you use the right key and IV length for the cipher you have selected, or it will go horribly wrong!!

We've also set up a buffer for the ciphertext to be placed in. It is important to ensure that this buffer is sufficiently large for the expected ciphertext or you may see a program crash (or potentially introduce a security vulnerability into your code). Note: The ciphertext may be longer than the plaintext (e.g. if padding is being used).

We're also going to need a helper function to handle any errors. This will simply dump any error messages from the OpenSSL error stack to the screen, and then abort the program.

void handleErrors(void)
{
ERR_print_errors_fp(stderr);
abort();
}

==Encrypting the message==

So now that we have set up the program we need to define the "encrypt" function. This will take as parameters the plaintext, the length of the plaintext, the key to be used, and the IV. We'll also take in a buffer to put the ciphertext in (which we assume to be long enough), and will return the length of the ciphertext that we have written.

Encrypting consists of the following stages:
* Setting up a context
* Initialising the encryption operation
* Providing plaintext bytes to be encrypted
* Finalising the encryption operation

During initialisation we will provide an EVP_CIPHER object. In this case we are using EVP_aes_256_cbc(), which uses the AES algorithm with a 256-bit key in [[CBC]] mode. Refer to [[EVP#Working with Algorithms and Modes]] for further details.

int encrypt(unsigned char *plaintext, int plaintext_len, unsigned char *key,
unsigned char *iv, unsigned char *ciphertext)
{
EVP_CIPHER_CTX *ctx;

int len;

int ciphertext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new())) handleErrors();

/* Initialise the encryption operation. IMPORTANT - ensure you use a key
* and IV size appropriate for your cipher
* In this example we are using 256 bit AES (i.e. a 256 bit key). The
* IV size for *most* modes is the same as the block size. For AES this
* is 128 bits */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_cbc(), NULL, key, iv))
handleErrors();

/* Provide the message to be encrypted, and obtain the encrypted output.
* EVP_EncryptUpdate can be called multiple times if necessary
*/
if(1 != EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len))
handleErrors();
ciphertext_len = len;

/* Finalise the encryption. Further ciphertext bytes may be written at
* this stage.
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len)) handleErrors();
ciphertext_len += len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}

==Decrypting the Message==

Finally we need to define the "decrypt" operation. This is very similar to encryption and consists of the following stages:
Encrypting consists of the following stages:
* Setting up a context
* Initialising the decryption operation
* Providing ciphertext bytes to be decrypted
* Finalising the decryption operation

Again through the parameters we will receive the ciphertext to be decrypted, the length of the ciphertext, the key and the IV. We'll also receive a buffer to place the decrypted text into, and return the length of the plaintext we have found.

Note that we have passed the length of the ciphertext. This is required as you cannot use functions such as "strlen" on this data - its binary! Similarly, even though in this example our plaintext really is ASCII text, OpenSSL does not know that. In spite of the name plaintext could be binary data, and therefore no NULL terminator will be put on the end (unless you encrypt the NULL as well of course).

Here is the decrypt function:

int decrypt(unsigned char *ciphertext, int ciphertext_len, unsigned char *key,
unsigned char *iv, unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;

int len;

int plaintext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new())) handleErrors();

/* Initialise the decryption operation. IMPORTANT - ensure you use a key
* and IV size appropriate for your cipher
* In this example we are using 256 bit AES (i.e. a 256 bit key). The
* IV size for *most* modes is the same as the block size. For AES this
* is 128 bits */
if(1 != EVP_DecryptInit_ex(ctx, EVP_aes_256_cbc(), NULL, key, iv))
handleErrors();

/* Provide the message to be decrypted, and obtain the plaintext output.
* EVP_DecryptUpdate can be called multiple times if necessary
*/
if(1 != EVP_DecryptUpdate(ctx, plaintext, &len, ciphertext, ciphertext_len))
handleErrors();
plaintext_len = len;

/* Finalise the decryption. Further plaintext bytes may be written at
* this stage.
*/
if(1 != EVP_DecryptFinal_ex(ctx, plaintext + len, &len)) handleErrors();
plaintext_len += len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return plaintext_len;
}

==Output==

If all goes well you should end up with output that looks like the following:
Ciphertext is:
0000 - e0 6f 63 a7 11 e8 b7 aa-9f 94 40 10 7d 46 80 a1 .oc.......@.}F..
0010 - 17 99 43 80 ea 31 d2 a2-99 b9 53 02 d4 39 b9 70 ..C..1....S..9.p
0020 - 2c 8e 65 a9 92 36 ec 92-07 04 91 5c f1 a9 8a 44 ,.e..6.....\...D
Decrypted text is:
The quick brown fox jumps over the lazy dog

For further details about symmetric encryption and decryption operations refer to the OpenSSL documentation [[Manual:EVP_EncryptInit(3)]].

==Notes on some unusual modes==

Worthy of mention here is the [[XTS]] mode (e.g. EVP_aes_256_xts()). This works in exactly the same way as shown above, except that the "tweak" is provided in the IV parameter. A further "gotcha" is that XTS mode expects a key which is twice as long as normal. Therefore EVP_aes_256_xts() expects a key which is 512-bits long.

Authenticated encryption modes ([[GCM]] or [[CCM]]) work in essentially the same way as shown above but require some special handling. See [[EVP Authenticated Encryption and Decryption]] for further details.

==See also==
* [[EVP]]
* [[Libcrypto API]]

[[Category:Crypto API]]
[[Category:C level]]
[[Category:Examples]]

OpenSSLWiki - User contributions [en]

Talk:Random Numbers

Talk:EVP Symmetric Encryption and Decryption

EVP Symmetric Encryption and Decryption