From 263b1d6ed97d56608f9a358fa0bfe9e66c968f36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Fri, 12 Dec 2014 08:29:43 +0100 Subject: Make the OpenSSL locking function warnings more severe Our git_openssl_set_locking() would ideally not exist. Make it clearer that we provide it as a last resort and you should prefer anything else. --- THREADING.md | 21 +++++++++++++++------ include/git2.h | 1 - include/git2/sys/openssl.h | 38 ++++++++++++++++++++++++++++++++++++++ include/git2/threads.h | 40 ---------------------------------------- src/global.c | 1 - 5 files changed, 53 insertions(+), 48 deletions(-) create mode 100644 include/git2/sys/openssl.h delete mode 100644 include/git2/threads.h diff --git a/THREADING.md b/THREADING.md index a264567ee..c9bee5184 100644 --- a/THREADING.md +++ b/THREADING.md @@ -54,17 +54,26 @@ it should use. This means that libgit2 cannot know what to set as the user of libgit2 may use OpenSSL independently and the locking settings must survive libgit2 shutting down. -libgit2 does provide a convenience function -`git_openssl_set_locking()` to use the platform-native mutex -mechanisms to perform the locking, which you may rely on if you do not -want to use OpenSSL outside of libgit2, or you know that libgit2 will -outlive the rest of the operations. It is not safe to use OpenSSL -multi-threaded after libgit2's shutdown function has been called. +libgit2 does provide a last-resort convenience function +`git_openssl_set_locking()` (available in `sys/openssl.h`) to use the +platform-native mutex mechanisms to perform the locking, which you may +rely on if you do not want to use OpenSSL outside of libgit2, or you +know that libgit2 will outlive the rest of the operations. It is not +safe to use OpenSSL multi-threaded after libgit2's shutdown function +has been called. + +If your programming language offers a package/bindings for OpenSSL, +you should very strongly prefer to use that in order to set up +locking, as they provide a level of coördination which is impossible +when using this function. See the [OpenSSL documentation](https://www.openssl.org/docs/crypto/threads.html) on threading for more details. +Be also aware that libgit2 may not always link against OpenSSL in the +future if there are alternatives provided by the system. + libssh2 may be linked against OpenSSL or libgcrypt. If it uses OpenSSL, you only need to set up threading for OpenSSL once and the above paragraphs are enough. If it uses libgcrypt, then you need to diff --git a/include/git2.h b/include/git2.h index b36bb5365..cf6b5cb89 100644 --- a/include/git2.h +++ b/include/git2.h @@ -57,7 +57,6 @@ #include "git2/status.h" #include "git2/submodule.h" #include "git2/tag.h" -#include "git2/threads.h" #include "git2/transport.h" #include "git2/tree.h" #include "git2/types.h" diff --git a/include/git2/sys/openssl.h b/include/git2/sys/openssl.h new file mode 100644 index 000000000..ad05e6ca8 --- /dev/null +++ b/include/git2/sys/openssl.h @@ -0,0 +1,38 @@ +/* + * Copyright (C) the libgit2 contributors. All rights reserved. + * + * This file is part of libgit2, distributed under the GNU GPL v2 with + * a Linking Exception. For full terms see the included COPYING file. + */ +#ifndef INCLUDE_git_openssl_h__ +#define INCLUDE_git_openssl_h__ + +#include "common.h" + +GIT_BEGIN_DECL + +/** + * Initialize the OpenSSL locks + * + * OpenSSL requires the application to determine how it performs + * locking. + * + * This is a last-resort convenience function which libgit2 provides for + * allocating and initializing the locks as well as setting the + * locking function to use the system's native locking functions. + * + * The locking function will be cleared and the memory will be freed + * when you call git_threads_sutdown(). + * + * If your programming language has an OpenSSL package/bindings, it + * likely sets up locking. You should very strongly prefer that over + * this function. + * + * @return 0 on success, -1 if there are errors or if libgit2 was not + * built with OpenSSL and threading support. + */ +GIT_EXTERN(int) git_openssl_set_locking(void); + +GIT_END_DECL +#endif + diff --git a/include/git2/threads.h b/include/git2/threads.h deleted file mode 100644 index c0c3898d9..000000000 --- a/include/git2/threads.h +++ /dev/null @@ -1,40 +0,0 @@ -/* - * Copyright (C) the libgit2 contributors. All rights reserved. - * - * This file is part of libgit2, distributed under the GNU GPL v2 with - * a Linking Exception. For full terms see the included COPYING file. - */ -#ifndef INCLUDE_git_threads_h__ -#define INCLUDE_git_threads_h__ - -#include "common.h" - -/** - * @file git2/threads.h - * @brief Library level thread functions - * @defgroup git_thread Threading functions - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Initialize the OpenSSL locks - * - * OpenSSL requires the application to determine how it performs - * locking. This is a convenience function which libgit2 provides for - * allocating and initializing the locks as well as setting the - * locking function to use the system's native locking functions. - * - * The locking function will be cleared and the memory will be freed - * when you call git_threads_sutdown(). - * - * @return 0 on success, -1 if there are errors or if libgit2 was not - * built with OpenSSL and threading support. - */ -GIT_EXTERN(int) git_openssl_set_locking(void); - -/** @} */ -GIT_END_DECL -#endif - diff --git a/src/global.c b/src/global.c index b09e6df02..f79bfd353 100644 --- a/src/global.c +++ b/src/global.c @@ -8,7 +8,6 @@ #include "global.h" #include "hash.h" #include "sysdir.h" -#include "git2/threads.h" #include "git2/global.h" #include "thread-utils.h" -- cgit v1.2.3 From 5192bcc52cbc7f049ef85f52a997a44cb4ebe5c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Fri, 12 Dec 2014 08:30:37 +0100 Subject: Add the OpenSSL changes to the CHANGELOG It seems these were forgotten when initially splitting this up. --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cfb4f0430..a8b3353f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,11 @@ v0.21 + 1 tells it to include a copy of libssh2 at the given location. This is enabled for MSVC. +* libgit2 no longer automatically sets the OpenSSL locking + functions. This is not something which we can know to do. A + last-resort convenience function is provided in sys/openssl.h, + git_openssl_set_locking() which can be used to set the locking. + * The git_transport_register function no longer takes a priority and takes a URL scheme name (eg "http") instead of a prefix like "http://" -- cgit v1.2.3