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 +++++++ 6 files changed, 638 insertions(+), 5 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 (limited to 'src/lib/libcrypto/man') 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 -- cgit v1.2.3-55-g6feb