diff options
author | Matt Caswell <matt@openssl.org> | 2016-04-25 11:54:30 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2016-05-03 11:50:13 +0100 |
commit | 0b3762a342bef77fcd8c2d712eae4860af706b20 (patch) | |
tree | 237b617cb5890c607d88e775e1e96423f0fc18c4 /doc/crypto | |
parent | 3850c2b9d55fb91ea1d9b8228fd8a761d0ba1780 (diff) |
Add documentation for EVP_EncodeInit() and similar functions
Reviewed-by: Richard Levitte <levitte@openssl.org>
Diffstat (limited to 'doc/crypto')
-rw-r--r-- | doc/crypto/EVP_EncodeInit.pod | 146 | ||||
-rw-r--r-- | doc/crypto/evp.pod | 5 |
2 files changed, 151 insertions, 0 deletions
diff --git a/doc/crypto/EVP_EncodeInit.pod b/doc/crypto/EVP_EncodeInit.pod new file mode 100644 index 0000000000..bc35acfc42 --- /dev/null +++ b/doc/crypto/EVP_EncodeInit.pod @@ -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 diff --git a/doc/crypto/evp.pod b/doc/crypto/evp.pod index 29fab9fd51..303cd95a70 100644 --- a/doc/crypto/evp.pod +++ b/doc/crypto/evp.pod @@ -61,6 +61,10 @@ based encryption. Careful selection of the parameters will provide a PKCS#5 PBKD implementation. However, new applications should not typically use this (preferring, for example, PBKDF2 from PCKS#5). +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 L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>. All the symmetric algorithms (ciphers), digests and asymmetric algorithms @@ -86,6 +90,7 @@ L<EVP_SealInit(3)|EVP_SealInit(3)>, L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, L<EVP_SignInit(3)|EVP_SignInit(3)>, L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, +L<EVP_EncodeInit(3)>, L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>, L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>, |