From 22f89c8c27130dce389c2cba215b4cdd0deadd22 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 11 Nov 2015 21:15:15 +0000 Subject: Convert five more manuals from POD to mdoc. I found drafts of these in my tree, probably originally from Max Fillinger, that just needed minor polishing. --- src/lib/libcrypto/man/CONF_modules_free.3 | 56 ++++ src/lib/libcrypto/man/CONF_modules_load_file.3 | 82 ++++++ src/lib/libcrypto/man/CRYPTO_set_ex_data.3 | 70 +++++ .../libcrypto/man/CRYPTO_set_locking_callback.3 | 321 +++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 10 +- src/lib/libcrypto/man/crypto.3 | 104 +++++++ .../libssl/src/doc/crypto/CONF_modules_free.pod | 47 --- .../src/doc/crypto/CONF_modules_load_file.pod | 60 ---- .../libssl/src/doc/crypto/CRYPTO_set_ex_data.pod | 56 ---- .../src/doc/crypto/CRYPTO_set_locking_callback.pod | 210 -------------- src/lib/libssl/src/doc/crypto/crypto.pod | 85 ------ 11 files changed, 638 insertions(+), 463 deletions(-) create mode 100644 src/lib/libcrypto/man/CONF_modules_free.3 create mode 100644 src/lib/libcrypto/man/CONF_modules_load_file.3 create mode 100644 src/lib/libcrypto/man/CRYPTO_set_ex_data.3 create mode 100644 src/lib/libcrypto/man/CRYPTO_set_locking_callback.3 create mode 100644 src/lib/libcrypto/man/crypto.3 delete mode 100644 src/lib/libssl/src/doc/crypto/CONF_modules_free.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CONF_modules_load_file.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CRYPTO_set_ex_data.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CRYPTO_set_locking_callback.pod delete mode 100644 src/lib/libssl/src/doc/crypto/crypto.pod (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/CONF_modules_free.3 b/src/lib/libcrypto/man/CONF_modules_free.3 new file mode 100644 index 0000000000..b09989d664 --- /dev/null +++ b/src/lib/libcrypto/man/CONF_modules_free.3 @@ -0,0 +1,56 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CONF_MODULES_FREE 3 +.Os +.Sh NAME +.Nm CONF_modules_free , +.Nm CONF_modules_finish , +.Nm CONF_modules_unload +.Nd OpenSSL configuration cleanup functions +.Sh SYNOPSIS +.In openssl/conf.h +.Ft void +.Fo CONF_modules_free +.Fa void +.Fc +.Ft void +.Fo CONF_modules_finish +.Fa void +.Fc +.Ft void +.Fo CONF_modules_unload +.Fa "int all" +.Fc +.Sh DESCRIPTION +.Fn CONF_modules_free +closes down and frees up all memory allocated by all configuration +modules. +.Pp +.Fn CONF_modules_finish +calls the configuration +.Sy finish +handler of each configuration module to free up any configuration +that module may have performed. +.Pp +.Fn CONF_modules_unload +finishes and unloads configuration modules. +If +.Fa all +is set to 0, only modules loaded from DSOs will be unloaded. +If +.Fa all +is 1, all modules, including builtin modules, will be unloaded. +.Sh NOTES +Normally applications will only call +.Fn CONF_modules_free +at application to tidy up any configuration performed. +.Sh RETURN VALUE +None of the functions return a value. +.Sh SEE ALSO +.Xr CONF_modules_load_file 3 , +.Xr OPENSSL_config 3 +.Sh HISTORY +.Fn CONF_modules_free , +.Fn CONF_modules_unload , +and +.Fn CONF_modules_finish +first appeared in OpenSSL 0.9.7. diff --git a/src/lib/libcrypto/man/CONF_modules_load_file.3 b/src/lib/libcrypto/man/CONF_modules_load_file.3 new file mode 100644 index 0000000000..b5de94411d --- /dev/null +++ b/src/lib/libcrypto/man/CONF_modules_load_file.3 @@ -0,0 +1,82 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CONF_MODULES_LOAD_FILE 3 +.Os +.Sh NAME +.Nm CONF_modules_load_file , +.Nm CONF_modules_load +.Nd OpenSSL configuration functions +.Sh SYNOPSIS +.In openssl/conf.h +.Ft int +.Fo CONF_modules_load_file +.Fa "const char *filename" +.Fa "const char *appname" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo CONF_modules_load +.Fa "const CONF *cnf" +.Fa "const char *appname" +.Fa "unsigned long flags" +.Fc +.Sh DESCRIPTION +The function +.Fn CONF_modules_load_file +configures OpenSSL using file +.Fa filename +and application name +.Fa appname . +If +.Fa filename +is +.Dv NULL , +the standard OpenSSL configuration file is used. +If +.Fa appname +is +.Dv NULL , +the standard OpenSSL application name +.Qq openssl_conf +is used. +The behaviour can be cutomized using +.Fa flags . +.Pp +.Fn CONF_modules_load +is idential to +.Fn CONF_modules_load_file +except it reads configuration information from +.Fa cnf . +.Pp +The following +.Fa flags +are currently recognized: +.Bl -tag -width Ds +.It Dv CONF_MFLAGS_IGNORE_ERRORS +Ignore errors returned by individual configuration modules. +By default, the first module error is considered fatal and no further +modules are loaded. +.It Dv CONF_MFLAGS_SILENT +Do not add any error information. +By default, all module errors add error information to the error queue. +.It Dv CONF_MFLAGS_NO_DSO +Disable loading of configuration modules from DSOs. +.It Dv CONF_MFLAGS_IGNORE_MISSING_FILE +Let +.Fn CONF_modules_load_file +ignore missing configuration files. +By default, a missing configuration file returns an error. +.El +.Sh RETURN VALUES +These functions return 1 for success and zero or a negative value for +failure. +If module errors are not ignored, the return code will reflect the return +value of the failing module (this will always be zero or negative). +.Sh SEE ALSO +.Xr CONF_free 3 , +.Xr ERR 3 , +.Xr OPENSSL_config 3 +.Sh HISTORY +.Fn CONF_modules_load_file +and +.Fn CONF_modules_load +first appeared in OpenSSL 0.9.7. diff --git a/src/lib/libcrypto/man/CRYPTO_set_ex_data.3 b/src/lib/libcrypto/man/CRYPTO_set_ex_data.3 new file mode 100644 index 0000000000..1be42dedd9 --- /dev/null +++ b/src/lib/libcrypto/man/CRYPTO_set_ex_data.3 @@ -0,0 +1,70 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CRYPTO_SET_EX_DATA 3 +.Os +.Sh NAME +.Nm CRYPTO_set_ex_data , +.Nm CRYPTO_get_ex_data +.Nd internal application specific data functions +.Sh SYNOPSIS +.In openssl/crypto.h +.Ft int +.Fo CRYPTO_set_ex_data +.Fa "CRYPTO_EX_DATA *r" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft void * +.Fo CRYPTO_get_ex_data +.Fa "CRYPTO_EX_DATA *r" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +Several OpenSSL structures can have application specific data attached +to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. +.Pp +These functions should only be used by applications to manipulate +.Vt CRYPTO_EX_DATA +structures passed to the +.Fn new_func , +.Fn free_func , +and +.Fn dup_func +callbacks: as passed to +.Xr RSA_get_ex_new_index 3 +for example. +.Pp +.Fn CRYPTO_set_ex_data +is used to set application specific data, the data is supplied in the +.Fa arg +parameter and its precise meaning is up to the application. +.Pp +.Fn CRYPTO_get_ex_data +is used to retrieve application specific data. +The data is returned to the application, this will be the same value as +supplied to a previous +.Fn CRYPTO_set_ex_data +call. +.Sh RETURN VALUES +.Fn CRYPTO_set_ex_data +returns 1 on success or 0 on failure. +.Pp +.Fn CRYPTO_get_ex_data +returns the application data or 0 on failure. +0 may also be valid application data but currently it can only fail if +given an invalid +.Fa idx +parameter. +.Pp +On failure an error code can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr DH_get_ex_new_index 3 , +.Xr DSA_get_ex_new_index 3 , +.Xr RSA_get_ex_new_index 3 +.Sh HISTORY +.Fn CRYPTO_set_ex_data +and +.Fn CRYPTO_get_ex_data +have been available since SSLeay 0.9.0. diff --git a/src/lib/libcrypto/man/CRYPTO_set_locking_callback.3 b/src/lib/libcrypto/man/CRYPTO_set_locking_callback.3 new file mode 100644 index 0000000000..d6290852b5 --- /dev/null +++ b/src/lib/libcrypto/man/CRYPTO_set_locking_callback.3 @@ -0,0 +1,321 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CRYPTO_SET_LOCKING_CALLBACK 3 +.Os +.Sh NAME +.Nm CRYPTO_THREADID_set_callback , +.Nm CRYPTO_THREADID_get_callback , +.Nm CRYPTO_THREADID_current , +.Nm CRYPTO_THREADID_cmp , +.Nm CRYPTO_THREADID_cpy , +.Nm CRYPTO_THREADID_hash , +.Nm CRYPTO_set_locking_callback , +.Nm CRYPTO_num_locks , +.Nm CRYPTO_set_dynlock_create_callback , +.Nm CRYPTO_set_dynlock_lock_callback , +.Nm CRYPTO_set_dynlock_destroy_callback , +.Nm CRYPTO_get_new_dynlockid , +.Nm CRYPTO_destroy_dynlockid , +.Nm CRYPTO_lock +.Nd OpenSSL thread support +.Sh SYNOPSIS +.In openssl/crypto.h +.Bd -literal +/* Don't use this structure directly. */ +typedef struct crypto_threadid_st { + void *ptr; + unsigned long val; +} CRYPTO_THREADID; +/* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ +.Ed +.Pp +.Ft void +.Fo CRYPTO_THREADID_set_numeric +.Fa "CRYPTO_THREADID *id" +.Fa "unsigned long val" +.Fc +.Ft void +.Fo CRYPTO_THREADID_set_pointer +.Fa "CRYPTO_THREADID *id" +.Fa "void *ptr" +.Fc +.Ft int +.Fo CRYPTO_THREADID_set_callback +.Fa "void (*threadid_func)(CRYPTO_THREADID *)" +.Fc +.Ft void +.Fo "(*CRYPTO_THREADID_get_callback(void))" +.Fa "CRYPTO_THREADID *" +.Fc +.Ft void +.Fo CRYPTO_THREADID_current +.Fa "CRYPTO_THREADID *id" +.Fc +.Ft int +.Fo CRYPTO_THREADID_cmp +.Fa "const CRYPTO_THREADID *a" +.Fa "const CRYPTO_THREADID *b" +.Fc +.Ft void +.Fo CRYPTO_THREADID_cpy +.Fa "CRYPTO_THREADID *dest" +.Fa "const CRYPTO_THREADID *src" +.Fc +.Ft unsigned long +.Fo CRYPTO_THREADID_hash +.Fa "const CRYPTO_THREADID *id" +.Fc +.Ft int +.Fo CRYPTO_num_locks +.Fa void +.Fc +.Bd -literal +/* struct CRYPTO_dynlock_value needs to be defined by the user */ +struct CRYPTO_dynlock_value; +.Ed +.Pp +.Ft void +.Fo CRYPTO_set_dynlock_create_callback +.Fa "struct CRYPTO_dynlock_value *" +.Fa "(*dyn_create_function)(char *file, int line)" +.Fc +.Ft void +.Fo CRYPTO_set_dynlock_lock_callback +.Fa "void (*dyn_lock_function)(int mode, struct CRYPTO_dynlock_value *l,\ + const char *file, int line)" +.Fc +.Ft void +.Fo CRYPTO_set_dynlock_destroy_callback +.Fa "void (*dyn_destroy_function)(struct CRYPTO_dynlock_value *l,\ + const char *file, int line)" +.Fc +.Ft int +.Fo CRYPTO_get_new_dynlockid +.Fa void +.Fc +.Ft void +.Fo CRYPTO_destroy_dynlockid +.Fa "int i" +.Fc +.Ft void +.Fo CRYPTO_lock +.Fa "int mode" +.Fa "int n" +.Fa "const char *file" +.Fa "int line" +.Fc +.Bd -literal +#define CRYPTO_w_lock(type) \e + CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE, type, __FILE__, __LINE__) +#define CRYPTO_w_unlock(type) \e + CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE, type, __FILE__, __LINE__) +#define CRYPTO_r_lock(type) \e + CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ, type, __FILE__, __LINE__) +#define CRYPTO_r_unlock(type) \e + CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ, type, __FILE__, __LINE__) +#define CRYPTO_add(addr,amount,type) \e + CRYPTO_add_lock(addr, amount, type, __FILE__, __LINE__) +.Ed +.Sh DESCRIPTION +OpenSSL can safely be used in multi-threaded applications provided that +at least two callback functions are set, +.Fn locking_function +and +.Fn threadid_func . +.Pp +.Fo locking_function +.Fa "int mode" +.Fa "int n" +.Fa "const char *file" +.Fa "int line" +.Fc +is needed to perform locking on shared data structures. +Note that OpenSSL uses a number of global data structures that will be +implicitly shared whenever multiple threads use OpenSSL. +Multi-threaded applications will crash at random if it is not set. +.Pp +.Fn locking_function +must be able to handle up to +.Fn CRYPTO_num_locks +different mutex locks. +It sets the +.Fa n Ns -th +lock if +.Fa mode +includes +.Dv CRYPTO_LOCK , +and releases it otherwise. +.Pp +.Fa file +and +.Fa line +are the file number of the function setting the lock. +They can be useful for debugging. +.Pp +.Fo threadid_func +.Fa "CRYPTO_THREADID *id" +.Fc +is needed to record the currently-executing thread's identifier into +.Fa id . +The implementation of this callback should not fill in +.Fa id +directly, but should use +.Fn CRYPTO_THREADID_set_numeric +if thread IDs are numeric, or +.Fn CRYPTO_THREADID_set_pointer +if they are pointer-based. +If the application does not register such a callback using +.Fn CRYPTO_THREADID_set_callback , +then a default implementation is used - on Windows and BeOS this uses +the system's default thread identifying APIs, and on all other platforms +it uses the address of +.Va errno . +The latter is satisfactory for thread-safety if and only if the platform +has a thread-local error number facility. +.Pp +Once +.Fn threadid_func +is registered, or if the built-in default implementation is to be used, +.Bl -bullet +.It +.Fn CRYPTO_THREADID_current +records the currently-executing thread ID into the given +.Fa id +object. +.It +.Fn CRYPTO_THREADID_cmp +compares two thread IDs (returning zero for equality, i.e. the same +semantics as +.Xr memcmp 3 ) . +.It +.Fn CRYPTO_THREADID_cpy +duplicates a thread ID value. +.It +.Fn CRYPTO_THREADID_hash +returns a numeric value usable as a hash-table key. +This is usually the exact numeric or pointer-based thread ID used +internally, however this also handles the unusual case where pointers +are larger than +.Vt long +variables and the platform's thread IDs are pointer-based \(em in +this case, mixing is done to attempt to produce a unique numeric +value even though it is not as wide as the platform's true thread +IDs. +.El +.Pp +Additionally, OpenSSL supports dynamic locks, and sometimes, some parts +of OpenSSL need it for better performance. +To enable this, the following is required: +.Bl -bullet +.It +Three additional callback functions, +.Fn dyn_create_function , +.Fn dyn_lock_function , +and +.Fn dyn_destroy_function . +.It +A structure defined with the data that each lock needs to handle. +.El +.Pp +.Vt struct CRYPTO_dynlock_value +has to be defined to contain whatever structure is needed to handle locks. +.Pp +.Fo dyn_create_function +.Fa "const char *file" +.Fa "int line" +.Fc +is needed to create a lock. +Multi-threaded applications might crash at random if it is not set. +.Pp +.Fo dyn_lock_function +.Fa "int mode" +.Fa "CRYPTO_dynlock *l" +.Fa "const char *file" +.Fa "int line" +.Fc +is needed to perform locking off dynamic lock numbered n. +Multi-threaded applications might crash at random if it is not set. +.Pp +.Fo dyn_destroy_function +.Fa "CRYPTO_dynlock *l" +.Fa "const char *file" +.Fa "int line" +.Fc +is needed to destroy the lock +.Fa l . +Multi-threaded applications might crash at random if it is not set. +.Pp +.Fn CRYPTO_get_new_dynlockid +is used to create locks. +It will call +.Fn dyn_create_function +for the actual creation. +.Pp +.Fn CRYPTO_destroy_dynlockid +is used to destroy locks. +It will call +.Fn dyn_destroy_function +for the actual destruction. +.Pp +.Fn CRYPTO_lock +is used to lock and unlock the locks. +.Fa mode +is a bitfield describing what should be done with the lock. +.Fa n +is the number of the lock as returned from +.Fn CRYPTO_get_new_dynlockid . +.Fa mode +can be combined from the following values. +These values are pairwise exclusive, with undefined behaviour if misused +(for example, +.Dv CRYPTO_READ +and +.Dv CRYPTO_WRITE +should not be used together): +.Bd -literal -offset indent +CRYPTO_LOCK 0x01 +CRYPTO_UNLOCK 0x02 +CRYPTO_READ 0x04 +CRYPTO_WRITE 0x08 +.Ed +.Sh RETURN VALUES +.Fn CRYPTO_num_locks +returns the required number of locks. +.Pp +.Fn CRYPTO_get_new_dynlockid +returns the index to the newly created lock. +.Pp +The other functions return no values. +.Sh NOTES +You can find out if OpenSSL was configured with thread support: +.Bd -literal -offset indent +#define OPENSSL_THREAD_DEFINES +#include +#if defined(OPENSSL_THREADS) + /* thread support enabled */ +#else + /* no thread support */ +#endif +.Ed +.Pp +Also, dynamic locks are currently not used internally by OpenSSL, but +may do so in the future. +.Sh EXAMPLES +.Pa crypto/threads/mttest.c +shows examples of the callback functions on Solaris, Irix and Win32. +.Sh SEE ALSO +.Xr crypto 3 +.Sh HISTORY +.Fn CRYPTO_set_locking_callback +is available in all versions of SSLeay and OpenSSL. +.Fn CRYPTO_num_locks +was added in OpenSSL 0.9.4. +All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. +.Vt CRYPTO_THREADID +and associated functions were introduced in OpenSSL 1.0.0 to replace +(actually, deprecate) the previous +.Fn CRYPTO_set_id_callback , +.Fn CRYPTO_get_id_callback , +and +.Fn CRYPTO_thread_id +functions which assumed thread IDs to always be represented by +.Vt unsigned long . diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 2c5ffbb8e4..ef5c1f9727 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.26 2015/11/11 18:36:48 schwarze Exp $ +# $OpenBSD: Makefile,v 1.27 2015/11/11 21:15:15 schwarze Exp $ .include # for NOMAN @@ -69,13 +69,14 @@ MAN= \ CMS_uncompress.3 \ CMS_verify.3 \ CMS_verify_receipt.3 \ - EVP_AEAD_CTX_init.3 \ - -GENMAN= \ CONF_modules_free.3 \ CONF_modules_load_file.3 \ CRYPTO_set_ex_data.3 \ CRYPTO_set_locking_callback.3 \ + EVP_AEAD_CTX_init.3 \ + crypto.3 \ + +GENMAN= \ DES_set_key.3 \ DH_generate_key.3 \ DH_generate_parameters.3 \ @@ -188,7 +189,6 @@ GENMAN= \ X509_verify_cert.3 \ bn.3 \ bn_internal.3 \ - crypto.3 \ d2i_ASN1_OBJECT.3 \ d2i_DHparams.3 \ d2i_DSAPublicKey.3 \ diff --git a/src/lib/libcrypto/man/crypto.3 b/src/lib/libcrypto/man/crypto.3 new file mode 100644 index 0000000000..24d4ed1979 --- /dev/null +++ b/src/lib/libcrypto/man/crypto.3 @@ -0,0 +1,104 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CRYPTO 3 +.Os +.Sh NAME +.Nm crypto +.Nd OpenSSL cryptographic library +.Sh DESCRIPTION +The OpenSSL crypto library implements a wide range of cryptographic +algorithms used in various Internet standards. +The services provided by this library are used by the OpenSSL +implementations of SSL, TLS and S/MIME, and they have also been used to +implement SSH, OpenPGP, and other cryptographic standards. +.Sh OVERVIEW +.Sy libcrypto +consists of a number of sub-libraries that implement the individual +algorithms. +.Pp +The functionality includes symmetric encryption, public key cryptography +and key agreement, certificate handling, cryptographic hash functions +and a cryptographic pseudo-random number generator. +.Bl -tag -width Ds +.It SYMMETRIC CIPHERS +.Xr blowfish 3 , +cast, +.Xr des 3 , +idea, +rc2, +.Xr rc4 3 , +rc5 +.It PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT +.Xr dsa 3 , +.Xr dh 3 , +.Xr rsa 3 +.It CERTIFICATES +.Xr x509 3 , +x509v3 +.It AUTHENTICATION CODES, HASH FUNCTIONS +.Xr hmac 3 , +.Xr MD2 3 , +.Xr MD4 3 , +.Xr MD5 3 , +.Xr ripemd 3 , +.Xr sha 3 +.It AUXILIARY FUNCTIONS +.Xr ERR 3 , +.Xr threads 3 , +.Xr rand 3 , +.Xr OPENSSL_VERSION_NUMBER 3 +.It INPUT/OUTPUT, DATA ENCODING +asn1, +.Xr bio 3 , +.Xr evp 3 , +.Xr pem 3 , +pkcs7, +pkcs12 +.It INTERNAL FUNCTIONS +.Xr bn 3 , +.Xr buffer 3 , +.Xr ec 3 , +.Xr lhash 3 , +objects, +stack, +txt_db +.El +.Sh NOTES +Some of the newer functions follow a naming convention using the numbers +.Sq 0 +and +.Sq 1 . +For example the functions: +.Pp +.Ft int +.Fo X509_CRL_add0_revoked +.Fa "X509_CRL *crl" +.Fa "X509_REVOKED *rev" +.Fc +.br +.Ft int +.Fo X509_add1_trust_object +.Fa "X509 *x" +.Fa "ASN1_OBJECT *obj" +.Fc +.Pp +The +.Sq 0 +version uses the supplied structure pointer directly in the parent and +it will be freed up when the parent is freed. +In the above example +.Fa crl +would be freed but +.Fa rev +would not. +.Pp +The +.Sq 1 +function uses a copy of the supplied structure pointer (or in some cases +increases its link count) in the parent and so both +.Pf ( Fa x +and +.Fa obj +above) should be freed up. +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 diff --git a/src/lib/libssl/src/doc/crypto/CONF_modules_free.pod b/src/lib/libssl/src/doc/crypto/CONF_modules_free.pod deleted file mode 100644 index 803b2faab1..0000000000 --- a/src/lib/libssl/src/doc/crypto/CONF_modules_free.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -CONF_modules_free, CONF_modules_finish, CONF_modules_unload - OpenSSL -configuration cleanup functions - -=head1 SYNOPSIS - - #include - - void CONF_modules_free(void); - void CONF_modules_finish(void); - void CONF_modules_unload(int all); - -=head1 DESCRIPTION - -CONF_modules_free() closes down and frees up all memory allocated by all -configuration modules. - -CONF_modules_finish() calls each configuration modules B handler -to free up any configuration that module may have performed. - -CONF_modules_unload() finishes and unloads configuration modules. If -B is set to B<0> only modules loaded from DSOs will be unloads. If -B is B<1> all modules, including builtin modules will be unloaded. - -=head1 NOTES - -Normally applications will only call CONF_modules_free() at application to -tidy up any configuration performed. - -=head1 RETURN VALUE - -None of the functions return a value. - -=head1 SEE ALSO - -L, L, -L - -=head1 HISTORY - -CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish() -first appeared in OpenSSL 0.9.7. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CONF_modules_load_file.pod b/src/lib/libssl/src/doc/crypto/CONF_modules_load_file.pod deleted file mode 100644 index e663ac5bc9..0000000000 --- a/src/lib/libssl/src/doc/crypto/CONF_modules_load_file.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions - -=head1 SYNOPSIS - - #include - - int CONF_modules_load_file(const char *filename, const char *appname, - unsigned long flags); - int CONF_modules_load(const CONF *cnf, const char *appname, - unsigned long flags); - -=head1 DESCRIPTION - -The function CONF_modules_load_file() configures OpenSSL using file -B and application name B. If B is NULL -the standard OpenSSL configuration file is used. If B is -NULL the standard OpenSSL application name B is used. -The behaviour can be customized using B. - -CONF_modules_load() is identical to CONF_modules_load_file() except it -read configuration information from B. - -=head1 NOTES - -The following B are currently recognized: - -B if set errors returned by individual -configuration modules are ignored. If not set the first module error is -considered fatal and no further modules are loads. - -Normally any modules errors will add error information to the error queue. If -B is set no error information is added. - -If B is set configuration module loading from DSOs is -disabled. - -B if set will make CONF_load_modules_file() -ignore missing configuration files. Normally a missing configuration file -return an error. - -=head1 RETURN VALUE - -These functions return 1 for success and a zero or negative value for -failure. If module errors are not ignored the return code will reflect the -return value of the failing module (this will always be zero or negative). - -=head1 SEE ALSO - -L, L, -L, L - -=head1 HISTORY - -CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CRYPTO_set_ex_data.pod b/src/lib/libssl/src/doc/crypto/CRYPTO_set_ex_data.pod deleted file mode 100644 index 0c8b378854..0000000000 --- a/src/lib/libssl/src/doc/crypto/CRYPTO_set_ex_data.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data -functions - -=head1 SYNOPSIS - - #include - - int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); - - void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -These functions should only be used by applications to manipulate -B structures passed to the B, B and -B callbacks: as passed to B for example. - -B is used to set application specific data, the data is -supplied in the B parameter and its precise meaning is up to the -application. - -B is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous B call. - -=head1 RETURN VALUES - -B returns 1 on success or 0 on failure. - -B returns the application data or 0 on failure. 0 may -also be valid application data but currently it can only fail if given an -invalid B parameter. - -On failure an error code can be obtained from -L. - -=head1 SEE ALSO - -L, -L, -L - -=head1 HISTORY - -CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay -0.9.0. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CRYPTO_set_locking_callback.pod b/src/lib/libssl/src/doc/crypto/CRYPTO_set_locking_callback.pod deleted file mode 100644 index 8f4cf4cb2d..0000000000 --- a/src/lib/libssl/src/doc/crypto/CRYPTO_set_locking_callback.pod +++ /dev/null @@ -1,210 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, -CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, -CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, -CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, -CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, -CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support - -=head1 SYNOPSIS - - #include - - /* Don't use this structure directly. */ - typedef struct crypto_threadid_st - { - void *ptr; - unsigned long val; - } CRYPTO_THREADID; - /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ - void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); - void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); - int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); - void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); - void CRYPTO_THREADID_current(CRYPTO_THREADID *id); - int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, - const CRYPTO_THREADID *b); - void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, - const CRYPTO_THREADID *src); - unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); - - int CRYPTO_num_locks(void); - - /* struct CRYPTO_dynlock_value needs to be defined by the user */ - struct CRYPTO_dynlock_value; - - void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * - (*dyn_create_function)(char *file, int line)); - void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) - (int mode, struct CRYPTO_dynlock_value *l, - const char *file, int line)); - void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) - (struct CRYPTO_dynlock_value *l, const char *file, int line)); - - int CRYPTO_get_new_dynlockid(void); - - void CRYPTO_destroy_dynlockid(int i); - - void CRYPTO_lock(int mode, int n, const char *file, int line); - - #define CRYPTO_w_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_w_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_r_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_r_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_add(addr,amount,type) \ - CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) - -=head1 DESCRIPTION - -OpenSSL can safely be used in multi-threaded applications provided -that at least two callback functions are set, locking_function and -threadid_func. - -locking_function(int mode, int n, const char *file, int line) is -needed to perform locking on shared data structures. -(Note that OpenSSL uses a number of global data structures that -will be implicitly shared whenever multiple threads use OpenSSL.) -Multi-threaded applications will crash at random if it is not set. - -locking_function() must be able to handle up to CRYPTO_num_locks() -different mutex locks. It sets the B-th lock if B & -B, and releases it otherwise. - -B and B are the file number of the function setting the -lock. They can be useful for debugging. - -threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing -thread's identifier into B. The implementation of this callback should not -fill in B directly, but should use CRYPTO_THREADID_set_numeric() if thread -IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based. -If the application does not register such a callback using -CRYPTO_THREADID_set_callback(), then a default implementation is used - on -Windows and BeOS this uses the system's default thread identifying APIs, and on -all other platforms it uses the address of B. The latter is satisfactory -for thread-safety if and only if the platform has a thread-local error number -facility. - -Once threadid_func() is registered, or if the built-in default implementation is -to be used; - -=over 4 - -=item * -CRYPTO_THREADID_current() records the currently-executing thread ID into the -given B object. - -=item * -CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie. -the same semantics as memcmp()). - -=item * -CRYPTO_THREADID_cpy() duplicates a thread ID value, - -=item * -CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This -is usually the exact numeric or pointer-based thread ID used internally, however -this also handles the unusual case where pointers are larger than 'long' -variables and the platform's thread IDs are pointer-based - in this case, mixing -is done to attempt to produce a unique numeric value even though it is not as -wide as the platform's true thread IDs. - -=back - -Additionally, OpenSSL supports dynamic locks, and sometimes, some parts -of OpenSSL need it for better performance. To enable this, the following -is required: - -=over 4 - -=item * -Three additional callback function, dyn_create_function, dyn_lock_function -and dyn_destroy_function. - -=item * -A structure defined with the data that each lock needs to handle. - -=back - -struct CRYPTO_dynlock_value has to be defined to contain whatever structure -is needed to handle locks. - -dyn_create_function(const char *file, int line) is needed to create a -lock. Multi-threaded applications might crash at random if it is not set. - -dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) -is needed to perform locking off dynamic lock numbered n. Multi-threaded -applications might crash at random if it is not set. - -dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is -needed to destroy the lock l. Multi-threaded applications might crash at -random if it is not set. - -CRYPTO_get_new_dynlockid() is used to create locks. It will call -dyn_create_function for the actual creation. - -CRYPTO_destroy_dynlockid() is used to destroy locks. It will call -dyn_destroy_function for the actual destruction. - -CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield -describing what should be done with the lock. n is the number of the -lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined -from the following values. These values are pairwise exclusive, with -undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE -should not be used together): - - CRYPTO_LOCK 0x01 - CRYPTO_UNLOCK 0x02 - CRYPTO_READ 0x04 - CRYPTO_WRITE 0x08 - -=head1 RETURN VALUES - -CRYPTO_num_locks() returns the required number of locks. - -CRYPTO_get_new_dynlockid() returns the index to the newly created lock. - -The other functions return no values. - -=head1 NOTES - -You can find out if OpenSSL was configured with thread support: - - #define OPENSSL_THREAD_DEFINES - #include - #if defined(OPENSSL_THREADS) - // thread support enabled - #else - // no thread support - #endif - -Also, dynamic locks are currently not used internally by OpenSSL, but -may do so in the future. - -=head1 EXAMPLES - -B shows examples of the callback functions on -Solaris, Irix and Win32. - -=head1 HISTORY - -CRYPTO_set_locking_callback() is -available in all versions of SSLeay and OpenSSL. -CRYPTO_num_locks() was added in OpenSSL 0.9.4. -All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. -B and associated functions were introduced in OpenSSL 1.0.0 -to replace (actually, deprecate) the previous CRYPTO_set_id_callback(), -CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed -thread IDs to always be represented by 'unsigned long'. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/crypto.pod b/src/lib/libssl/src/doc/crypto/crypto.pod deleted file mode 100644 index bbd6ce9ea9..0000000000 --- a/src/lib/libssl/src/doc/crypto/crypto.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -crypto - OpenSSL cryptographic library - -=head1 SYNOPSIS - -=head1 DESCRIPTION - -The OpenSSL B library implements a wide range of cryptographic -algorithms used in various Internet standards. The services provided -by this library are used by the OpenSSL implementations of SSL, TLS -and S/MIME, and they have also been used to implement SSH, OpenPGP, and -other cryptographic standards. - -=head1 OVERVIEW - -B consists of a number of sub-libraries that implement the -individual algorithms. - -The functionality includes symmetric encryption, public key -cryptography and key agreement, certificate handling, cryptographic -hash functions and a cryptographic pseudo-random number generator. - -=over 4 - -=item SYMMETRIC CIPHERS - -L, L, L, -L, L, L, L - -=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT - -L, L, L - -=item CERTIFICATES - -L, L - -=item AUTHENTICATION CODES, HASH FUNCTIONS - -L, L, L, -L, L, -L - -=item AUXILIARY FUNCTIONS - -L, L, L, -L - -=item INPUT/OUTPUT, DATA ENCODING - -L, L, L, L, -L, L - -=item INTERNAL FUNCTIONS - -L, L, L, L, -L, L, -L - -=back - -=head1 NOTES - -Some of the newer functions follow a naming convention using the numbers -B<0> and B<1>. For example the functions: - - int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); - int X509_add1_trust_object(X509 *x, ASN1_OBJECT *obj); - -The B<0> version uses the supplied structure pointer directly -in the parent and it will be freed up when the parent is freed. -In the above example B would be freed but B would not. - -The B<1> function uses a copy of the supplied structure pointer -(or in some cases increases its link count) in the parent and -so both (B and B above) should be freed up. - -=head1 SEE ALSO - -L, L - -=cut -- cgit v1.2.3-55-g6feb