These functions allow an B<ASN1_STRING> structure to be manipulated.
-ASN1_STRING_length() returns the length of the content of I<x>.
+ASN1_STRING_length() returns the length of the content of I<x>. I<x> B<MUST NOT> be NULL.
ASN1_STRING_get0_data() returns an internal pointer to the data of I<x>.
Since this is an internal pointer it should B<not> be freed or
-modified in any way.
+modified in any way. I<x> B<MUST NOT> be NULL.
ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the
returned value is not constant. This function is deprecated:
with the correct B<index> value.
TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
-an offset into the opaque exdata part of the TYPE object.
+an offset into the opaque exdata part of the TYPE object. I<d> B<MUST NOT> be NULL.
TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with
-an offset into the opaque exdata part of the TYPE object.
+an offset into the opaque exdata part of the TYPE object. I<d> B<MUST NOT> be NULL.
For compatibility with previous releases, the exdata index of zero is
reserved for "application data." There are two convenience functions for
The BIO_new_ex() function returns a new BIO using method B<type> associated with
the library context I<libctx> (see OSSL_LIB_CTX(3)). The library context may be
-NULL to indicate the default library context.
+NULL to indicate the default library context. I<type> B<MUST NOT> be NULL.
The BIO_new() is the same as BIO_new_ex() except the default library context is
always used.
BN_bn2bin() converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of
-memory.
+memory. B<a> and B<to> B<MUST NOT> be NULL.
BN_bn2binpad() also converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<tolen> indicates the length of the output buffer
BN_bin2bn() converts the positive integer in big-endian form of length
B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is
-NULL, a new B<BIGNUM> is created.
+NULL, a new B<BIGNUM> is created. B<s> B<MUST NOT> be NULL.
BN_signed_bin2bn() converts the integer in big-endian signed 2's complement
form of length B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If
ERR_error_string_n() is a variant of ERR_error_string() that writes
at most I<len> characters (including the terminating 0)
and truncates the string if necessary.
-For ERR_error_string_n(), I<buf> may not be B<NULL>.
+For ERR_error_string_n(), I<buf> B<MUST NOT> be NULL.
The string will have the following format:
Sets up digest context I<ctx> to use a digest I<type>.
I<type> is typically supplied by a function such as EVP_sha1(), or a
-value explicitly fetched with EVP_MD_fetch().
+value explicitly fetched with EVP_MD_fetch(). I<ctx> B<MUST NOT> be NULL.
The parameters B<params> are set on the context after initialisation.
allows changing the digest size and it is set to a larger value by the
application. After calling EVP_DigestFinal_ex() no additional calls to
EVP_DigestUpdate() can be made, but EVP_DigestInit_ex2() can be called to
-initialize a new digest operation.
+initialize a new digest operation. I<ctx> B<MUST NOT> be NULL.
=item EVP_DigestFinalXOF()
}
mdctx = EVP_MD_CTX_new();
+ if (mdctx == NULL) {
+ printf("Message digest create failed.\n");
+ exit(1);
+ }
if (!EVP_DigestInit_ex2(mdctx, md, NULL)) {
printf("Message digest initialization failed.\n");
EVP_MD_CTX_free(mdctx);
EVP_DigestSignUpdate() hashes I<cnt> bytes of data at I<d> into the
signature context I<ctx>. This function can be called several times on the
-same I<ctx> to include additional data.
+same I<ctx> to include additional data. I<ctx> B<MUST NOT> be NULL.
Unless I<sig> is NULL EVP_DigestSignFinal() signs the data in I<ctx>
and places the signature in I<sig>.
=item EVP_EncryptInit_ex2()
-Sets up cipher context I<ctx> for encryption with cipher I<type>. I<type> is
-typically supplied by calling EVP_CIPHER_fetch(). I<type> may also be set
+Sets up cipher context I<ctx> for encryption with cipher I<type>. I<ctx> B<MUST NOT> be NULL.
+I<type> is typically supplied by calling EVP_CIPHER_fetch(). I<type> may also be set
using legacy functions such as EVP_aes_256_cbc(), but this is not recommended
for new applications. I<key> is the symmetric key to use and I<iv> is the IV to
use (if necessary), the actual number of bytes used for the key and IV depends
case the encryption will be done in-place. However, in-place encryption is
guaranteed to work only if the encryption context (I<ctx>) has processed data in
multiples of the block size. If the context contains an incomplete data block
-from previous operations, in-place encryption will fail.
+from previous operations, in-place encryption will fail. I<ctx> B<MUST NOT> be NULL.
If I<out> and I<in> point to different locations, the two buffers must be
disjoint, otherwise the operation might fail or the outcome might be undefined.
identical to the encryption operations except that if padding is enabled the
decrypted data buffer I<out> passed to EVP_DecryptUpdate() should have
sufficient room for (I<inl> + cipher_block_size) bytes unless the cipher block
-size is 1 in which case I<inl> bytes is sufficient.
+size is 1 in which case I<inl> bytes is sufficient. I<ctx> B<MUST NOT> be NULL.
=item EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and
EVP_CipherFinal_ex()
are padded using standard block padding and the padding is checked and removed
when decrypting. If the I<pad> parameter is zero then no padding is
performed, the total amount of data encrypted or decrypted must then
-be a multiple of the block size or an error will occur.
+be a multiple of the block size or an error will occur. I<x> B<MUST NOT> be NULL.
=item EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length()
Return the name of the passed cipher or context. For fetched ciphers with
multiple names, only one of them is returned. See also EVP_CIPHER_names_do_all().
+I<cipher> B<MUST NOT> be NULL.
=item EVP_CIPHER_names_do_all()
for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>.
MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and
-MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure.
+MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure. The parameter B<MUST NOT> be NULL.
Applications should use the higher level functions
L<EVP_DigestInit(3)>
The PEM functions have many common arguments.
The I<bp> BIO parameter (if present) specifies the BIO to read from
-or write to.
+or write to. The I<bp> BIO parameter B<MUST NOT> be NULL.
The I<fp> FILE parameter (if present) specifies the FILE pointer to
read from or write to.
=head1 DESCRIPTION
RAND_bytes() generates B<num> random bytes using a cryptographically
-secure pseudo random generator (CSPRNG) and stores them in B<buf>.
+secure pseudo random generator (CSPRNG) and stores them in B<buf>. B<buf> B<MUST NOT> be NULL.
RAND_priv_bytes() has the same semantics as RAND_bytes(). It is intended to
be used for generating values that should remain private. If using the
SSL_CTX_load_verify_file(), SSL_CTX_load_verify_store() specifies the
locations for B<ctx>, at which CA certificates for verification purposes
are located. The certificates available via B<CAfile>, B<CApath> and
-B<CAstore> are trusted.
+B<CAstore> are trusted. B<ctx> B<MUST NOT> be NULL
Details of the certificate verification and chain checking process are
described in L<openssl-verification-options(1)/Certification Path Validation>.
OpenSSL directory.
Alternatively the B<SSL_CERT_FILE> environment variable can be defined to
override this location.
+B<ctx> B<MUST NOT> be NULL.
SSL_CTX_set_default_verify_dir() is similar to
SSL_CTX_set_default_verify_paths() except that just the default directory is
If another X509_STORE object is currently set in B<ctx>, it will be X509_STORE_free()ed.
SSL_CTX_get_cert_store() returns a pointer to the current certificate
-verification storage.
+verification storage. B<ctx> B<MUST NOT> be NULL.
=head1 NOTES
for B<ctx> using the control string B<str>. The format of the string is described
in L<openssl-ciphers(1)>. The list of ciphers is inherited by all
B<ssl> objects created from B<ctx>. This function does not impact TLSv1.3
-ciphersuites. Use SSL_CTX_set_ciphersuites() to configure those.
+ciphersuites. Use SSL_CTX_set_ciphersuites() to configure those. B<ctx> B<MUST NOT> be NULL.
SSL_set_cipher_list() sets the list of ciphers (TLSv1.2 and below) only for
B<ssl>.
SSL_set_info_callback() sets the B<callback> function, that can be used to
obtain state information for B<ssl> during connection setup and use.
When B<callback> is NULL, the callback setting currently valid for
-B<ctx> is used.
+B<ctx> is used. B<ssl> B<MUST NOT> be NULL.
SSL_CTX_get_info_callback() returns a pointer to the currently set information
callback function for B<ctx>.
=head1 DESCRIPTION
SSL_CTX_set_options() adds the options set via bit-mask in B<options> to B<ctx>.
+B<ctx> B<MUST NOT> be NULL.
Options already set before are not cleared!
SSL_set_options() adds the options set via bit-mask in B<options> to B<ssl>.
SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
specifies the B<verify_callback> function to be used. If no callback function
-shall be specified, the NULL pointer can be used for B<verify_callback>.
+shall be specified, the NULL pointer can be used for B<verify_callback>. B<ctx> B<MUST NOT> be NULL.
SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
specifies the B<verify_callback> function to be used. If no callback function
ending at the highest level (root) CA. SSL_use_certificate_chain_file() is
similar except it loads the certificate chain into B<ssl>.
-SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>.
+SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>. B<ctx> B<MUST NOT> be NULL.
SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA
to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>;
SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>.
SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in
B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found
in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private
-RSA key found to B<ssl>.
+RSA key found to B<ssl>. B<ctx> B<MUST NOT> be NULL.
SSL_CTX_check_private_key() checks the consistency of a private key with
the corresponding certificate loaded into B<ctx>. If more than one
SSL_connect() initiates the TLS/SSL handshake with a server. The communication
channel must already have been set and assigned to the B<ssl> by setting an
-underlying B<BIO>.
+underlying B<BIO>. B<ssl> B<MUST NOT> be NULL.
=head1 NOTES
SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing
the description of the actually used cipher of a connection established with
-the B<ssl> object.
+the B<ssl> object. B<ssl> B<MUST NOT> be NULL.
See L<SSL_CIPHER_get_name(3)> for more details.
SSL_get_cipher_name() obtains the
=head1 DESCRIPTION
SSL_get_verify_result() returns the result of the verification of the
-X509 certificate presented by the peer, if any.
+X509 certificate presented by the peer, if any. I<ssl> B<MUST NOT> be NULL.
=head1 NOTES
Note that in some circumstances (such as when early data is being transferred)
SSL_in_init(), SSL_in_before() and SSL_is_init_finished() can all return 0.
+B<s> B<MUST NOT> be NULL.
+
SSL_in_connect_init() returns 1 if B<s> is acting as a client and SSL_in_init()
would return 1, or 0 otherwise.
=head1 DESCRIPTION
-SSL_shutdown() shuts down an active connection represented by an SSL object.
+SSL_shutdown() shuts down an active connection represented by an SSL object. I<ssl> B<MUST NOT> be NULL.
SSL_shutdown_ex() is an extended version of SSL_shutdown(). If non-NULL, I<args>
must point to a B<SSL_SHUTDOWN_EX_ARGS> structure and I<args_len> must be set to
=head1 DESCRIPTION
-SSL_want() returns state information for the SSL object B<ssl>.
+SSL_want() returns state information for the SSL object B<ssl>. B<ssl> B<MUST NOT> be NULL.
The other SSL_want_*() calls are shortcuts for the possible states returned
by SSL_want().
using L<X509_verify_cert(3)> or L<X509_STORE_CTX_verify(3)> has indicated
an error or in a verification callback to determine the nature of an error.
-X509_STORE_CTX_get_error() returns the error code of I<ctx>.
+X509_STORE_CTX_get_error() returns the error code of I<ctx>. I<ctx> B<MUST NOT> be NULL.
See the L</ERROR CODES> section for a full description of all error codes.
It may return a code != X509_V_OK even if X509_verify_cert() did not indicate
an error, likely because a verification callback function has waived the error.
X509_STORE_CTX_set_error() sets the error code of I<ctx> to I<s>. For example
it might be used in a verification callback to set an error based on additional
-checks.
+checks. I<ctx> B<MUST NOT> be NULL.
X509_STORE_CTX_get_error_depth() returns the I<depth> of the error. This is a
nonnegative integer representing where in the certificate chain the error
occurred. If it is zero it occurred in the end entity certificate, one if
it is the certificate which signed the end entity certificate and so on.
+I<ctx> B<MUST NOT> be NULL.
X509_STORE_CTX_set_error_depth() sets the error I<depth>.
This can be used in combination with X509_STORE_CTX_set_error() to set the
X509_STORE_set_trust(), and X509_STORE_set1_param() set the default values
for the corresponding values used in certificate chain validation. Their
behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual
-pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>.
+pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>. The B<X509_STORE> B<MUST NOT> be NULL.
X509_STORE_add_lookup() finds or creates a L<X509_LOOKUP(3)> with the
L<X509_LOOKUP_METHOD(3)> I<meth> and adds it to the B<X509_STORE>
X509_get0_notBefore() and X509_get0_notAfter() return the B<notBefore>
and B<notAfter> fields of certificate I<x> respectively. The value
returned is an internal pointer which must not be freed up after
-the call.
+the call. I<x> B<MUST NOT> be NULL.
X509_getm_notBefore() and X509_getm_notAfter() are similar to
X509_get0_notBefore() and X509_get0_notAfter() except they return
using the default library context and default property query.
X509_get_subject_name() returns the subject name of certificate I<x>. The
-returned value is an internal pointer which B<MUST NOT> be freed.
+returned value is an internal pointer which B<MUST NOT> be freed. I<x> B<MUST NOT> be NULL.
X509_set_subject_name() sets the issuer name of certificate I<x> to
I<name>. The I<name> parameter is copied internally and should be freed
projects / thirdparty / openssl.git / commitdiff
