diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index efb4be8716..13a5d63695 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ To request new features or report bugs, please open an issue on GitHub To submit a patch, please open a pull request on GitHub. If you are thinking of making a large contribution, open an issue for it before starting work, to get comments from the community. Someone may be already working on -the same thing or there may be reasons why that feature isn't implemented. +the same thing, or there may be reasons why that feature isn't implemented. To make it easier to review and accept your pull request, please follow these guidelines: @@ -54,7 +54,7 @@ guidelines: (usually by rebasing) before it will be acceptable. 4. Patches should follow our [coding style] and compile without warnings. - Where `gcc` or `clang` is available you should use the + Where `gcc` or `clang` is available, you should use the `--strict-warnings` `Configure` option. OpenSSL compiles on many varied platforms: try to ensure you only use portable features. Clean builds via GitHub Actions and AppVeyor are required, and they are started automatically diff --git a/HACKING.md b/HACKING.md index 6375450c24..9a1f7b9f50 100644 --- a/HACKING.md +++ b/HACKING.md @@ -9,7 +9,7 @@ This document describes the way to add custom modifications to OpenSSL sources. [Configurations/unix-Makefile.tmpl](Configurations/unix-Makefile.tmpl) to pick up that file. - After that perform the following steps: + After that, perform the following steps: ./Configure -Werror --strict-warnings [your-options] make update @@ -27,7 +27,7 @@ This document describes the way to add custom modifications to OpenSSL sources. `make update` also generates files related to OIDs (in the `crypto/objects/` folder) and errors. - If a merge error occurs in one of these generated files then the + If a merge error occurs in one of these generated files, then the generated files need to be removed and regenerated using `make update`. - To aid in this process the generated files can be committed separately + To aid in this process, the generated files can be committed separately so they can be removed easily. diff --git a/INSTALL.md b/INSTALL.md index 3e711f3c76..3c995349bd 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1020,7 +1020,7 @@ below and how these flags interact with those variables. Additional options that are not otherwise recognised are passed through as they are to the compiler as well. Unix-style options beginning with a -`-` or `+` and Windows-style options beginning with a `/` are recognized. +`-` or `+` and Windows-style options beginning with a `/` are recognised. Again, consult your compiler documentation. If the option contains arguments separated by spaces, then the URL-style diff --git a/NOTES-ANDROID.md b/NOTES-ANDROID.md index eebf03a4c4..c79b2212d4 100644 --- a/NOTES-ANDROID.md +++ b/NOTES-ANDROID.md @@ -4,7 +4,7 @@ Notes for Android platforms Requirement details ------------------- - Beside basic tools like perl and make you'll need to download the Android + Beside basic tools like perl and make, you'll need to download the Android NDK. It's available for Linux, macOS and Windows, but only Linux version was actually tested. There is no reason to believe that macOS wouldn't work. And as for Windows, it's unclear which "shell" would be @@ -26,13 +26,13 @@ Notes for Android platforms invoke `$(CROSS_COMPILE)clang` [`*gcc` on NDK 19 and lower] and company. (`./Configure` will fail and give you a hint if you get it wrong.) - Apart from `PATH` adjustment you need to set `ANDROID_NDK_ROOT` environment + Apart from `PATH` adjustment, you need to set `ANDROID_NDK_ROOT` environment to point at the `NDK` directory. If you're using a side-by-side NDK the path will look something like `/some/where/android-sdk/ndk/`, and for a standalone NDK the path will be something like `/some/where/android-ndk-`. Both variables are significant at both configuration and compilation times. The NDK customarily supports multiple Android API levels, e.g. `android-14`, - `android-21`, etc. By default latest API level is chosen. If you need to target + `android-21`, etc. By default, latest API level is chosen. If you need to target an older platform pass the argument `-D__ANDROID_API__=N` to `Configure`, with `N` being the numerical value of the target platform version. For example, to compile for Android 10 arm64 with a side-by-side NDK r20.0.5594570 @@ -59,7 +59,7 @@ Notes for Android platforms conflict, and mixing the two is therefore not supported. Migration to `CROSS_SYSROOT`-less setup is recommended. - One can engage clang by adjusting PATH to cover same NDK's clang. Just + One can engage clang by adjusting PATH to cover the same NDK's clang. Just keep in mind that if you miss it, Configure will try to use gcc... Also, PATH would need even further adjustment to cover unprefixed, yet target-specific, ar and ranlib. It's possible that you don't need to @@ -67,7 +67,7 @@ Notes for Android platforms Another option is to create so called "standalone toolchain" tailored for single specific platform including Android API level, and assign its - location to `ANDROID_NDK_ROOT`. In such case you have to pass matching + location to `ANDROID_NDK_ROOT`. In such case, you have to pass matching target name to Configure and shouldn't use `-D__ANDROID_API__=N`. `PATH` adjustment becomes simpler, `$ANDROID_NDK_ROOT/bin:$PATH` suffices. diff --git a/NOTES-PERL.md b/NOTES-PERL.md index b7fc83fc7d..b49daed244 100644 --- a/NOTES-PERL.md +++ b/NOTES-PERL.md @@ -33,12 +33,12 @@ Perl on Windows --------------- There are a number of build targets that can be viewed as "Windows". -Indeed, there are `VC-*` configs targeting VisualStudio C, as well as +Indeed, there are `VC-*` configs targeting Visual Studio C, as well as MinGW and Cygwin. The key recommendation is to use a Perl installation that matches the build environment. For example, if you will build on Cygwin be sure to use the Cygwin package manager to install Perl. For MSYS builds use the MSYS provided Perl. -For VC-* builds we recommend Strawberry Perl, from . +For VC-* builds, we recommend Strawberry Perl, from . An alternative is ActiveState Perl, from for which you may need to explicitly select the Perl module Win32/Console.pm available via . diff --git a/NOTES-UNIX.md b/NOTES-UNIX.md index 293793b605..fa52de68ab 100644 --- a/NOTES-UNIX.md +++ b/NOTES-UNIX.md @@ -101,14 +101,14 @@ Notes for UNIX-like platforms shared library face exactly the same problem with non-default locations. The OpenSSL config options mentioned above might or might not have bearing on linking of the target application. "Might" means that under some - circumstances it would be sufficient to link with OpenSSL shared library + circumstances, it would be sufficient to link with OpenSSL shared library "naturally", i.e. with `-L/whatever/path -lssl -lcrypto`. But there are also cases when you'd have to explicitly specify runtime search path when linking your application. Consult your system documentation and use above section as inspiration... Shared OpenSSL builds also install static libraries. Linking with the - latter is likely to require special care, because linkers usually look + latter is likely to require special care because linkers usually look for shared libraries first and tend to remain "blind" to static OpenSSL libraries. Referring to system documentation would suffice, if not for a corner case. On AIX static libraries (in shared build) are named diff --git a/NOTES-WINDOWS.md b/NOTES-WINDOWS.md index b1d6c4fe13..63264b5731 100644 --- a/NOTES-WINDOWS.md +++ b/NOTES-WINDOWS.md @@ -23,7 +23,7 @@ or "Hosted" OpenSSL relies on an external POSIX compatibility layer for building (using GNU/Unix shell, compiler, and tools) and at run time. -For this option you can use Cygwin. +For this option, you can use Cygwin. Native builds using Visual C++ ============================== @@ -212,7 +212,7 @@ Linking native applications This section applies to all native builds. -If you link with static OpenSSL libraries then you're expected to +If you link with static OpenSSL libraries, then you're expected to additionally link your application with `WS2_32.LIB`, `GDI32.LIB`, `ADVAPI32.LIB`, `CRYPT32.LIB` and `USER32.LIB`. Those developing non-interactive service applications might feel concerned about @@ -220,7 +220,7 @@ linking with `GDI32.LIB` and `USER32.LIB`, as they are justly associated with interactive desktop, which is not available to service processes. The toolkit is designed to detect in which context it's currently executed, GUI, console app or service, and act accordingly, -namely whether or not to actually make GUI calls. Additionally those +namely whether to actually make GUI calls. Additionally, those who wish to `/DELAYLOAD:GDI32.DLL` and `/DELAYLOAD:USER32.DLL` and actually keep them off service process should consider implementing and exporting from .exe image in question own `_OPENSSL_isservice` not @@ -261,5 +261,5 @@ Apart from that, follow the Unix / Linux instructions in INSTALL.md. NOTE: `make test` and normal file operations may fail in directories mounted as text (i.e. `mount -t c:\somewhere /home`) due to Cygwin -stripping of carriage returns. To avoid this ensure that a binary +stripping of carriage returns. To avoid this, ensure that a binary mount is used, e.g. `mount -b c:\somewhere /home`. diff --git a/README-ENGINES.md b/README-ENGINES.md index 9992cebe22..24ec748fe5 100644 --- a/README-ENGINES.md +++ b/README-ENGINES.md @@ -22,9 +22,9 @@ Built-in ENGINE implementations There are currently built-in ENGINE implementations for the following crypto devices: - * Microsoft CryptoAPI - * VIA Padlock - * nCipher CHIL +- Microsoft CryptoAPI +- VIA Padlock +- nCipher CHIL In addition, dynamic binding to external ENGINE implementations is now provided by a special ENGINE called "dynamic". See the "DYNAMIC ENGINE" @@ -32,9 +32,9 @@ section below for details. At this stage, a number of things are still needed and are being worked on: - 1. Integration of EVP support. - 2. Configuration support. - 3. Documentation! +1. Integration of EVP support. +2. Configuration support. +3. Documentation! Integration of EVP support -------------------------- @@ -87,17 +87,17 @@ devices from common OpenSSL-based applications. Bugs and/or inexplicable behaviour in using a specific ENGINE implementation should be sent to the author of that implementation (if it is mentioned in the corresponding C file), and in the case of implementations for commercial hardware -devices, also through whatever vendor support channels are available. If +devices, also through whatever vendor support channels are available. If none of this is possible, or the problem seems to be something about the ENGINE API itself (ie. not necessarily specific to a particular ENGINE implementation) then you should mail complete details to the relevant OpenSSL mailing list. For a definition of "complete details", refer to the OpenSSL "README" file. As for which list to send it to: - * openssl-users: if you are *using* the ENGINE abstraction, either in an - pre-compiled application or in your own application code. +- openssl-users: if you are *using* the ENGINE abstraction, either in an + pre-compiled application or in your own application code. - * openssl-dev: if you are discussing problems with OpenSSL source code. +- openssl-dev: if you are discussing problems with OpenSSL source code. USAGE ===== @@ -185,7 +185,7 @@ the shared-library ENGINE implementation. If this command succeeds, the (copy of the) 'dynamic' ENGINE will magically morph into the ENGINE that has been loaded from the shared-library. As such, any control commands supported by the loaded ENGINE could then be executed as per -normal. Eg. if ENGINE "foo" is implemented in the shared-library +normal. For instance, if ENGINE "foo" is implemented in the shared-library "libfoo.so" and it supports some special control command "CMD_FOO", the following code would load and use it (NB: obviously this code has no error checking); @@ -270,35 +270,36 @@ This example will show building the "atalla" ENGINE in the crypto/engine/ directory as a shared-library for use via the "dynamic" ENGINE. - 1. "cd" to the crypto/engine/ directory of a pre-compiled OpenSSL - source tree. +1. "cd" to the crypto/engine/ directory of a pre-compiled OpenSSL + source tree. - 2. Recompile at least one source file so you can see all the compiler - flags (and syntax) being used to build normally. Eg; +2. Recompile at least one source file so you can see all the compiler + flags (and syntax) being used to build normally. Eg; - touch hw_atalla.c ; make + touch hw_atalla.c ; make - will rebuild "hw_atalla.o" using all such flags. + will rebuild "hw_atalla.o" using all such flags. - 3. Manually enter the same compilation line to compile the - "hw_atalla.c" file but with the following two changes; - * add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches, - * change the output file from "hw_atalla.o" to something new, - eg. "tmp_atalla.o" +3. Manually enter the same compilation line to compile the + "hw_atalla.c" file but with the following two changes; - 4. Link "tmp_atalla.o" into a shared-library using the top-level - OpenSSL libraries to resolve any dependencies. The syntax for doing - this depends heavily on your system/compiler and is a nightmare - known well to anyone who has worked with shared-library portability - before. 'gcc' on Linux, for example, would use the following syntax; + - add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches, + - change the output file from "hw_atalla.o" to something new, + eg. "tmp_atalla.o" - gcc -shared -o dyn_atalla.so tmp_atalla.o -L../.. -lcrypto +4. Link "tmp_atalla.o" into a shared-library using the top-level + OpenSSL libraries to resolve any dependencies. The syntax for doing + this depends heavily on your system/compiler and is a nightmare + known well to anyone who has worked with shared-library portability + before. 'gcc' on Linux, for example, would use the following syntax; - 5. Test your shared library using "openssl engine" as explained in the - previous section. Eg. from the top-level directory, you might try + gcc -shared -o dyn_atalla.so tmp_atalla.o -L../.. -lcrypto - apps/openssl engine -vvvv dynamic \ - -pre SO_PATH:./crypto/engine/dyn_atalla.so -pre LOAD +5. Test your shared library using "openssl engine" as explained in the + previous section. Eg. from the top-level directory, you might try + + apps/openssl engine -vvvv dynamic \ + -pre SO_PATH:./crypto/engine/dyn_atalla.so -pre LOAD If the shared-library loads successfully, you will see both "-pre" commands marked as "SUCCESS" and the list of control commands @@ -314,4 +315,3 @@ It seems like the ENGINE part doesn't work too well with CryptoSwift on Win32. A quick test done right before the release showed that trying "openssl speed -engine cswift" generated errors. If the DSO gets enabled, an attempt is made to write at memory address 0x00000002. - diff --git a/README-FIPS.md b/README-FIPS.md index a8be9ddb31..36d9390fa7 100644 --- a/README-FIPS.md +++ b/README-FIPS.md @@ -50,7 +50,7 @@ The FIPS module must have the self tests run, and the FIPS module config file output generated on every machine that it is to be used on. You must not copy the FIPS module config file output data from one machine to another. -On Unix the `openssl fipsinstall` command will be invoked as follows by default: +On Unix, the `openssl fipsinstall` command will be invoked as follows by default: $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so diff --git a/README-PROVIDERS.md b/README-PROVIDERS.md index 33533f671c..3b5476831b 100644 --- a/README-PROVIDERS.md +++ b/README-PROVIDERS.md @@ -15,7 +15,7 @@ Standard Providers Providers are containers for algorithm implementations. Whenever a cryptographic algorithm is used via the high level APIs a provider is selected. It is that provider implementation that actually does the required work. There are five -providers distributed with OpenSSL. In the future we expect third parties to +providers distributed with OpenSSL. In the future, we expect third parties to distribute their own providers which can be added to OpenSSL dynamically. Documentation about writing providers is available on the [provider(7)] manual page. @@ -31,10 +31,10 @@ explicitly (e.g. in the application or via config), then this is the provider that will be used. It is loaded automatically the first time that we try to get an algorithm from a provider if no other provider has been loaded yet. If another provider has already been loaded then it won't be loaded -automatically. Therefore if you want to use it in conjunction with other -providers then you must load it explicitly. +automatically. Therefore, if you want to use it in conjunction with other +providers, then you must load it explicitly. -This is a "built-in" provider which means that it is compiled and linked +This is a "built-in" provider, which means that it is compiled and linked into the libcrypto library and does not exist as a separate standalone module. The Legacy Provider @@ -58,7 +58,7 @@ The FIPS provider contains a sub-set of the algorithm implementations available from the default provider, consisting of algorithms conforming to FIPS standards. It is intended that this provider will be FIPS140-2 validated. -In some cases there may be minor behavioural differences between algorithm +In some cases, there may be minor behavioural differences between algorithm implementations in this provider compared to the equivalent algorithm in the default provider. This is typically in order to conform to FIPS standards. diff --git a/README.md b/README.md index 13790c62c5..379a6c0948 100644 --- a/README.md +++ b/README.md @@ -63,8 +63,8 @@ Source code tarballs of the official releases can be downloaded from The OpenSSL project does not distribute the toolkit in binary form. However, for a large variety of operating systems precompiled versions -of the OpenSSL toolkit are available. In particular on Linux and other -Unix operating systems it is normally recommended to link against the +of the OpenSSL toolkit are available. In particular, on Linux and other +Unix operating systems, it is normally recommended to link against the precompiled shared libraries provided by the distributor or vendor. For Testing and Development @@ -94,7 +94,7 @@ GitHub and clone your public fork instead. git clone https://github.com/yourname/openssl.git -This is necessary, because all development of OpenSSL nowadays is done via +This is necessary because all development of OpenSSL nowadays is done via GitHub pull requests. For more details, see [Contributing](#contributing). Build and Install @@ -133,7 +133,7 @@ Wiki ---- There is a Wiki at [wiki.openssl.org] which is currently not very active. -It contains a lot of useful information, not all of which is up to date. +It contains a lot of useful information, not all of which is up-to-date. License ======= @@ -148,7 +148,7 @@ Support ======= There are various ways to get in touch. The correct channel depends on -your requirement. see the [SUPPORT](SUPPORT.md) file for more details. +your requirement. See the [SUPPORT](SUPPORT.md) file for more details. Contributing ============ @@ -160,7 +160,7 @@ Legalities ========== A number of nations restrict the use or export of cryptography. If you are -potentially subject to such restrictions you should seek legal advice before +potentially subject to such restrictions, you should seek legal advice before attempting to develop or distribute cryptographic code. Copyright