diff options
Diffstat (limited to 'doc/man3')
37 files changed, 1520 insertions, 252 deletions
diff --git a/doc/man3/BIO_f_base64.pod b/doc/man3/BIO_f_base64.pod index 7d10df933c..67d65da2e2 100644 --- a/doc/man3/BIO_f_base64.pod +++ b/doc/man3/BIO_f_base64.pod @@ -25,11 +25,28 @@ For writing, by default output is divided to lines of length 64 characters and there is a newline at the end of output. This behavior can be changed with B<BIO_FLAGS_BASE64_NO_NL> flag. -For reading, first line should be at most 1024 bytes long including newline -unless the flag B<BIO_FLAGS_BASE64_NO_NL> is set. -Further input lines can be of any length (i.e., newlines may appear anywhere +For reading, the first line of base64 content should be at most 1024 bytes long +including newline unless the flag B<BIO_FLAGS_BASE64_NO_NL> is set. +Subsequent input lines can be of any length (i.e., newlines may appear anywhere in the input) and a newline at the end of input is not needed. +Also when reading, unless the flag B<BIO_FLAGS_BASE64_NO_NL> is set, initial +lines that contain non-base64 content (whitespace is tolerated and ignored) are +skipped, as are lines longer than 1024 bytes. +Decoding starts with the first line that is shorter than 1024 bytes (including +the newline) and consists of only (at least one) valid base64 characters plus +optional whitespace. +Decoding stops when base64 padding is encountered, a soft end-of-input +character (B<->, see L<EVP_DecodeUpdate(3)>) occurs as the first byte after a +complete group of 4 valid base64 characters is decoded, or when an error occurs +(e.g. due to input characters other than valid base64 or whitespace). + +If decoding stops as a result of an error, the first L<BIO_read(3)> that +returns no decoded data will typically return a negative result, rather +than 0 (which indicates normal end of input). +However, a negative return value can also occur if the underlying BIO +supports retries, see L<BIO_should_read(3)> and L<BIO_set_mem_eof_return(3)>. + BIO_flush() on a base64 BIO that is being written through is used to signal that no more data is to be encoded: this is used to flush the final block through the BIO. @@ -64,7 +81,7 @@ to standard output: BIO_free_all(b64); -Read Base64 encoded data from standard input and write the decoded +Read base64 encoded data from standard input and write the decoded data to standard output: BIO *bio, *b64, *bio_out; @@ -83,16 +100,30 @@ data to standard output: =head1 BUGS -On decoding, if the flag B<BIO_FLAGS_BASE64_NO_NL> is not set and -the first 1024 bytes of input do not include a newline character -the first two lines of input are ignored. +The hyphen character (B<->) is treated as an ad hoc soft end-of-input +character when it occurs at the start of a base64 group of 4 encoded +characters. -The ambiguity of EOF in base64 encoded data can cause additional -data following the base64 encoded block to be misinterpreted. +This heuristic works to detect the ends of base64 blocks in PEM or +multi-part MIME, provided there are no stray hyphens in the middle +input. +But it is just a heuristic, and sufficiently unusual input could produce +unexpected results. -There should be some way of specifying a test that the BIO can perform +There should perhaps be some way of specifying a test that the BIO can perform to reliably determine EOF (for example a MIME boundary). +It may be possible for L<BIO_read(3)> to return zero, rather than -1, even if +an error has been detected, more tests are needed to cover all the potential +error paths. + +=head1 SEE ALSO + +L<BIO_read(3)>, +L<BIO_should_read(3)>, +L<BIO_set_mem_eof_return(3)>, +L<EVP_DecodeUpdate(3)>. + =head1 COPYRIGHT Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/BN_add.pod b/doc/man3/BN_add.pod index 35cfdd1495..4d9cb87224 100644 --- a/doc/man3/BN_add.pod +++ b/doc/man3/BN_add.pod @@ -14,9 +14,9 @@ arithmetic operations on BIGNUMs int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + int BN_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); + int BN_sqr(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx); int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, BN_CTX *ctx); @@ -25,25 +25,25 @@ arithmetic operations on BIGNUMs int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + int BN_mod_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + int BN_mod_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + int BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); + int BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - BIGNUM *BN_mod_sqrt(BIGNUM *in, BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); + BIGNUM *BN_mod_sqrt(BIGNUM *in, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); - int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); + int BN_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); - int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + int BN_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx); - int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + int BN_gcd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); =head1 DESCRIPTION diff --git a/doc/man3/BN_set_bit.pod b/doc/man3/BN_set_bit.pod index 349ef9e056..e4d66791e8 100644 --- a/doc/man3/BN_set_bit.pod +++ b/doc/man3/BN_set_bit.pod @@ -33,8 +33,11 @@ error occurs if B<a> is shorter than B<n> bits. BN_is_bit_set() tests if bit B<n> in B<a> is set. BN_mask_bits() truncates B<a> to an B<n> bit number -(C<a&=~((~0)E<lt>E<lt>n)>). An error occurs if B<a> already is -shorter than B<n> bits. +(C<a&=~((~0)E<lt>E<lt>n)>). An error occurs if B<n> is negative. An error is +also returned if the internal representation of B<a> is already shorter than +B<n> bits. The internal representation depends on the platform's word size, and +this error can be safely ignored. Use L<BN_num_bits(3)> to determine the exact +number of bits if needed. BN_lshift() shifts B<a> left by B<n> bits and places the result in B<r> (C<r=a*2^n>). Note that B<n> must be nonnegative. BN_lshift1() shifts diff --git a/doc/man3/CMAC_CTX.pod b/doc/man3/CMAC_CTX.pod new file mode 100644 index 0000000000..fae4fd1516 --- /dev/null +++ b/doc/man3/CMAC_CTX.pod @@ -0,0 +1,114 @@ +=pod + +=head1 NAME + +CMAC_CTX, CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free, +CMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final, +CMAC_resume +- create cipher-based message authentication codes + +=head1 SYNOPSIS + + #include <openssl/cmac.h> + +The following functions have been deprecated since OpenSSL 3.0, and can be +disabled entirely by defining B<OPENSSL_API_COMPAT> with a suitable version +value, see L<openssl_user_macros(7)>. + + typedef struct CMAC_CTX_st CMAC_CTX; + + CMAC_CTX *CMAC_CTX_new(void); + void CMAC_CTX_cleanup(CMAC_CTX *ctx); + void CMAC_CTX_free(CMAC_CTX *ctx); + EVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx); + int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in); + int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen, + const EVP_CIPHER *cipher, ENGINE *impl); + int CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen); + int CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen); + int CMAC_resume(CMAC_CTX *ctx); + +=head1 DESCRIPTION + +The low-level MAC functions documented on this page are deprecated. +Applications should use the new L<EVP_MAC(3)> interface. +Specifically, utilize the following functions for MAC operations: + +=over 4 + +=item L<EVP_MAC_CTX_new(3)> to create a new MAC context. + +=item L<EVP_MAC_CTX_free(3)> to free the MAC context. + +=item L<EVP_MAC_init(3)> to initialize the MAC context. + +=item L<EVP_MAC_update(3)> to update the MAC with data. + +=item L<EVP_MAC_final(3)> to finalize the MAC and retrieve the output. + +=back + +Alternatively, for a single-step MAC computation, use the L<EVP_Q_mac(3)> +function. + +The B<CMAC_CTX> type is a structure used for the provision of CMAC +(Cipher-based Message Authentication Code) operations. + +CMAC_CTX_new() creates a new B<CMAC_CTX> structure and returns a pointer to it. + +CMAC_CTX_cleanup() resets the B<CMAC_CTX> structure, clearing any internal data +but not freeing the structure itself. + +CMAC_CTX_free() frees the B<CMAC_CTX> structure and any associated resources. +If the argument is NULL, no action is taken. + +CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal B<EVP_CIPHER_CTX> +structure within the B<CMAC_CTX>. + +CMAC_CTX_copy() copies the state from one B<CMAC_CTX> structure to another. + +CMAC_Init() initializes the B<CMAC_CTX> structure for a new CMAC calculation +with the specified key, key length, and cipher type. +Optionally, an B<ENGINE> can be provided. + +CMAC_Update() processes data to be included in the CMAC calculation. +This function can be called multiple times to update the context with +additional data. + +CMAC_Final() finalizes the CMAC calculation and retrieves the resulting +MAC value. The output is stored in the provided buffer, and the length is +stored in the variable pointed to by I<poutlen>. To determine the required +buffer size, call with I<out> set to NULL, which stores only the length in +I<poutlen>. Allocate a buffer of this size and call CMAC_Final() again with +the allocated buffer to retrieve the MAC. + +CMAC_resume() resumes a previously finalized CMAC calculation, allowing +additional data to be processed and a new MAC to be generated. + +=head1 RETURN VALUES + +CMAC_CTX_new() returns a pointer to a new B<CMAC_CTX> structure or NULL if +an error occurs. + +CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal +B<EVP_CIPHER_CTX> structure, or NULL if an error occurs. + +CMAC_CTX_copy(), CMAC_Init(), CMAC_Update(), CMAC_Final() and CMAC_resume() +return 1 for success or 0 if an error occurs. + +=head1 HISTORY + +All functions described here were deprecated in OpenSSL 3.0. For replacements, +see L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>, +L<EVP_MAC_update(3)>, and L<EVP_MAC_final(3)>. + +=head1 COPYRIGHT + +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. + +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 +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/CMS_add0_cert.pod b/doc/man3/CMS_add0_cert.pod index c876238fe4..8f61813f6f 100644 --- a/doc/man3/CMS_add0_cert.pod +++ b/doc/man3/CMS_add0_cert.pod @@ -57,8 +57,9 @@ For enveloped data they are added to B<OriginatorInfo>. CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return 1 for success and 0 for failure. -CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs -or NULL if there are none or an error occurs. The only error which will occur +CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs, +which is empty if there are none. They return NULL on error. +Besides out-of-memory, the only error which will occur in practice is if the I<cms> type is invalid. =head1 SEE ALSO diff --git a/doc/man3/CMS_verify.pod b/doc/man3/CMS_verify.pod index bd46a1262c..3f3488b2f6 100644 --- a/doc/man3/CMS_verify.pod +++ b/doc/man3/CMS_verify.pod @@ -26,6 +26,8 @@ B<CMS SignedData> structure contained in a structure of type B<CMS_ContentInfo>. I<cms> points to the B<CMS_ContentInfo> structure to verify. The optional I<certs> parameter refers to a set of certificates in which to search for signing certificates. +It is also used +as a source of untrusted intermediate CA certificates for chain building. I<cms> may contain extra untrusted CA certificates that may be used for chain building as well as CRLs that may be used for certificate validation. I<store> may be NULL or point to diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index aeae8e81e6..ed327480a1 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -17,14 +17,15 @@ EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type, EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags, EVP_MD_CTX_get0_name, EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md, -EVP_MD_CTX_get_type, EVP_MD_CTX_get_size, EVP_MD_CTX_get_block_size, +EVP_MD_CTX_get_type, EVP_MD_CTX_get_size_ex, EVP_MD_CTX_get_block_size, EVP_MD_CTX_get0_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn, EVP_md_null, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj, EVP_MD_CTX_get_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, EVP_MD_do_all_provided, EVP_MD_type, EVP_MD_nid, EVP_MD_name, EVP_MD_pkey_type, EVP_MD_size, -EVP_MD_block_size, EVP_MD_flags, EVP_MD_CTX_size, EVP_MD_CTX_block_size, +EVP_MD_block_size, EVP_MD_flags, EVP_MD_xof, +EVP_MD_CTX_size, EVP_MD_CTX_get_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data - EVP digest routines @@ -85,11 +86,12 @@ EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data int EVP_MD_get_size(const EVP_MD *md); int EVP_MD_get_block_size(const EVP_MD *md); unsigned long EVP_MD_get_flags(const EVP_MD *md); + int EVP_MD_xof(const EVP_MD *md); const EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx); EVP_MD *EVP_MD_CTX_get1_md(EVP_MD_CTX *ctx); const char *EVP_MD_CTX_get0_name(const EVP_MD_CTX *ctx); - int EVP_MD_CTX_get_size(const EVP_MD_CTX *ctx); + int EVP_MD_CTX_get_size_ex(const EVP_MD_CTX *ctx); int EVP_MD_CTX_get_block_size(const EVP_MD_CTX *ctx); int EVP_MD_CTX_get_type(const EVP_MD_CTX *ctx); void *EVP_MD_CTX_get0_md_data(const EVP_MD_CTX *ctx); @@ -114,7 +116,8 @@ EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data #define EVP_MD_size EVP_MD_get_size #define EVP_MD_block_size EVP_MD_get_block_size #define EVP_MD_flags EVP_MD_get_flags - #define EVP_MD_CTX_size EVP_MD_CTX_get_size + #define EVP_MD_CTX_get_size EVP_MD_CTX_get_size_ex + #define EVP_MD_CTX_size EVP_MD_CTX_get_size_ex #define EVP_MD_CTX_block_size EVP_MD_CTX_get_block_size #define EVP_MD_CTX_type EVP_MD_CTX_get_type #define EVP_MD_CTX_pkey_ctx EVP_MD_CTX_get_pkey_ctx @@ -135,11 +138,20 @@ see L<openssl_user_macros(7)>: =head1 DESCRIPTION -The EVP digest routines are a high-level interface to message digests, -and should be used instead of the digest-specific functions. +The EVP digest routines are a high-level interface to message digests, and +Extendable Output Functions (XOF). The B<EVP_MD> type is a structure for digest method implementation. +Each Message digest algorithm (such as SHA256) produces a fixed size output +length which is returned when EVP_DigestFinal_ex() is called. +Extendable Output Functions (XOF) such as SHAKE256 have a variable sized output +length I<outlen> which can be used with either EVP_DigestFinalXOF() or +EVP_DigestSqueeze(). EVP_DigestFinal_ex() may also be used for an XOF, but the +"xoflen" must be set beforehand (See L</PARAMETERS>). +Note that EVP_MD_get_size() and EVP_MD_CTX_get_size_ex() behave differently for +an XOF. + =over 4 =item EVP_MD_fetch() @@ -344,6 +356,12 @@ EVP_sha256() rather than the result of an EVP_MD_fetch()), only cipher names registered with the default library context (see L<OSSL_LIB_CTX(3)>) will be considered. +=item EVP_MD_xof() + +Returns 1 if I<md> is an Extendable-output Function (XOF) otherwise it returns +0. SHAKE128 and SHAKE256 are XOF functions. +It returns 0 for BLAKE2B algorithms. + =item EVP_MD_get0_name(), EVP_MD_CTX_get0_name() @@ -366,11 +384,16 @@ The description is at the discretion of the digest implementation. Returns an B<OSSL_PROVIDER> pointer to the provider that implements the given B<EVP_MD>. -=item EVP_MD_get_size(), -EVP_MD_CTX_get_size() +=item EVP_MD_get_size() Return the size of the message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the hash. +For an XOF this returns 0. + +=item EVP_MD_CTX_get_size_ex(), EVP_MD_CTX_get_size() + +For a normal digest this is the same as EVP_MD_get_size(). +For an XOF this returns the "xoflen" if it has been set, otherwise it returns 0. =item EVP_MD_get_block_size(), EVP_MD_CTX_get_block_size() @@ -482,17 +505,31 @@ I<arg> as argument. See L<OSSL_PARAM(3)> for information about passing parameters. -EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys: +EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params() can be used with the +following OSSL_PARAM keys: =over 4 =item "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer> -Sets the digest length for extendable output functions. +Sets or gets the digest length for extendable output functions. The value should not exceed what can be given using a B<size_t>. -It may be used by BLAKE2B-512, SHAKE-128 and SHAKE-256 to set the +It may be used by SHAKE-128 and SHAKE-256 to set the output length used by EVP_DigestFinal_ex() and EVP_DigestFinal(). +=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer> + +Sets or gets a fixed digest length. +The value should not exceed what can be given using a B<size_t>. +It may be used by BLAKE2B-512 to set the output length used by +EVP_DigestFinal_ex() and EVP_DigestFinal(). + +=back + +EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys: + +=over 4 + =item "pad-type" (B<OSSL_DIGEST_PARAM_PAD_TYPE>) <unsigned integer> Sets the padding type. @@ -532,7 +569,7 @@ an L<OSSL_PARAM(3)> item with the key "micalg" (B<OSSL_DIGEST_PARAM_MICALG>). This control sets the digest length for extendable output functions to I<p1>. Sending this control directly should not be necessary, the use of EVP_DigestFinalXOF() is preferred. -Currently used by SHAKE. +Currently used by SHAKE algorithms. When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with an L<OSSL_PARAM(3)> item with the key "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>). @@ -550,9 +587,13 @@ can be used the manipulate and test these B<EVP_MD_CTX> flags: This flag instructs the digest to optimize for one update only, if possible. -=for comment EVP_MD_CTX_FLAG_CLEANED is internal, don't mention it +=item EVP_MD_CTX_FLAG_CLEANED + +This flag is for internal use only and I<must not> be used in user code. -=for comment EVP_MD_CTX_FLAG_REUSE is internal, don't mention it +=item EVP_MD_CTX_FLAG_REUSE + +This flag is for internal use only and I<must not> be used in user code. =for comment We currently avoid documenting flags that are only bit holder: EVP_MD_CTX_FLAG_NON_FIPS_ALLOW, EVP_MD_CTX_FLAGS_PAD_* @@ -811,6 +852,12 @@ The EVP_MD_CTX_dup() function was added in OpenSSL 3.1. The EVP_DigestSqueeze() function was added in OpenSSL 3.3. +The EVP_MD_CTX_get_size_ex() and EVP_xof() functions were added in OpenSSL 3.4. +The macros EVP_MD_CTX_get_size() and EVP_MD_CTX_size were changed in OpenSSL 3.4 +to be aliases for EVP_MD_CTX_get_size_ex(), previously they were aliases for +EVP_MD_get_size which returned a constant value. This is required for XOF +digests since they do not have a fixed size. + =head1 COPYRIGHT Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/EVP_EncodeInit.pod b/doc/man3/EVP_EncodeInit.pod index 2d6e4e8cbf..94a9a3b345 100644 --- a/doc/man3/EVP_EncodeInit.pod +++ b/doc/man3/EVP_EncodeInit.pod @@ -5,7 +5,7 @@ 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 base 64 encode/decode routines +EVP_DecodeBlock - EVP base64 encode/decode routines =head1 SYNOPSIS @@ -29,10 +29,11 @@ EVP_DecodeBlock - EVP base 64 encode/decode routines =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 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 base 64 encoded data will be produced +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. @@ -44,7 +45,8 @@ EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the space allocated to it. If the argument is NULL, nothing is done. 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 +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 @@ -93,37 +95,62 @@ 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 divisible -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. +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 chunks of up +to 80 base64 characters at a time. +Residual input shorter than the internal chunk size will be buffered in B<ctx> +if its length is not a multiple of 4 (including any padding), to be processed +in future calls to EVP_DecodeUpdate() or EVP_DecodeFinal(). +If the final chunk length is a multiple of 4, it is decoded immediately and +not buffered. + +Any whitespace, newline or carriage return characters are ignored. +For compatibility with B<PEM>, the B<-> (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 B<ctx>, it is up to the +caller to avoid further calls to EVP_DecodeUpdate() after a 0 or negative +(error) return. + +If any invalid base64 characters are encountered or if the base64 padding +character (B<=>) is encountered in the middle of the data then +EVP_DecodeUpdate() 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 (B<=>), or that the next 4 byte group starts with the +soft end-of-input (B<->) character, and therefore no more input data is +expected to be processed. + +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). + +EVP_DecodeFinal() 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. + +EVP_DecodeBlock() will decode the block of B<n> characters of base64 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. +Internal whitespace MUST NOT be present. +After trimming the data in B<f> 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 (B<=>) (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. +EVP_DecodeBlock() will return the length of the data decoded or -1 on error. =head1 RETURN VALUES @@ -139,7 +166,7 @@ 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. +then no more non-padding base64 characters are expected. EVP_DecodeFinal() returns -1 on error or 1 on success. diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index b759f9020d..b38e820598 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -375,9 +375,13 @@ exists. Encrypts I<inl> bytes from the buffer I<in> and writes the encrypted version to I<out>. The pointers I<out> |