From: schwarze <schwarze@openbsd.org>
Date: Sat, 26 Aug 2023 15:12:04 +0000 (+0000)
Subject: Write documentation for EVP_CIPHER_CTX_buf_noconst(3) from scratch.
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=0e80ab9d860cba37a8cbaddb1f7b336158e7e901;p=openbsd

Write documentation for EVP_CIPHER_CTX_buf_noconst(3) from scratch.
Put it here rather than into EVP_EncryptInit(3) because similar to
EVP_CIPHER_CTX_get_cipher_data(3), application software should not
use it.  These functions will likely not be needed except by people
implementing custom encryption algorithms.
---

diff --git a/lib/libcrypto/man/EVP_CIPHER_CTX_get_cipher_data.3 b/lib/libcrypto/man/EVP_CIPHER_CTX_get_cipher_data.3
index e60e1fb30ed..4f75c8b0085 100644
--- a/lib/libcrypto/man/EVP_CIPHER_CTX_get_cipher_data.3
+++ b/lib/libcrypto/man/EVP_CIPHER_CTX_get_cipher_data.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: EVP_CIPHER_CTX_get_cipher_data.3,v 1.2 2023/08/26 06:19:09 jsg Exp $
+.\" $OpenBSD: EVP_CIPHER_CTX_get_cipher_data.3,v 1.3 2023/08/26 15:12:04 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
-.\" This file was written by Matt Caswell <matt@openssl.org>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Matt Caswell <matt@openssl.org>.
 .\" Copyright (c) 2016 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -53,7 +70,8 @@
 .Os
 .Sh NAME
 .Nm EVP_CIPHER_CTX_get_cipher_data ,
-.Nm EVP_CIPHER_CTX_set_cipher_data
+.Nm EVP_CIPHER_CTX_set_cipher_data ,
+.Nm EVP_CIPHER_CTX_buf_noconst
 .Nd inspect and modify EVP_CIPHER_CTX objects
 .Sh SYNOPSIS
 .In openssl/evp.h
@@ -66,6 +84,10 @@
 .Fa "EVP_CIPHER_CTX *ctx"
 .Fa "void *cipher_data"
 .Fc
+.Ft unsigned char *
+.Fo EVP_CIPHER_CTX_buf_noconst
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fc
 .Sh DESCRIPTION
 .Fn EVP_CIPHER_CTX_get_cipher_data
 returns a pointer to the cipher data of
@@ -89,6 +111,15 @@ A pointer to any existing cipher data is returned from this function.
 If the old data is no longer required,
 it should be freed through a call to
 .Xr free 3 .
+.Pp
+.Fn EVP_CIPHER_CTX_buf_noconst
+provides engines and custom cipher implementations
+with access to the internal buffer that
+.Xr EVP_EncryptUpdate 3
+copies input data into before encrypting it.
+This function can for example be used
+inside callback functions installed with
+.Xr EVP_CIPHER_meth_set_do_cipher 3 .
 .Sh RETURN VALUES
 .Fn EVP_CIPHER_CTX_get_cipher_data
 returns an internal pointer owned by
@@ -98,12 +129,18 @@ returns an internal pointer owned by
 returns a pointer to the old cipher data of
 .Fa ctx
 and transfers ownership to the caller.
+.Pp
+.Fn EVP_CIPHER_CTX_buf_noconst
+returns a pointer to an internal buffer owned by
+.Fa ctx .
 .Sh SEE ALSO
 .Xr evp 3 ,
+.Xr EVP_CIPHER_meth_new 3 ,
 .Xr EVP_EncryptInit 3
 .Sh HISTORY
-.Fn EVP_CIPHER_CTX_get_cipher_data
+.Fn EVP_CIPHER_CTX_get_cipher_data ,
+.Fn EVP_CIPHER_CTX_set_cipher_data ,
 and
-.Fn EVP_CIPHER_CTX_set_cipher_data
+.Fn EVP_CIPHER_CTX_buf_noconst
 first appeared in OpenSSL 1.1.0 and have been available since
 .Ox 7.1 .