diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_EncodeInit.3')
-rw-r--r-- | secure/lib/libcrypto/man/man3/EVP_EncodeInit.3 | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_EncodeInit.3 b/secure/lib/libcrypto/man/man3/EVP_EncodeInit.3 new file mode 100644 index 000000000000..9b16686cf317 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/EVP_EncodeInit.3 @@ -0,0 +1,247 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_ENCODEINIT 3ossl" +.TH EVP_ENCODEINIT 3ossl 2025-09-30 3.5.4 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy, +EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, +EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, +EVP_DecodeBlock \- EVP base64 encode/decode routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/evp.h> +\& +\& EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void); +\& void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx); +\& int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx); +\& int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx); +\& void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); +\& int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, +\& const unsigned char *in, int inl); +\& void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); +\& int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n); +\& +\& void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); +\& int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, +\& const unsigned char *in, int inl); +\& int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); +\& int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP encode routines provide a high-level interface to base64 encoding and +decoding. +Base64 encoding converts binary data into a printable form that uses +the characters A\-Z, a\-z, 0\-9, "+" and "/" to represent the data. For every 3 +bytes of binary data provided 4 bytes of base64 encoded data will be produced +plus some occasional newlines (see below). If the input data length is not a +multiple of 3 then the output data will be padded at the end using the "=" +character. +.PP +\&\fBEVP_ENCODE_CTX_new()\fR allocates, initializes and returns a context to be used for +the encode/decode functions. +.PP +\&\fBEVP_ENCODE_CTX_free()\fR cleans up an encode/decode context \fBctx\fR and frees up the +space allocated to it. If the argument is NULL, nothing is done. +.PP +Encoding of binary data is performed in blocks of 48 input bytes (or less for +the final block). +For each 48 byte input block encoded 64 bytes of base64 data +is output plus an additional newline character (i.e. 65 bytes in total). The +final block (which may be less than 48 bytes) will output 4 bytes for every 3 +bytes of input. If the data length is not divisible by 3 then a full 4 bytes is +still output for the final 1 or 2 bytes of input. Similarly a newline character +will also be output. +.PP +\&\fBEVP_EncodeInit()\fR initialises \fBctx\fR for the start of a new encoding operation. +.PP +\&\fBEVP_EncodeUpdate()\fR encode \fBinl\fR bytes of data found in the buffer pointed to by +\&\fBin\fR. The output is stored in the buffer \fBout\fR and the number of bytes output +is stored in \fB*outl\fR. It is the caller's responsibility to ensure that the +buffer at \fBout\fR is sufficiently large to accommodate the output data. Only full +blocks of data (48 bytes) will be immediately processed and output by this +function. Any remainder is held in the \fBctx\fR object and will be processed by a +subsequent call to \fBEVP_EncodeUpdate()\fR or \fBEVP_EncodeFinal()\fR. To calculate the +required size of the output buffer add together the value of \fBinl\fR with the +amount of unprocessed data held in \fBctx\fR and divide the result by 48 (ignore +any remainder). This gives the number of blocks of data that will be processed. +Ensure the output buffer contains 65 bytes of storage for each block, plus an +additional byte for a NUL terminator. \fBEVP_EncodeUpdate()\fR may be called +repeatedly to process large amounts of input data. In the event of an error +\&\fBEVP_EncodeUpdate()\fR will set \fB*outl\fR to 0 and return 0. On success 1 will be +returned. +.PP +\&\fBEVP_EncodeFinal()\fR must be called at the end of an encoding operation. It will +process any partial block of data remaining in the \fBctx\fR object. The output +data will be stored in \fBout\fR and the length of the data written will be stored +in \fB*outl\fR. It is the caller's responsibility to ensure that \fBout\fR is +sufficiently large to accommodate the output data which will never be more than +65 bytes plus an additional NUL terminator (i.e. 66 bytes in total). +.PP +\&\fBEVP_ENCODE_CTX_copy()\fR can be used to copy a context \fBsctx\fR to a context +\&\fBdctx\fR. \fBdctx\fR must be initialized before calling this function. +.PP +\&\fBEVP_ENCODE_CTX_num()\fR will return the number of as yet unprocessed bytes still to +be encoded or decoded that are pending in the \fBctx\fR object. +.PP +\&\fBEVP_EncodeBlock()\fR encodes a full block of input data in \fBf\fR and of length +\&\fBn\fR and stores it in \fBt\fR. For every 3 bytes of input provided 4 bytes of +output data will be produced. If \fBn\fR is not divisible by 3 then the block is +encoded as a final block of data and the output is padded such that it is always +divisible by 4. Additionally a NUL terminator character will be added. For +example if 16 bytes of input data is provided then 24 bytes of encoded data is +created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of +the data generated \fIwithout\fR the NUL terminator is returned from the function. +.PP +\&\fBEVP_DecodeInit()\fR initialises \fBctx\fR for the start of a new decoding operation. +.PP +\&\fBEVP_DecodeUpdate()\fR decodes \fBinl\fR characters of data found in the buffer +pointed to by \fBin\fR. +The output is stored in the buffer \fBout\fR and the number of bytes output is +stored in \fB*outl\fR. +It is the caller's responsibility to ensure that the buffer at \fBout\fR is +sufficiently large to accommodate the output data. +This function will attempt to decode as much data as possible in chunks of up +to 80 base64 characters at a time. +Residual input shorter than the internal chunk size will be buffered in \fBctx\fR +if its length is not a multiple of 4 (including any padding), to be processed +in future calls to \fBEVP_DecodeUpdate()\fR or \fBEVP_DecodeFinal()\fR. +If the final chunk length is a multiple of 4, it is decoded immediately and +not buffered. +.PP +Any whitespace, newline or carriage return characters are ignored. +For compatibility with \fBPEM\fR, the \fB\-\fR (hyphen) character is treated as a soft +end-of-input, subsequent bytes are not buffered, and the return value will be +0 to indicate that the end of the base64 input has been detected. +The soft end-of-input, if present, MUST occur after a multiple of 4 valid base64 +input bytes. +The soft end-of-input condition is not remembered in \fBctx\fR, it is up to the +caller to avoid further calls to \fBEVP_DecodeUpdate()\fR after a 0 or negative +(error) return. +.PP +If any invalid base64 characters are encountered or if the base64 padding +character (\fB=\fR) is encountered in the middle of the data then +\&\fBEVP_DecodeUpdate()\fR returns \-1 to indicate an error. +A return value of 0 or 1 indicates successful processing of the data. +A return value of 0 additionally indicates that the last 4 bytes processed +ended with base64 padding (\fB=\fR), or that the next 4 byte group starts with the +soft end-of-input (\fB\-\fR) character, and therefore no more input data is +expected to be processed. +.PP +For every 4 valid base64 bytes processed (ignoring whitespace, carriage returns +and line feeds), 3 bytes of binary output data will be produced (except at the +end of data terminated with one or two padding characters). +.PP +\&\fBEVP_DecodeFinal()\fR should be called at the end of a decoding operation, +but it will never decode additional data. If there is no residual data +it will return 1 to indicate success. If there is residual data, its +length is not a multiple of 4, i.e. it was not properly padded, \-1 is +is returned in that case to indicate an error. +.PP +\&\fBEVP_DecodeBlock()\fR will decode the block of \fBn\fR characters of base64 data +contained in \fBf\fR and store the result in \fBt\fR. +Any leading whitespace will be trimmed as will any trailing whitespace, +newlines, carriage returns or EOF characters. +Internal whitespace MUST NOT be present. +After trimming the data in \fBf\fR MUST consist entirely of valid base64 +characters or padding (only at the tail of the input) and its length MUST be +divisible by 4. +For every 4 input bytes exactly 3 output bytes will be produced. +Padding bytes (\fB=\fR) (even if internal) are decoded to 6 zero bits, the caller +is responsible for taking trailing padding into account, by ignoring as many +bytes at the tail of the returned output. +\&\fBEVP_DecodeBlock()\fR will return the length of the data decoded or \-1 on error. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_ENCODE_CTX_new()\fR returns a pointer to the newly allocated EVP_ENCODE_CTX +object or NULL on error. +.PP +\&\fBEVP_ENCODE_CTX_num()\fR returns the number of bytes pending encoding or decoding in +\&\fBctx\fR. +.PP +\&\fBEVP_EncodeUpdate()\fR returns 0 on error or 1 on success. +.PP +\&\fBEVP_EncodeBlock()\fR returns the number of bytes encoded excluding the NUL +terminator. +.PP +\&\fBEVP_DecodeUpdate()\fR returns \-1 on error and 0 or 1 on success. If 0 is returned +then no more non-padding base64 characters are expected. +.PP +\&\fBEVP_DecodeFinal()\fR returns \-1 on error or 1 on success. +.PP +\&\fBEVP_DecodeBlock()\fR returns the length of the data decoded or \-1 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_DecodeUpdate()\fR function was fixed in OpenSSL 3.5, +so now it produces the number of bytes specified in \fBoutl*\fR +and does not decode padding bytes (\fB=\fR) to 6 zero bits. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |