TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA
-=head2 Elliptic curve cipher suites.
+=head2 Elliptic curve cipher suites
TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA
and return an error if no recipient can be found: this option should be used
with caution. For a fuller description see L<CMS_decrypt(3)>).
-=head1 CAdES Basic Electronic Signature (CAdES-BES)
+=head1 CADES BASIC ELECTRONIC SIGNATURE (CADES-BES)
A CAdES Basic Electronic Signature (CAdES-BES), as defined in the European Standard ETSI EN 319 122-1 V1.1.1, contains:
=back
-=head1 COMPATIBILITY WITH PKCS#7 format.
+=head1 COMPATIBILITY WITH PKCS#7 FORMAT
The B<smime> utility can only process the older B<PKCS#7> format. The B<cms>
utility supports Cryptographic Message Syntax format. Use of some features
=back
-=head1 OCSP Response verification.
+=head1 OCSP RESPONSE VERIFICATION
OCSP Response follows the rules specified in RFC2560.
PKCS#8 format because the encryption details are included at an ASN1
level whereas the traditional format includes them at a PEM level.
-=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
+=head1 PKCS#5 V1.5 AND PKCS#12 ALGORITHMS
Various algorithms can be used with the B<-v1> command line option,
including PKCS#5 v1.5 and PKCS#12. These are described in more detail
verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for
the B<-pkeyopt> B<digest> option.
-=head1 X25519 and X448 ALGORITHMS
+=head1 X25519 AND X448 ALGORITHMS
The X25519 and X448 algorithms support key derivation only. Currently there are
no additional options.
-=head1 Ed25519 and Ed448 ALGORITHMS
+=head1 ED25519 AND ED448 ALGORITHMS
These algorithms only support signing and verifying. OpenSSL only implements the
"pure" variants of these algorithms so raw data can be passed directly to them
algorithm (zlib compression). B<in> is the content to be compressed.
B<flags> is an optional set of flags.
-=head1 NOTES
-
The only currently supported compression algorithm is zlib using the NID
NID_zlib_compression.
B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
practice and is not supported by SMIME_write_CMS().
-=head1 NOTES
-
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
is a list of recipient certificates. B<in> is the content to be encrypted.
B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
-=head1 NOTES
-
Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this
function.
B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
practice and is not supported by SMIME_write_CMS().
-=head1 NOTES
-
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
=head1 EXAMPLES
+You can find out if OpenSSL was configured with thread support:
+
+ #include <openssl/opensslconf.h>
+ #if defined(OPENSSL_THREADS)
+ /* thread support enabled */
+ #else
+ /* no thread support */
+ #endif
+
This example safely initializes and uses a lock.
#ifdef _WIN32
The simplest solution is to just "leak" the lock in applications and not
repeatedly load/unload shared libraries that allocate locks.
-=head1 NOTES
-
-You can find out if OpenSSL was configured with thread support:
-
- #include <openssl/opensslconf.h>
- #if defined(OPENSSL_THREADS)
- /* thread support enabled */
- #else
- /* no thread support */
- #endif
-
=head1 SEE ALSO
L<crypto(7)>
=back
-=head1 AEAD Interface
+=head1 AEAD INTERFACE
The EVP interface for Authenticated Encryption with Associated Data (AEAD)
modes are subtly altered and several additional I<ctrl> operations are supported
The tag length is often referred to as B<M>. If not set a default value is
used (12 for AES). When decrypting, the tag needs to be set before passing
in data to be decrypted, but as in GCM and OCB mode, it can be set after
-passing additional authenticated data (see L<AEAD Interface>).
+passing additional authenticated data (see L</AEAD INTERFACE>).
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)
BIO_dump(trc_out, bar, sizeof(bar));
} OSSL_TRACE_END(TLS);
-=head1 Simple example
+=head2 Simple example
An example with just a channel and constant prefix / suffix.
B<p12> is a pointer to a PKCS12 structure. B<oldpass> is the existing password
and B<newpass> is the new password.
-=head1 NOTES
-
Each of B<oldpass> and B<newpass> is independently interpreted as a string in
the UTF-8 encoding. If it is not valid UTF-8, it is assumed to be ISO8859-1
instead.
the terminal or command line. Refer to the documentation of
L<UI_OpenSSL(3)>, for example.
+If the PKCS#12 structure does not have a password, then you must use the empty
+string "" for B<oldpass>. Using NULL for B<oldpass> will result in a
+PKCS12_newpass() failure.
+
+If the wrong password is used for B<oldpass> then the function will fail,
+with a MAC verification error. In rare cases the PKCS12 structure does not
+contain a MAC: in this case it will usually fail with a decryption padding
+error.
+
=head1 RETURN VALUES
PKCS12_newpass() returns 1 on success or 0 on failure. Applications can
}
-=head1 NOTES
-
-If the PKCS#12 structure does not have a password, then you must use the empty
-string "" for B<oldpass>. Using NULL for B<oldpass> will result in a
-PKCS12_newpass() failure.
-
-If the wrong password is used for B<oldpass> then the function will fail,
-with a MAC verification error. In rare cases the PKCS12 structure does not
-contain a MAC: in this case it will usually fail with a decryption padding
-error.
-
=head1 BUGS
The password format is a NULL terminated ASCII string which is converted to
is a list of recipient certificates. B<in> is the content to be encrypted.
B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
-=head1 NOTES
-
Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
certificates supplied to this function must all contain RSA public keys, though
they do not have to be signed using the RSA algorithm.
If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output
suitable for streaming I/O: no data is read from the BIO B<in>.
-=head1 NOTES
-
If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
complete and outputting its contents via a function that does not
properly finalize the B<PKCS7> structure will give unpredictable
B<flags> is an optional set of flags.
-=head1 NOTES
-
Any of the following flags (ored together) can be passed in the B<flags>
parameter.
If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
which additional signers and capabilities can be added before finalization.
-=head1 NOTES
-
If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
complete and outputting its contents via a function that does not properly
finalize the B<PKCS7> structure will give unpredictable results.
If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
renegotiation B<always> succeeds.
-=head2 Patched OpenSSL client and unpatched server.
+=head2 Patched OpenSSL client and unpatched server
If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
SSL_set_psk_server_callback() and use that. In this case the handshake digest
will default to SHA-256 for any returned PSK.
-=head1 NOTES
-
A connection established via a TLSv1.3 PSK will appear as if session resumption
has occurred so that L<SSL_session_reused(3)> will return true.
SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
close_notify shutdown alert to the peer.
-=head1 NOTES
-
SSL_shutdown() tries to send the close_notify shutdown alert to the peer.
Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
a currently open session is considered closed and good and will be kept in the
It is not possible to call SSL_write() after calling SSL_shutdown().
The read direction is closed by the peer.
+The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
+If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
+handshake step has been finished or an error occurred.
+
+If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
+when the underlying BIO could not satisfy the needs of SSL_shutdown()
+to continue the handshake. In this case a call to SSL_get_error() with the
+return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_shutdown().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
+to wait for the peer's close_notify alert.
+SSL_shutdown() will return 1 in that case.
+However, it is recommended to wait for it using SSL_read() instead.
+
+SSL_shutdown() can be modified to only set the connection to "shutdown"
+state but not actually send the close_notify alert messages,
+see L<SSL_CTX_set_quiet_shutdown(3)>.
+When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
+and return 1.
+
=head2 First to close the connection
When the application is the first party to send the close_notify
Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.
-=head1 NOTES
-
-The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
-If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
-handshake step has been finished or an error occurred.
-
-If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
-when the underlying BIO could not satisfy the needs of SSL_shutdown()
-to continue the handshake. In this case a call to SSL_get_error() with the
-return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
-B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
-taking appropriate action to satisfy the needs of SSL_shutdown().
-The action depends on the underlying BIO. When using a non-blocking socket,
-nothing is to be done, but select() can be used to check for the required
-condition. When using a buffering BIO, like a BIO pair, data must be written
-into or retrieved out of the BIO before being able to continue.
-
-After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
-to wait for the peer's close_notify alert.
-SSL_shutdown() will return 1 in that case.
-However, it is recommended to wait for it using SSL_read() instead.
-
-SSL_shutdown() can be modified to only set the connection to "shutdown"
-state but not actually send the close_notify alert messages,
-see L<SSL_CTX_set_quiet_shutdown(3)>.
-When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
-and return 1.
-
=head1 RETURN VALUES
The following return values can occur:
The following sections describe each supported extension in detail.
-=head2 Basic Constraints.
+=head2 Basic Constraints
This is a multi valued extension which indicates whether a certificate is
a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
only be used to sign end user certificates and not further CAs.
-=head2 Key Usage.
+=head2 Key Usage
Key usage is a multi valued extension consisting of a list of names of the
permitted key usages.
keyUsage=critical, keyCertSign
-=head2 Extended Key Usage.
+=head2 Extended Key Usage
This extensions consists of a list of usages indicating purposes for which
the certificate public key can be used for,
extendedKeyUsage=serverAuth,clientAuth
-=head2 Subject Key Identifier.
+=head2 Subject Key Identifier
This is really a string extension and can take two possible values. Either
the word B<hash> which will automatically follow the guidelines in RFC3280
subjectKeyIdentifier=hash
-=head2 Authority Key Identifier.
+=head2 Authority Key Identifier
The authority key identifier extension permits two options. keyid and issuer:
both can take the optional value "always".
authorityKeyIdentifier=keyid,issuer
-=head2 Subject Alternative Name.
+=head2 Subject Alternative Name
The subject alternative name extension allows various literal values to be
included in the configuration file. These include B<email> (an email address)
CN=My Name
-=head2 Issuer Alternative Name.
+=head2 Issuer Alternative Name
The issuer alternative name option supports all the literal options of
subject alternative name. It does B<not> support the email:copy option because
issuerAltName = issuer:copy
-=head2 Authority Info Access.
+=head2 Authority Info Access
The authority information access extension gives details about how to access
certain information relating to the CA. Its syntax is accessOID;location
CN=Some Name
-=head2 Certificate Policies.
+=head2 Certificate Policies
This is a I<raw> extension. All the fields of this extension can be set by
using the appropriate syntax.
The following extensions are non standard, Netscape specific and largely
obsolete. Their use in new applications is discouraged.
-=head2 Netscape String extensions.
+=head2 Netscape String extensions
Netscape Comment (B<nsComment>) is a string extension containing a comment
which will be displayed when the certificate is viewed in some browsers.
previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
-=head2 Entropy Input vs. Additional Data
+=head2 Entropy Input and Additional Data
The DRBG distinguishes two different types of random input: I<entropy>,
which comes from a trusted source, and I<additional input>',
The method object that is fetched can then be used with diverse other
functions that use them, for example L<EVP_DigestInit_ex(3)>.
-=head2 Implicit fetch
+=head3 Implicit fetch
I<NOTE: This section is mostly interesting to OpenSSL users.>
my $section = shift;
my $before = shift;
- return
- unless $contents =~ /=head1 $section/ and $contents =~ /=head1 $before/;
- print "$id $section should be placed before $before section\n"
+ return unless $contents =~ /=head1 $section/
+ and $contents =~ /=head1 $before/;
+ print "$id $section should appear before $before section\n"
if $contents =~ /=head1 $before.*=head1 $section/ms;
}
+# Check if a =head1 is duplicated, or a =headX is duplicated within a
+# =head1. Treats =head2 =head3 as equivalent -- it doesn't reset the head3
+# sets if it finds a =head2 -- but that is good enough for now. Also check
+# for proper capitalization, trailing periods, etc.
+sub check_head_style()
+{
+ my $id = shift;
+ my $contents = shift;
+ my %head1;
+ my %subheads;
+
+ foreach my $line ( split /\n+/, $contents ) {
+ next unless $line =~ /^=head/;
+ if ( $line =~ /head1/ ) {
+ print "$id duplicate section $line\n"
+ if defined $head1{$line};
+ $head1{$line} = 1;
+ %subheads = ();
+ } else {
+ print "$id duplicate subsection $line\n"
+ if defined $subheads{$line};
+ $subheads{$line} = 1;
+ }
+ print "$id period in =head\n"
+ if $line =~ /\.[^\w]/ or $line =~ /\.$/;
+ print "$id not all uppercase in =head1\n"
+ if $line =~ /head1.*[a-z]/;
+ print "$id all uppercase in subhead\n"
+ if $line =~ /head[234][ A-Z0-9]+$/;
+ }
+}
+
sub check()
{
my $filename = shift;
}
my $id = "${filename}:1:";
+ &check_head_style($id, $contents);
# Check ordering of some sections in man3
if ( $filename =~ m|man3/| ) {
projects / openssl.git / commitdiff