Add documentation for EVP_EncodeInit() and similar functions
Reviewed-by: Richard Levitte <levitte@openssl.org>
This commit is contained in:
parent
5d20e98465
commit
fec6d1e868
146
doc/crypto/EVP_EncodeInit.pod
Normal file
146
doc/crypto/EVP_EncodeInit.pod
Normal file
@ -0,0 +1,146 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_num, EVP_EncodeInit,
|
||||
EVP_EncodeUpdate, EVP_EncodeFinal, EVP_EncodeBlock, EVP_DecodeInit,
|
||||
EVP_DecodeUpdate, EVP_DecodeFinal, EVP_DecodeBlock - EVP base 64 encode/decode
|
||||
routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#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_num(EVP_ENCODE_CTX *ctx);
|
||||
void EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
|
||||
void 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);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The EVP encode routines provide a high level interface to base 64 encoding and
|
||||
decoding. Base 64 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 base 64 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.
|
||||
|
||||
EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for
|
||||
the encode/decode functions.
|
||||
|
||||
EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the
|
||||
space allocated to it.
|
||||
|
||||
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 base 64 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.
|
||||
|
||||
EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation.
|
||||
|
||||
EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by
|
||||
B<in>. The output is stored in the buffer B<out> and the number of bytes output
|
||||
is stored in B<*outl>. It is the caller's responsibility to ensure that the
|
||||
buffer at B<out> 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 B<ctx> object and will be processed by a
|
||||
subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the
|
||||
required size of the output buffer add together the value of B<inl> with the
|
||||
amount of unprocessed data held in B<ctx> 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. EVP_EncodeUpdate() may be called
|
||||
repeatedly to process large amounts of input data. In the event of an error
|
||||
EVP_EncodeUpdate() will set B<*outl> to 0.
|
||||
|
||||
EVP_EncodeFinal() must be called at the end of an encoding operation. It will
|
||||
process any partial block of data remaining in the B<ctx> object. The output
|
||||
data will be stored in B<out> and the length of the data written will be stored
|
||||
in B<*outl>. It is the caller's responsibility to ensure that B<out> 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).
|
||||
|
||||
EVP_ENCODE_CTX_num() will return the number of as yet unprocessed bytes still to
|
||||
be encoded or decoded that are pending in the B<ctx> object.
|
||||
|
||||
EVP_EncodeBlock() encodes a full block of input data in B<f> and of length
|
||||
B<dlen> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of
|
||||
output data will be produced. If B<dlen> 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 I<without> the NUL terminator is returned from the function.
|
||||
|
||||
EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation.
|
||||
|
||||
EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer pointed
|
||||
to by B<in>. The output is stored in the buffer B<out> and the number of bytes
|
||||
output is stored in B<*outl>. It is the caller's responsibility to ensure that
|
||||
the buffer at B<out> is sufficiently large to accommodate the output data. This
|
||||
function will attempt to decode as much data as possible in 4 byte chunks. Any
|
||||
whitespace, newline or carriage return characters are ignored. Any partial chunk
|
||||
of unprocessed data (1, 2 or 3 bytes) that remains at the end will be held in
|
||||
the B<ctx> object and processed by a subsequent call to EVP_DecodeUpdate(). If
|
||||
any illegal base 64 characters are encountered or if the base 64 padding
|
||||
character "=" is encountered in the middle of the data then the function 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
|
||||
input data characters processed included the base 64 padding character "=" and
|
||||
therefore no more non-padding character data is expected to be processed. For
|
||||
every 4 valid base 64 bytes processed (ignoring whitespace, carriage returns and
|
||||
line feeds), 3 bytes of binary output data will be produced (or less at the end
|
||||
of the data where the padding character "=" has been used).
|
||||
|
||||
EVP_DecodeFinal() must be called at the end of a decoding operation. If there
|
||||
is any unprocessed data still in B<ctx> then the input data must not have been
|
||||
a multiple of 4 and therefore an error has occurred. The function will return -1
|
||||
in this case. Otherwise the function returns 1 on success.
|
||||
|
||||
EVP_DecodeBlock() will decode the block of B<n> characters of base 64 data
|
||||
contained in B<f> and store the result in B<t>. Any leading whitespace will be
|
||||
trimmed as will any trailing whitespace, newlines, carriage returns or EOF
|
||||
characters. After such trimming the length of the data in B<f> must be divisbile
|
||||
by 4. For every 4 input bytes exactly 3 output bytes will be produced. The
|
||||
output will be padded with 0 bits if necessary to ensure that the output is
|
||||
always 3 bytes for every 4 input bytes. This function will return the length of
|
||||
the data decoded or -1 on error.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
EVP_ENCODE_CTX_new() returns a pointer to the newly allocated EVP_ENCODE_CTX
|
||||
object or NULL on error.
|
||||
|
||||
EVP_ENCODE_CTX_num() returns the number of bytes pending encoding or decoding in
|
||||
B<ctx>.
|
||||
|
||||
EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL
|
||||
terminator.
|
||||
|
||||
EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned
|
||||
then no more non-padding base 64 characters are expected.
|
||||
|
||||
EVP_DecodeFinal() returns -1 on error or 1 on success.
|
||||
|
||||
EVP_DecodeBlock() returns the length of the data decoded or -1 on error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<evp(3)>
|
||||
|
||||
=cut
|
@ -25,6 +25,10 @@ functions. The B<EVP_Digest>I<...> functions provide message digests.
|
||||
The B<EVP_PKEY>I<...> functions provide a high level interface to
|
||||
asymmetric algorithms.
|
||||
|
||||
The L<B<EVP_Encode>I<...>|EVP_EncodeInit(3)> and
|
||||
L<B<EVP_Decode>I<...>|EVP_EncodeInit(3)> functions implement base 64 encoding
|
||||
and decoding.
|
||||
|
||||
Algorithms are loaded with OpenSSL_add_all_algorithms(3).
|
||||
|
||||
All the symmetric algorithms (ciphers), digests and asymmetric algorithms
|
||||
@ -49,6 +53,7 @@ L<EVP_OpenInit(3)|EVP_OpenInit(3)>,
|
||||
L<EVP_SealInit(3)|EVP_SealInit(3)>,
|
||||
L<EVP_SignInit(3)|EVP_SignInit(3)>,
|
||||
L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
|
||||
L<EVP_EncodeInit(3)>,
|
||||
L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>,
|
||||
L<engine(3)|engine(3)>
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user