From cd52bfb7eb8d13d5dd568315c1b757aea4ff021d Mon Sep 17 00:00:00 2001 From: schwarze Date: Tue, 26 Dec 2023 22:13:00 +0000 Subject: [PATCH] Rename some argument placeholders to be less cryptic, in particular s/inl/in_len/ and s/outl/out_len/ as suggested by tb@. While here, also get rid of the "outm" placeholder that has been around since the file was added to OpenSSL in 2000, replacing it with the usual "out" in the four function prototypes affected; tb@ and myself suspect it was simply a typo followed by copy and paste. Slightly improve variable naming in the examples, too, for clarity and consistency, even though that doesn't turn the examples into good examples. OK tb@ --- lib/libcrypto/man/EVP_CIPHER_CTX_init.3 | 12 +-- lib/libcrypto/man/EVP_EncryptInit.3 | 101 ++++++++++++------------ 2 files changed, 58 insertions(+), 55 deletions(-) diff --git a/lib/libcrypto/man/EVP_CIPHER_CTX_init.3 b/lib/libcrypto/man/EVP_CIPHER_CTX_init.3 index 50df2e764dd..f328fc05b27 100644 --- a/lib/libcrypto/man/EVP_CIPHER_CTX_init.3 +++ b/lib/libcrypto/man/EVP_CIPHER_CTX_init.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_CIPHER_CTX_init.3,v 1.2 2023/12/26 19:09:08 schwarze Exp $ +.\" $OpenBSD: EVP_CIPHER_CTX_init.3,v 1.3 2023/12/26 22:13:00 schwarze Exp $ .\" full merge up to: .\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100 .\" @@ -91,7 +91,7 @@ .Fa "EVP_CIPHER_CTX *ctx" .Fa "unsigned char *out" .Fa "const unsigned char *in" -.Fa "unsigned int inl" +.Fa "unsigned int in_len" .Fc .Sh DESCRIPTION .Fn EVP_CIPHER_CTX_init @@ -133,11 +133,11 @@ behaviour depends on If that argument is .Dv NULL and -.Fa inl +.Fa in_len is 0, behaviour is similar to .Xr EVP_CipherFinal 3 ; if -.Fa inl +.Fa in_len is not 0, behaviour is undefined. If .Fa in @@ -158,7 +158,7 @@ It requires that the previous encryption or decryption operation using the same .Fa ctx , if there was any, ended exactly on a block boundary and that -.Fa inl +.Fa in_len is an integer multiple of the cipher block size. If either of these conditions is violated, .Fn EVP_Cipher @@ -167,7 +167,7 @@ For that reason, using the function .Xr EVP_CipherUpdate 3 instead is strongly recommended. The latter can safely handle partial blocks, and even if -.Fa inl +.Fa in_len actually is a multiple of the cipher block size for all calls, the overhead incurred by using .Xr EVP_CipherUpdate 3 diff --git a/lib/libcrypto/man/EVP_EncryptInit.3 b/lib/libcrypto/man/EVP_EncryptInit.3 index 7deabe92c1a..e8d22d8677f 100644 --- a/lib/libcrypto/man/EVP_EncryptInit.3 +++ b/lib/libcrypto/man/EVP_EncryptInit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_EncryptInit.3,v 1.50 2023/12/01 13:43:37 schwarze Exp $ +.\" $OpenBSD: EVP_EncryptInit.3,v 1.51 2023/12/26 22:13:00 schwarze Exp $ .\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800 .\" EVP_bf_cbc.pod EVP_cast5_cbc.pod EVP_idea_cbc.pod EVP_rc2_cbc.pod .\" 7c6d372a Nov 20 13:20:01 2018 +0000 @@ -69,7 +69,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 1 2023 $ +.Dd $Mdocdate: December 26 2023 $ .Dt EVP_ENCRYPTINIT 3 .Os .Sh NAME @@ -150,15 +150,15 @@ .Fo EVP_EncryptUpdate .Fa "EVP_CIPHER_CTX *ctx" .Fa "unsigned char *out" -.Fa "int *outl" +.Fa "int *out_len" .Fa "const unsigned char *in" -.Fa "int inl" +.Fa "int in_len" .Fc .Ft int .Fo EVP_EncryptFinal_ex .Fa "EVP_CIPHER_CTX *ctx" .Fa "unsigned char *out" -.Fa "int *outl" +.Fa "int *out_len" .Fc .Ft int .Fo EVP_DecryptInit_ex @@ -172,15 +172,15 @@ .Fo EVP_DecryptUpdate .Fa "EVP_CIPHER_CTX *ctx" .Fa "unsigned char *out" -.Fa "int *outl" +.Fa "int *out_len" .Fa "const unsigned char *in" -.Fa "int inl" +.Fa "int in_len" .Fc .Ft int .Fo EVP_DecryptFinal_ex .Fa "EVP_CIPHER_CTX *ctx" -.Fa "unsigned char *outm" -.Fa "int *outl" +.Fa "unsigned char *out" +.Fa "int *out_len" .Fc .Ft int .Fo EVP_CipherInit_ex @@ -195,15 +195,15 @@ .Fo EVP_CipherUpdate .Fa "EVP_CIPHER_CTX *ctx" .Fa "unsigned char *out" -.Fa "int *outl" +.Fa "int *out_len" .Fa "const unsigned char *in" -.Fa "int inl" +.Fa "int in_len" .Fc .Ft int .Fo EVP_CipherFinal_ex .Fa "EVP_CIPHER_CTX *ctx" -.Fa "unsigned char *outm" -.Fa "int *outl" +.Fa "unsigned char *out" +.Fa "int *out_len" .Fc .Ft int .Fo EVP_EncryptInit @@ -216,7 +216,7 @@ .Fo EVP_EncryptFinal .Fa "EVP_CIPHER_CTX *ctx" .Fa "unsigned char *out" -.Fa "int *outl" +.Fa "int *out_len" .Fc .Ft int .Fo EVP_DecryptInit @@ -228,8 +228,8 @@ .Ft int .Fo EVP_DecryptFinal .Fa "EVP_CIPHER_CTX *ctx" -.Fa "unsigned char *outm" -.Fa "int *outl" +.Fa "unsigned char *out" +.Fa "int *out_len" .Fc .Ft int .Fo EVP_CipherInit @@ -242,8 +242,8 @@ .Ft int .Fo EVP_CipherFinal .Fa "EVP_CIPHER_CTX *ctx" -.Fa "unsigned char *outm" -.Fa "int *outl" +.Fa "unsigned char *out" +.Fa "int *out_len" .Fc .Ft int .Fo EVP_CIPHER_CTX_encrypting @@ -378,7 +378,7 @@ This is done when the default cipher parameters are not appropriate. .Pp .Fn EVP_EncryptUpdate encrypts -.Fa inl +.Fa in_len bytes from the buffer .Fa in and writes the encrypted version to @@ -387,11 +387,13 @@ This function can be called multiple times to encrypt successive blocks of data. The amount of data written depends on the block alignment of the encrypted data: as a result the amount of data written may be anything -from zero bytes to (inl + cipher_block_size - 1) so +from zero bytes to +.Pq Fa in_len No + cipher_block_size - 1 +so .Fa out should contain sufficient room. The actual number of bytes written is placed in -.Fa outl . +.Pf * Fa out_len . .Pp If padding is enabled (the default) then .Fn EVP_EncryptFinal @@ -405,7 +407,7 @@ The encrypted final data is written to .Fa out which should have sufficient space for one cipher block. The number of bytes written is placed in -.Fa outl . +.Pf * Fa out_len . After this function is called, the encryption operation is finished and no further calls to .Fn EVP_EncryptUpdate @@ -436,9 +438,10 @@ operations except that if padding is enabled the decrypted data buffer .Fa out passed to .Fn EVP_DecryptUpdate -should have sufficient room for (inl + cipher_block_size) bytes -unless the cipher block size is 1 in which case -.Fa inl +should have sufficient room for +.Pq Fa in_len No + cipher_block_size +bytes unless the cipher block size is 1 in which case +.Fa in_len bytes is sufficient. .Pp .Fn EVP_CipherInit , @@ -703,7 +706,7 @@ parameters set to .Dv NULL and the length passed in the -.Fa inl +.Fa in_len parameter. .Pp The following ctrls are supported in CCM mode: @@ -729,25 +732,25 @@ The nonce length is given by 15 - L so it is 7 by default for AES. Encrypt a string using blowfish: .Bd -literal -offset 3n int -do_crypt(char *outfile) +do_crypt(char *out_filename) { - unsigned char outbuf[1024]; - int outlen, tmplen; + unsigned char out_buf[1024]; + int out_len, tmp_len; /* * Bogus key and IV: we'd normally set these from * another source. */ unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; unsigned char iv[] = {1,2,3,4,5,6,7,8}; - const char intext[] = "Some Crypto Text"; + const char in_text[] = "Some Crypto Text"; EVP_CIPHER_CTX *ctx; - FILE *out; + FILE *out_fileptr; ctx = EVP_CIPHER_CTX_new(); EVP_EncryptInit_ex(ctx, EVP_bf_cbc(), NULL, key, iv); - if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, - strlen(intext))) { + if (!EVP_EncryptUpdate(ctx, out_buf, &out_len, in_text, + strlen(in_text))) { /* Error */ EVP_CIPHER_CTX_free(ctx); return 0; @@ -756,12 +759,12 @@ do_crypt(char *outfile) * Buffer passed to EVP_EncryptFinal() must be after data just * encrypted to avoid overwriting it. */ - if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { + if (!EVP_EncryptFinal_ex(ctx, out_buf + out_len, &tmp_len)) { /* Error */ EVP_CIPHER_CTX_free(ctx); return 0; } - outlen += tmplen; + out_len += tmp_len; EVP_CIPHER_CTX_free(ctx); /* * Need binary mode for fopen because encrypted data is @@ -769,13 +772,13 @@ do_crypt(char *outfile) * it won't be NUL terminated and may contain embedded * NULs. */ - out = fopen(outfile, "wb"); - if (out == NULL) { + out_fileptr = fopen(out_filename, "wb"); + if (out_fileptr == NULL) { /* Error */ return 0; } - fwrite(outbuf, 1, outlen, out); - fclose(out); + fwrite(out_buf, 1, out_len, out_fileptr); + fclose(out_fileptr); return 1; } .Ed @@ -792,11 +795,11 @@ General encryption, decryption function example using FILE I/O and AES128 with a 128-bit key: .Bd -literal int -do_crypt(FILE *in, FILE *out, int do_encrypt) +do_crypt(FILE *in_fileptr, FILE *out_fileptr, int do_encrypt) { /* Allow enough space in output buffer for additional block */ - unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; - int inlen, outlen; + unsigned char in_buf[1024], out_buf[1024 + EVP_MAX_BLOCK_LENGTH]; + int in_len, out_len; EVP_CIPHER_CTX *ctx; /* @@ -812,23 +815,23 @@ do_crypt(FILE *in, FILE *out, int do_encrypt) EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); for (;;) { - inlen = fread(inbuf, 1, 1024, in); - if (inlen <= 0) + in_len = fread(in_buf, 1, 1024, in_fileptr); + if (in_len <= 0) break; - if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, - inlen)) { + if (!EVP_CipherUpdate(ctx, out_buf, &out_len, in_buf, + in_len)) { /* Error */ EVP_CIPHER_CTX_free(ctx); return 0; } - fwrite(outbuf, 1, outlen, out); + fwrite(out_buf, 1, out_len, out_fileptr); } - if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) { + if (!EVP_CipherFinal_ex(ctx, out_buf, &out_len)) { /* Error */ EVP_CIPHER_CTX_free(ctx); return 0; } - fwrite(outbuf, 1, outlen, out); + fwrite(out_buf, 1, out_len, out_fileptr); EVP_CIPHER_CTX_free(ctx); return 1; -- 2.20.1