And update find-doc-nits to complain if "=head1 EXAMPLE" is found.
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9602)
=back
-=head1 EXAMPLE
+=head1 EXAMPLES
To list all the commands available to a dynamic engine:
None.
-=head1 EXAMPLE
+=head1 EXAMPLES
The error code:
=back
-=head1 EXAMPLE
+=head1 EXAMPLES
Print out text version of parameters:
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
-=head1 EXAMPLE
+=head1 EXAMPLES
The following example demonstrates how to use most of the core async APIs:
BIO_method_type() returns the type of the BIO B<b>.
-=head1 EXAMPLE
+=head1 EXAMPLES
Traverse a chain looking for digest BIOs:
BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
-=head1 EXAMPLE
+=head1 EXAMPLES
Create a memory BIO:
BIO_new_accept() returns a BIO or NULL on error.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
[XXXXX: More return values need to be added here]
-=head1 EXAMPLE
+=head1 EXAMPLES
The BIO pair can be used to have full control over the network access of an
application. The application can call select() on the socket as required
BIO_do_connect() returns 1 if the connection was successfully
established and 0 or -1 if the connection failed.
-=head1 EXAMPLE
+=head1 EXAMPLES
This is example connects to a webserver on the local host and attempts
to retrieve a page and copy the result to standard output.
BIO_new_fd() returns the newly allocated BIO or NULL is an error
occurred.
-=head1 EXAMPLE
+=head1 EXAMPLES
This is a file descriptor BIO version of "Hello World":
BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
operations.
-=head1 EXAMPLE
+=head1 EXAMPLES
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
application developer's responsibility to include windows.h prior to
crypto.h where use of CRYPTO_THREAD_* types and functions is required.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example safely initializes and uses a lock.
EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration
or control.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example digests the data "Test Message\n" and "Hello World\n", using the
digest name passed on the command line.
EVP_MAC_do_all_ex() returns nothing at all.
-=head1 EXAMPLE
+=head1 EXAMPLES
#include <stdlib.h>
#include <stdio.h>
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret",
salt value "salt" and info value "label":
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret"
and seed value "seed":
or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
-=head1 EXAMPLE
+=head1 EXAMPLES
Decrypt data using OAEP (for RSA keys):
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
-=head1 EXAMPLE
+=head1 EXAMPLES
Derive shared secret (for example DH or EC keys):
or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
-=head1 EXAMPLE
+=head1 EXAMPLES
Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or
L<d2i_X509(3)> for means to load a public key. You may also simply
or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
-=head1 EXAMPLE
+=head1 EXAMPLES
Sign data using RSA with PKCS#1 padding and SHA256 digest:
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
-=head1 EXAMPLE
+=head1 EXAMPLES
Verify signature using PKCS#1 and SHA256 digest:
and 0 or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
-=head1 EXAMPLE
+=head1 EXAMPLES
Recover digest originally signed using PKCS#1 and SHA256 digest:
OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by
OCSP responders.
-=head1 EXAMPLE
+=head1 EXAMPLES
Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer
B<issuer>:
OSSL_CMP_ITAV_push0_stack_item() returns 1 on success, 0 on error.
-=head1 EXAMPLE
+=head1 EXAMPLES
The following code creates and sets a structure representing a generic
InfoTypeAndValue sequence, using an OID created from text as type, and an
OSSL_CRMF_pbmp_new() returns a new and initialized OSSL_CRMF_PBMPARAMETER
structure, or NULL on error.
-=head1 EXAMPLE
+=head1 EXAMPLES
OSSL_CRMF_PBMPARAMETER *pbm = NULL;
unsigned char *msg = "Hello";
The I<data_size> attribute can be zero, meaning that the parameter it
describes expects arbitrary length data.
-=head1 EXAMPLE
+=head1 EXAMPLES
Code that looked like this:
PKCS12_newpass() returns 1 on success or 0 on failure. Applications can
retrieve the most recent error from PKCS12_newpass() with ERR_get_error().
-=head1 EXAMPLE
+=head1 EXAMPLES
This example loads a PKCS#12 file, changes its password and writes out
the result to a new file.
SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error
occurred.
-=head1 EXAMPLE
+=head1 EXAMPLES
If the file "config.cnf" contains the following:
SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect
before they were called.
-=head1 EXAMPLE
+=head1 EXAMPLES
Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
DNSSEC-validated TLSA records.
SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
for failure.
-=head1 EXAMPLE
+=head1 EXAMPLES
Check hostname matches "www.foo.com" in peer certificate:
matched. Otherwise, it returns the matched peername. To determine
whether verification succeeded call L<SSL_get_verify_result(3)>.
-=head1 EXAMPLE
+=head1 EXAMPLES
Suppose "smtp.example.com" is the MX host of the domain "example.com".
The calls below will arrange to match either the MX hostname or the
corresponding B<X509_STORE> structure. No attempt is made to download
CRLs from the CRL distribution points extension.
-=head1 EXAMPLE
+=head1 EXAMPLES
Enable CRL checking when performing certificate verification during SSL
connections associated with an B<SSL_CTX> structure B<ctx>:
For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
after setting the mode and digest on the C<EVP_KDF_CTX>.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret",
salt value "salt" and info value "label":
The output length of an scrypt key derivation is specified via the
B<keylen> parameter to the L<EVP_KDF_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives a 64-byte long test vector using scrypt with the password
"password", salt "NaCl" and N = 1024, r = 8, p = 16.
The output length of an SSKDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
and fixedinfo value "label":
EVP_KDF_CTX_free(kctx);
-=head1 EXAMPLE
-
This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
fixedinfo value "label" and salt "salt":
EVP_KDF_CTX_free(kctx);
-=head1 EXAMPLE
-
This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
allocate a buffer of the desired length, and pass that buffer to the
L<EVP_KDF_derive(3)> function along with the desired length.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
"xcghash" and "session_id" values:
The output length of the PRF is specified by the C<keylen> parameter to the
EVP_KDF_derive() function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret"
and seed value "seed":
The output length of an X942KDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 24 bytes, with the secret key "secret" and a random user
keying material:
The output length of an X963KDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 10 bytes, with the secret key "secret" and sharedinfo
value "label":
Valid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is
specified, then both Ed25519 and Ed448 are benchmarked.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example generates an B<ED25519> private key and writes it to standard
output in PEM format:
And normally there is no need to pass a B<pctx> parameter to EVP_DigestSignInit()
or EVP_DigestVerifyInit() in such a scenario.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example demonstrates the calling sequence for using an B<EVP_PKEY> to verify
a message with the SM2 signature algorithm and the SM3 hash algorithm:
L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
-=head1 EXAMPLE
+=head1 EXAMPLES
This example generates an B<X25519> private key and writes it to standard
output in PEM format:
a source/sink BIO is normally called BIO_s_*() and a filter BIO
BIO_f_*();
-=head1 EXAMPLE
+=head1 EXAMPLES
Create a memory BIO:
# Check ordering of some sections in man3
if ( $filename =~ m|man3/| ) {
- &check_section_location($id, $contents, "RETURN VALUES", "EXAMPLE");
+ &check_section_location($id, $contents, "RETURN VALUES", "EXAMPLES");
&check_section_location($id, $contents, "SEE ALSO", "HISTORY");
- &check_section_location($id, $contents, "EXAMPLE", "SEE ALSO");
+ &check_section_location($id, $contents, "EXAMPLES", "SEE ALSO");
}
&name_synopsis($id, $filename, $contents)
if $contents !~ /=cut\n$/;
print "$id more than one cut line.\n"
if $contents =~ /=cut.*=cut/ms;
+ print "$id EXAMPLE not EXAMPLES section.\n"
+ if $contents =~ /=head1 EXAMPLE[^S]/;
print "$id missing copyright\n"
if $contents !~ /Copyright .* The OpenSSL Project Authors/;
print "$id copyright not last\n"
projects / oweals / openssl.git / commitdiff