=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_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
-=head1 EXAMPLE
+=head1 RETURN VALUES
+
+BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
+
+BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
+BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
+success or a value which is less than or equal to 0 if an error occurred.
+
+BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
+a valid B<BIO> structure on success or B<NULL> if an error occurred.
+
+BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
+
+BIO_do_handshake() returns 1 if the connection was established successfully.
+A zero or negative value is returned if the connection could not be established.
+
+=head1 EXAMPLES
-This SSL/TLS client example, attempts to retrieve a page from an
+This SSL/TLS client example attempts to retrieve a page from an
SSL/TLS web server. The I/O routines are identical to those of the
unencrypted example in L<BIO_s_connect(3)>.
BIO_flush(sbio);
BIO_free_all(sbio);
-=head1 RETURN VALUES
-
-BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
-
-BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
-BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
-success or a value which is less than or equal to 0 if an error occurred.
-
-BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
-a valid B<BIO> structure on success or B<NULL> if an error occurred.
-
-BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
-
-BIO_do_handshake() returns 1 if the connection was established successfully.
-A zero or negative value is returned if the connection could not be established.
-
=head1 HISTORY
In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
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
find out, how many bytes must be written into the buffer before the
SSL_operation() can successfully be continued.
-=head1 WARNING
+=head1 WARNINGS
As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
condition, but there is still data in the write buffer. An application must
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":
There should be an option to set the maximum size of a memory BIO.
-=head1 EXAMPLE
+=head1 RETURN VALUES
+
+BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
+
+BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
+return 1 on success or a value which is less than or equal to 0 if an error occurred.
+
+BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
+
+=head1 EXAMPLES
Create a memory BIO and write some data to it:
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
BIO_free(mem);
-=head1 RETURN VALUES
-
-BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
-
-BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
-return 1 on success or a value which is less than or equal to 0 if an error occurred.
-
-BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
=head1 COPYRIGHT
=back
-=head1 EXAMPLE
-
-The BIO_debug_callback() function is a good example, its source is
-in crypto/bio/bio_cb.c
-
=head1 RETURN VALUES
BIO_get_callback_ex() and BIO_get_callback() return the callback function
BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
operations.
+=head1 EXAMPLES
+
+The BIO_debug_callback() function is a good example, its source is
+in crypto/bio/bio_cb.c
+
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)>.
-=head1 WARNING
+=head1 WARNINGS
The inputs must be reduced modulo B<m>, otherwise the result will be
outside the expected range.
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.
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):
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
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>:
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.
recovered data, -1 on error. Error codes can be obtained by calling
L<ERR_get_error(3)>.
-=head1 WARNING
+=head1 WARNINGS
The result of RSA_padding_check_PKCS1_type_2() is a very sensitive
information which can potentially be used to mount a Bleichenbacher
On error, -1 is returned; the error codes can be
obtained by L<ERR_get_error(3)>.
-=head1 WARNING
+=head1 WARNINGS
Decryption failures in the RSA_PKCS1_PADDING mode leak information
which can potentially be used to mount a Bleichenbacher padding oracle
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.
using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies
them to suit its needs: for example to add a hostname check.
-=head1 EXAMPLE
-
-Check hostname matches "www.foo.com" in peer certificate:
-
- X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
- X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
-
=head1 RETURN VALUES
SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
for failure.
+=head1 EXAMPLES
+
+Check hostname matches "www.foo.com" in peer certificate:
+
+ X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
+ X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
+
=head1 SEE ALSO
L<X509_VERIFY_PARAM_set_flags(3)>
SSL_library_init() must be called before any other action takes place.
SSL_library_init() is not reentrant.
-=head1 WARNING
+=head1 WARNINGS
SSL_library_init() adds ciphers and digests used directly and indirectly by
SSL/TLS.
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
a new buffer (with the already sent bytes removed) must be started. A partial
write is performed with the size of a message block, which is 16kB.
-=head1 WARNING
+=head1 WARNINGS
When a write function call has to be repeated because L<SSL_get_error(3)>
returned B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
L<X509_STORE_set_verify(3)> for more information.
-=head1 WARNING
+=head1 WARNINGS
In general a verification callback should B<NOT> unconditionally return 1 in
all circumstances because this will allow verification to succeed no matter
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>:
basicConstraints=critical,DER:00:01:02:03
-=head1 WARNING
+=head1 WARNINGS
There is no guarantee that a specific implementation will process a given
extension. It may therefore be sometimes possible to use certificates for
The DER and ASN1 options should be used with caution. It is possible to create
totally invalid extensions if they are not used carefully.
-
=head1 NOTES
If an extension is multi-value and a field value must contain a comma the long
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:
The output length of an scrypt key derivation is specified via the
length parameter to the L<EVP_PKEY_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives a 64-byte long test vector using scrypt using the password
"password", salt "NaCl" and N = 1024, r = 8, p = 16.
}
}
-# Check if SECTION is located before BEFORE
+# Check if SECTION ($3) is located before BEFORE ($4)
sub check_section_location()
{
- my $filename = shift;
+ my $id = shift;
my $contents = shift;
my $section = shift;
my $before = shift;
- return unless $contents =~ /=head1 $section/
- and $contents =~ /=head1 $before/;
- print "$filename: $section should be placed before $before section\n"
+ return
+ unless $contents =~ /=head1 $section/ and $contents =~ /=head1 $before/;
+ print "$id $section should be placed before $before section\n"
if $contents =~ /=head1 $before.*=head1 $section/ms;
}
close POD;
}
- # Check if EXAMPLES is located after RETURN VALUES section.
- &check_section_location($filename, $contents, "RETURN VALUES", "EXAMPLES") if $filename =~ m|man3/|;
- # Check if HISTORY is located after SEE ALSO
- &check_section_location($filename, $contents, "SEE ALSO", "HISTORY") if $filename =~ m|man3/|;
- # Check if SEE ALSO is located after EXAMPLES
- &check_section_location($filename, $contents, "EXAMPLES", "SEE ALSO") if $filename =~ m|man3/|;
-
my $id = "${filename}:1:";
+ # Check ordering of some sections in man3
+ if ( $filename =~ m|man3/| ) {
+ &check_section_location($id, $contents, "RETURN VALUES", "EXAMPLES");
+ &check_section_location($id, $contents, "SEE ALSO", "HISTORY");
+ &check_section_location($id, $contents, "EXAMPLES", "SEE ALSO");
+ }
+
&name_synopsis($id, $filename, $contents)
unless $contents =~ /=for comment generic/
or $filename =~ m@man[157]/@;
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 WARNING not WARNINGS section.\n"
+ if $contents =~ /=head1 WARNING[^S]/;
print "$id missing copyright\n"
if $contents !~ /Copyright .* The OpenSSL Project Authors/;
print "$id copyright not last\n"
projects / oweals / openssl.git / commitdiff