From a888fa7efb0936d6beb88d8ca14686b17fc55c9a Mon Sep 17 00:00:00 2001 From: Mirek Jahoda Date: Thu, 1 Feb 2018 15:47:45 +0100 Subject: [PATCH] Markup issues resolved --- en-US/CXX-Language.adoc | 46 ++++++------ en-US/CXX-Std.adoc | 6 +- en-US/Features-HSM.adoc | 24 +++--- en-US/Features-TLS.adoc | 129 +++++++++++++-------------------- en-US/Go.adoc | 4 +- en-US/Java-LowLevel.adoc | 2 +- en-US/Shell.adoc | 11 ++- en-US/Tasks-Cryptography.adoc | 6 +- en-US/Tasks-Descriptors.adoc | 4 +- en-US/Tasks-Packaging.adoc | 20 ++--- en-US/Tasks-Processes.adoc | 12 +-- en-US/Tasks-Serialization.adoc | 53 ++++++-------- 12 files changed, 140 insertions(+), 177 deletions(-) diff --git a/en-US/CXX-Language.adoc b/en-US/CXX-Language.adoc index 6e505b9..b8643e0 100644 --- a/en-US/CXX-Language.adoc +++ b/en-US/CXX-Language.adoc @@ -31,7 +31,7 @@ overflow manually. For the `new T[n]` example, the size check could be `n || (n > 0 && n > (size_t(-1) - 8) / sizeof(T))`. (See <>.) If there are additional dimensions (which must be constants according to the -C++ standard), these should be included as factors in the +{cpp} standard), these should be included as factors in the divisor. These countermeasures prevent out-of-bounds writes and potential @@ -75,55 +75,59 @@ safety provides a benefit to the programmer. it can be patched in a central place if necessary. The KDE project publishes a document with more extensive -guidelines on ABI-preserving changes to C++ code, link:++https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B++[Policies/Binary -Compatibility Issues With C++] +guidelines on ABI-preserving changes to {cpp} code, link:++https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B++[Policies/Binary +Compatibility Issues With {cpp}] (*d-pointer* refers to the pointer-to-implementation idiom). [[sect-Defensive_Coding-CXX-Language-CXX11]] -===== C++0X and C++11 Support +===== {cpp}0X and {cpp}11 Support GCC offers different language compatibility modes: -* [option]`-std=c++98` for the original 1998 C++ +* [option]`-std=c++98` for the original 1998 {cpp} standard * [option]`-std=c++03` for the 1998 standard with the changes from the TR1 technical report -* [option]`-std=c++11` for the 2011 C++ standard. This +* [option]`-std=c++11` for the 2011 {cpp} standard. This option should not be used. * [option]`-std=c++0x` for several different versions -of C++11 support in development, depending on the GCC +of {cpp}11 support in development, depending on the GCC version. This option should not be used. For each of these flags, there are variants which also enable GNU extensions (mostly language features also found in C99 or -C11): [option]`-std=gnu++98`, -[option]`-std=gnu++03`, [option]`-std=gnu++11`. +C11): + +* [option]`-std=gnu++98` +* [option]`-std=gnu++03` +* [option]`-std=gnu++11` + Again, [option]`-std=gnu++11` should not be used. -If you enable C++11 support, the ABI of the standard C++ library +If you enable {cpp}11 support, the ABI of the standard {cpp} library `libstdc++` will change in subtle ways. -Currently, no C++ libraries are compiled in C++11 mode, so if -you compile your code in C++11 mode, it will be incompatible +Currently, no {cpp} libraries are compiled in {cpp}11 mode, so if +you compile your code in {cpp}11 mode, it will be incompatible with the rest of the system. Unfortunately, this is also the -case if you do not use any C++11 features. Currently, there is -no safe way to enable C++11 mode (except for freestanding +case if you do not use any {cpp}11 features. Currently, there is +no safe way to enable {cpp}11 mode (except for freestanding applications). -The meaning of C++0X mode changed from GCC release to GCC -release. Earlier versions were still ABI-compatible with C++98 -mode, but in the most recent versions, switching to C++0X mode -activates C++11 support, with its compatibility problems. +The meaning of {cpp}0X mode changed from GCC release to GCC +release. Earlier versions were still ABI-compatible with {cpp}98 +mode, but in the most recent versions, switching to {cpp}0X mode +activates {cpp}11 support, with its compatibility problems. -Some C++11 features (or approximations thereof) are available +Some {cpp}11 features (or approximations thereof) are available with TR1 support, that is, with [option]`-std=c++03` or [option]`-std=gnu++03` and in the `` header files. This includes `std::tr1::shared_ptr` (from ``) and `std::tr1::function` (from -``). For other C++11 -features, the Boost C++ library contains replacements. +``). For other {cpp}11 +features, the Boost {cpp} library contains replacements. diff --git a/en-US/CXX-Std.adoc b/en-US/CXX-Std.adoc index 06c3041..1ab2c31 100644 --- a/en-US/CXX-Std.adoc +++ b/en-US/CXX-Std.adoc @@ -94,12 +94,12 @@ if it was initially created as a copy of another string object). Pointers and iterators are also invalidated when non-const member functions are called, or functions with a non-const reference parameter. The behavior of the GCC implementation -deviates from that required by the C++ standard if multiple +deviates from that required by the {cpp} standard if multiple threads are present. In general, only the first call to a non-const member function after a structural modification of the string (such as appending a character) is invalidating, but this also applies to member function such as the non-const version of -`begin()`, in violation of the C++ standard. +`begin()`, in violation of the {cpp} standard. Particular care is necessary when invoking the `c_str()` member function on a temporary @@ -187,4 +187,4 @@ supplied an output area that is too small, and their use should be avoided. These issues make some of the standard library functions -difficult to use correctly, see <>. \ No newline at end of file +difficult to use correctly, see <>. diff --git a/en-US/Features-HSM.adoc b/en-US/Features-HSM.adoc index 72f4cc1..c507a1d 100644 --- a/en-US/Features-HSM.adoc +++ b/en-US/Features-HSM.adoc @@ -57,7 +57,7 @@ modules. This is an uncommon requirement, which has led to several bugs across applications in Fedora which used PKCS#11 directly. To make things more complicated software PKCS#11 module like `softhsm` do not require this re-initialization leading to applications working against software modules but failing with hardware -modules or smart cards. The wrapper PKCS#11 APIs provided by NSS, GNUTLS and +modules or smart cards. The wrapper PKCS#11 APIs provided by NSS, GnuTLS and engine_pkcs11 (OpenSSL) handle the reinitialization after fork requirement transparently. [[sect-Defensive_Coding-HSM-OpenSSL]] @@ -79,18 +79,17 @@ and its usage to sign data. .Signing data with HSM and OpenSSL ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-HSM-OpenSSL.adoc[] - ---- ==== [[sect-Defensive_Coding-HSM-GNUTLS]] -==== GNUTLS HSM Support +==== GnuTLS HSM Support -GNUTLS supports PKCS#11 natively. Most of the API functions +GnuTLS supports PKCS#11 natively. Most of the API functions accepting certificate files, can also accept PKCS#11 URLs, thus requiring minor or no modifications to applications in order to support HSMs. In most cases applications must be modified @@ -103,10 +102,9 @@ and its usage to sign data. .Signing data with HSM and GnuTLS ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-HSM-GNUTLS.adoc[] - ---- ==== @@ -119,10 +117,9 @@ An example PIN callback function is shown below. .An example PIN callback with GNUTLS ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-HSM-GNUTLS-PIN.adoc[] - ---- ==== @@ -146,16 +143,16 @@ The following example demonstrates a typical NSS application for signing. .Signing data with HSM and NSS ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-HSM-NSS.adoc[] - ---- ==== To use the example above with an HSM or smart card you will need to do the following. +[source,bash] ---- # add your HSM or token library to an NSS database (in the sample code the database is @@ -174,10 +171,9 @@ $ NSS_Sign_Example "${token_name}:${cert_name}" .An example PIN callback with NSS ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-HSM-NSS-PIN.adoc[] - ---- -==== \ No newline at end of file +==== diff --git a/en-US/Features-TLS.adoc b/en-US/Features-TLS.adoc index 56c881f..6ac86c7 100644 --- a/en-US/Features-TLS.adoc +++ b/en-US/Features-TLS.adoc @@ -17,7 +17,7 @@ library' documentation. * link:++https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS++[NSS documentation] -* link:++http://www.gnutls.org/manual/++[GNUTLS documentation] +* link:++http://www.gnutls.org/manual/++[GnuTLS documentation] * link:++https://www.openssl.org/docs/++[OpenSSL documentation] @@ -60,10 +60,9 @@ duration of the handshake), or use the Linux-specific .Deactivating the TCP Nagle algorithm ==== -[subs="quotes"] +[source,c] ---- -include::snippets/Features-TLS-Nagle.adoc[] - +include::snippets/Features-TLS-Nagle.adoc[] ---- ==== @@ -132,10 +131,9 @@ due to a connection teardown by the other end). .Obtaining OpenSSL error codes ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-OpenSSL-Errors.adoc[] - ---- ==== @@ -194,11 +192,11 @@ material over documented interfaces. This can significantly increase the part of the code base which has to undergo security certification. -[[sect-Defensive_Coding-TLS-Pitfalls-GNUTLS]] -===== GNUTLS Pitfalls +[[sect-Defensive_Coding-TLS-Pitfalls-GnuTLS]] +===== GnuTLS Pitfalls -Older versions of GNUTLS had several peculiarities described -in previous versions of this guide; as of GNUTLS 3.3.10, these +Older versions of GnuTLS had several peculiarities described +in previous versions of this guide; as of GnuTLS 3.3.10, these issues are no longer applicable. [[sect-Defensive_Coding-TLS-Pitfalls-OpenJDK]] @@ -309,7 +307,7 @@ The OpenSSL library needs explicit initialization (see <>). [[ex-Defensive_Coding-TLS-Client-GNUTLS-Credentials]] -.Initializing a GNUTLS credentials structure +.Initializing a GnuTLS credentials structure ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-Client-GNUTLS-Credentials.adoc[] - ---- ==== @@ -472,10 +464,9 @@ include::snippets/Features-TLS-Client-GNUTLS-Credentials.adoc[] After the last TLS connection has been closed, this credentials object should be freed: -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-GNUTLS-Credentials-Close.adoc[] - ---- During its lifetime, the credentials object can be used to @@ -484,19 +475,18 @@ that it is not changed. Once the TCP connection has been established, the Nagle algorithm should be disabled (see <>). After that, the -socket can be associated with a new GNUTLS session object. +socket can be associated with a new GnuTLS session object. The previously allocated credentials object provides the set of root CAs. Then the TLS handshake must be initiated. This is shown in <>. [[ex-Defensive_Coding-TLS-Client-GNUTLS-Connect]] -.Establishing a TLS client connection using GNUTLS +.Establishing a TLS client connection using GnuTLS ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-Client-GNUTLS-Connect.adoc[] - ---- ==== @@ -510,13 +500,12 @@ user-specific trust store can be checked. This function call can be omitted if the functionality is not needed. [[ex-Defensive_Coding-TLS-Client-GNUTLS-Verify]] -.Verifying a server certificate using GNUTLS +.Verifying a server certificate using GnuTLS ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-Client-GNUTLS-Verify.adoc[] - ---- ==== @@ -525,13 +514,12 @@ An established TLS session can be used for sending and receiving data, as in <>. [[ex-Defensive_Coding-TLS-GNUTLS-Use]] -.Using a GNUTLS session +.Using a GnuTLS session ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-GNUTLS-Use.adoc[] - ---- ==== @@ -542,13 +530,12 @@ Finally, the session object can be deallocated using `gnutls_deinit` (see <>). [[ex-Defensive_Coding-TLS-GNUTLS-Disconnect]] -.Closing a GNUTLS session in an orderly fashion +.Closing a GnuTLS session in an orderly fashion ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-GNUTLS-Disconnect.adoc[] - ---- ==== @@ -559,7 +546,7 @@ include::snippets/Features-TLS-GNUTLS-Disconnect.adoc[] The examples below use the following cryptographic-related classes: -[subs="quotes"] +[source,java] ---- include::snippets/Features-TLS-Client-OpenJDK-Import.adoc[] @@ -587,14 +574,12 @@ OpenJDK{nbsp}6, the `TLSv1` provider has to be supported as a fall-back option. This is shown in <>. [[ex-Defensive_Coding-TLS-Client-OpenJDK-Context]] -.Setting up an `SSLContext` for OpenJDK TLS - clients +.Setting up an `SSLContext` for OpenJDK TLS clients ==== -[subs="quotes"] +[source,java] ---- include::snippets/Features-TLS-Client-OpenJDK-Context.adoc[] - ---- ==== @@ -605,14 +590,12 @@ the context, these parameters can be reused for multiple TLS connections. [[ex-Defensive_Coding-TLS-OpenJDK-Parameters]] -.Setting up `SSLParameters` for TLS use - with OpenJDK +.Setting up `SSLParameters` for TLS use with OpenJDK ==== -[subs="quotes"] +[source,java] ---- include::snippets/Features-TLS-OpenJDK-Parameters.adoc[] - ---- ==== @@ -621,10 +604,9 @@ As initialized above, the parameter object does not yet require host name checking. This has to be enabled separately, and this is only supported by OpenJDK 7 and later: -[subs="quotes"] +[source,java] ---- include::snippets/Features-TLS-Client-OpenJDK-Hostname.adoc[] - ---- All application protocols can use the @@ -645,10 +627,9 @@ internal API on OpenJDK 6. .Establishing a TLS connection with OpenJDK ==== -[subs="quotes"] +[source,java] ---- include::snippets/Features-TLS-Client-OpenJDK-Connect.adoc[] - ---- ==== @@ -667,10 +648,9 @@ The TLS socket can be used as a regular socket, as shown in .Using a TLS client socket in OpenJDK ==== -[subs="quotes"] +[source,java] ---- include::snippets/Features-TLS-Client-OpenJDK-Use.adoc[] - ---- ==== @@ -693,10 +673,9 @@ the server certificate is identified by its SHA-256 hash. .A customer trust manager for OpenJDK TLS clients ==== -[subs="quotes"] +[source,java] ---- include::snippets/Features-TLS-Client-OpenJDK-MyTrustManager.adoc[] - ---- ==== @@ -709,9 +688,9 @@ This trust manager has to be passed to the .Using a custom TLS trust manager with OpenJDK ==== +[source,java] ---- include::snippets/Features-TLS-Client-OpenJDK-Context_For_Cert.adoc[] - ---- ==== @@ -754,10 +733,9 @@ Using NSS needs several header files, as shown in .Include files for NSS ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-NSS-Includes.adoc[] - ---- ==== @@ -781,7 +759,7 @@ load trusted CA certificates from a file.) .Initializing the NSS library ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-NSS-Init.adoc[] @@ -792,10 +770,9 @@ include::snippets/Features-TLS-NSS-Init.adoc[] Some of the effects of the initialization can be reverted with the following function calls: -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-NSS-Close.adoc[] - ---- After NSS has been initialized, the TLS connection can be @@ -829,10 +806,9 @@ certificate is verified and matched against the host name. .Creating a TLS connection with NSS ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-Client-NSS-Connect.adoc[] - ---- ==== @@ -844,10 +820,9 @@ the NSPR descriptor to communicate with the server. .Using NSS for sending and receiving data ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-NSS-Use.adoc[] - ---- ==== @@ -859,7 +834,7 @@ shows how to close the connection. .Closing NSS client connections ==== -[subs="quotes"] +[source,c] ---- include::snippets/Features-TLS-Client-NSS-Close.adoc[] @@ -897,13 +872,12 @@ shows how to implement certificate matching, using the parsed certificate returned by `getpeercert`. [[ex-Defensive_Coding-TLS-Client-Python-check_host_name]] -.Implementing TLS host name checking Python (without - wildcard support) +.Implementing TLS host name checking Python (without wildcard support) ==== +[source,python] ---- include::snippets/Features-TLS-Client-Python-check_host_name.adoc[] - ---- ==== @@ -947,10 +921,9 @@ manually against the host name, by calling the .Establishing a TLS client connection with Python ==== -[subs="quotes"] +[source,python] ---- include::snippets/Features-TLS-Client-Python-Connect.adoc[] - ---- ==== @@ -958,16 +931,14 @@ include::snippets/Features-TLS-Client-Python-Connect.adoc[] After the connection has been established, the TLS socket can be used like a regular socket: -[subs="quotes"] +[source,python] ---- include::snippets/Features-TLS-Python-Use.adoc[] - ---- Closing the TLS socket is straightforward as well: -[subs="quotes"] +[source,python] ---- include::snippets/Features-TLS-Python-Close.adoc[] - ----- \ No newline at end of file +---- diff --git a/en-US/Go.adoc b/en-US/Go.adoc index 546f631..9c2911d 100644 --- a/en-US/Go.adoc +++ b/en-US/Go.adoc @@ -51,6 +51,7 @@ details. .Regular error handling in Go ==== +[source,go] ---- include::snippets/Go-Error_Handling-Regular.adoc[] @@ -70,6 +71,7 @@ returning both data and an error at the same time. .Read error handling in Go ==== +[source,go] ---- include::snippets/Go-Error_Handling-IO.adoc[] @@ -105,4 +107,4 @@ During deserialization, missing value do not result in an error, but the original value is preserved. Using a fresh value (with suitable default values if necessary) ensures that data from a previous deserialization operation does not leak into the current -one. This is especially relevant when structs are deserialized. \ No newline at end of file +one. This is especially relevant when structs are deserialized. diff --git a/en-US/Java-LowLevel.adoc b/en-US/Java-LowLevel.adoc index e33f446..7bf9a3e 100644 --- a/en-US/Java-LowLevel.adoc +++ b/en-US/Java-LowLevel.adoc @@ -5,7 +5,7 @@ ==== Low-level Features of the Virtual Machine [[sect-Defensive_Coding-Java-Reflection]] -===== `Reflection and Private Parts` +===== Reflection and Private Parts The `setAccessible(boolean)` method of the `java.lang.reflect.AccessibleObject` class diff --git a/en-US/Shell.adoc b/en-US/Shell.adoc index 04e535c..0e03951 100644 --- a/en-US/Shell.adoc +++ b/en-US/Shell.adoc @@ -49,7 +49,7 @@ most basic syntax is In almost all cases, a parameter expansion should be enclosed in double quotation marks `"`pass:attributes[{blank}]…pass:attributes[{blank}]`"`. -[subs="quotes"] +[source,bash] ---- external-program "$arg1" "$arg2" @@ -184,6 +184,7 @@ inputs, refer to <>. [application]*bash* supports explicit type declarations for shell variables: +[source,bash] ---- declare -i integer_variable @@ -207,6 +208,7 @@ declarations for shell variables: Variables can also be declared as arrays by assigning them an array expression, as in: +[source,bash] ---- array_variable=(1 2 3 4) @@ -314,7 +316,7 @@ variables. .Creating and Cleaning up Temporary Files ==== -[subs="quotes"] +[source,bash] ---- tmpfile="$(mktemp)" @@ -346,6 +348,7 @@ POSIX shells. .Input validation in [application]*bash* ==== +[source,bash] ---- include::snippets/Shell-Input_Validation.adoc[] @@ -380,7 +383,7 @@ into a `main` function, and invoking the `main` function at the end of the script, using this syntax: -[subs="quotes"] +[source,bash] ---- main "$@" ; exit $? @@ -389,4 +392,4 @@ main "$@" ; exit $? This construct ensures that [application]*bash* will stop execution after the `main` function, instead -of opening the script file and trying to read more commands. \ No newline at end of file +of opening the script file and trying to read more commands. diff --git a/en-US/Tasks-Cryptography.adoc b/en-US/Tasks-Cryptography.adoc index 685607e..9722e0e 100644 --- a/en-US/Tasks-Cryptography.adoc +++ b/en-US/Tasks-Cryptography.adoc @@ -9,7 +9,7 @@ Choosing from the following cryptographic primitives is recommended: -* RSA with 2048 bit keys and OAEP or PSS +* RSA with 2048-bit keys and OAEP or PSS padding * AES-128 in CBC mode @@ -34,7 +34,7 @@ and legacy padding * AES-192 -* 3DES (triple DES, with two or three 56 bit keys), +* 3DES (triple DES, with two or three 56-bit keys), but strongly discouraged * RC4 (but very, very strongly discouraged) @@ -129,4 +129,4 @@ Other sources of randomness should be considered predictable. Generating randomness for cryptographic keys in long-term use may need different steps and is best left to cryptographic -libraries. \ No newline at end of file +libraries. diff --git a/en-US/Tasks-Descriptors.adoc b/en-US/Tasks-Descriptors.adoc index 727a291..933d6db 100644 --- a/en-US/Tasks-Descriptors.adoc +++ b/en-US/Tasks-Descriptors.adoc @@ -195,7 +195,7 @@ flag. * Before doing anything else with the descriptor `fd`, invoke: -+ +[source,c] ---- int newfd = fcntl(fd, F_DUPFD_CLOEXEC, (long)FD_SETSIZE); @@ -213,4 +213,4 @@ The new descriptor has been allocated above the `FD_SETSIZE`. Even though this algorithm is racy in the sense that the `FD_SETSIZE` first descriptors could fill up, a very high degree of -physical parallelism is required before this becomes a problem. \ No newline at end of file +physical parallelism is required before this becomes a problem. diff --git a/en-US/Tasks-Packaging.adoc b/en-US/Tasks-Packaging.adoc index 6a3254b..37fafb6 100644 --- a/en-US/Tasks-Packaging.adoc +++ b/en-US/Tasks-Packaging.adoc @@ -41,15 +41,14 @@ In the spec file, we define two RPM variables which contain the names of the files used to store the private and public key, and the user name for the service: +[source,bash] ---- - # Name of the user owning the file with the private key %define tlsuser %{name} # Name of the directory which contains the key and certificate files %define tlsdir %{_sysconfdir}/%{name} %define tlskey %{tlsdir}/%{name}.key -%define tlscert %{tlsdir}/%{name}.crt - +%define tlscert %{tlsdir}/%{name}.crt ---- These variables likely need adjustment based on the needs of the @@ -69,8 +68,8 @@ login shell for the user has been disabled. .Creating a key pair in a user-owned directory ==== +[source,bash] ---- - %post if [ $1 -eq 1 ] ; then if ! test -e %{tlskey} ; then @@ -90,8 +89,7 @@ fi %files %dir %attr(0755,%{tlsuser},%{tlsuser]) %{tlsdir} %ghost %attr(0600,%{tlsuser},%{tlsuser}) %config(noreplace) %{tlskey} -%ghost %attr(0644,%{tlsuser},%{tlsuser}) %config(noreplace) %{tlscert} - +%ghost %attr(0644,%{tlsuser},%{tlsuser}) %config(noreplace) %{tlscert} ---- ==== @@ -112,8 +110,8 @@ If the *directory* .Creating a key pair in a `root`-owned directory ==== +[source,bash] ---- - %post if [ $1 -eq 1 ] ; then if ! test -e %{tlskey} ; then @@ -130,8 +128,7 @@ fi %files %dir %attr(0755,root,root]) %{tlsdir} %ghost %attr(0600,%{tlsuser},%{tlsuser}) %config(noreplace) %{tlskey} -%ghost %attr(0644,root,root) %config(noreplace) %{tlscert} - +%ghost %attr(0644,root,root) %config(noreplace) %{tlscert} ---- ==== @@ -146,8 +143,7 @@ is needed for the [application]*su* or [application]*chmod* invocation. [[sect-Defensive_Coding-Tasks-Packaging-Certificates-Service]] -==== Generating X.509 Self-signed Certificates before Service - Start +==== Generating X.509 Self-signed Certificates before Service Start An alternative way to automatically provide an X.509 key pair is to create it just before the service is started for the first @@ -181,4 +177,4 @@ later at run time, and generally results in a poor user experience. The requirements for generating such keys is documented at -link:++https://fedoraproject.org/wiki/Packaging:Initial_Service_Setup#Generating_Self-Signed_Certificates++[Packaging:Initial Service Setup]. \ No newline at end of file +link:++https://fedoraproject.org/wiki/Packaging:Initial_Service_Setup#Generating_Self-Signed_Certificates++[Packaging:Initial Service Setup]. diff --git a/en-US/Tasks-Processes.adoc b/en-US/Tasks-Processes.adoc index b382968..7a6a6b0 100644 --- a/en-US/Tasks-Processes.adoc +++ b/en-US/Tasks-Processes.adoc @@ -12,8 +12,7 @@ This section describes how to create new child processes in a safe manner. In addition to the concerns addressed below, there is the possibility of file descriptor leaks, see <>. -===== Obtaining the Program Path and the Command-line - Template +===== Obtaining the Program Path and the Command-line Template The name and path to the program being invoked should be hard-coded or controlled by a static configuration file stored @@ -236,8 +235,7 @@ termination of the child process using and hope that the status is not collected by an event loop first. -==== `SUID`pass:attributes[{blank}]/pass:attributes[{blank}]`SGID` - processes +==== `SUID`pass:attributes[{blank}]/pass:attributes[{blank}]`SGID` processes Programs can be marked in the file system to indicate to the kernel that a trust transition should happen if the program is @@ -294,8 +292,8 @@ Either the `secure_getenv` function or the .Obtaining a definition for `secure_getenv` ==== +[source,c] ---- - #include #ifndef HAVE_SECURE_GETENV @@ -305,8 +303,6 @@ Either the `secure_getenv` function or the # error neither secure_getenv nor __secure_getenv are available # endif #endif - - ---- ==== @@ -378,4 +374,4 @@ followed by a call to `execve` (perhaps after rearranging and closing file descriptors) is typically unsafe, especially from a library which does not control the state of the entire process. Such use of `fork` -should be replaced with proper child processes or threads. \ No newline at end of file +should be replaced with proper child processes or threads. diff --git a/en-US/Tasks-Serialization.adoc b/en-US/Tasks-Serialization.adoc index 110c57e..3ec873b 100644 --- a/en-US/Tasks-Serialization.adoc +++ b/en-US/Tasks-Serialization.adoc @@ -197,9 +197,9 @@ in various places. [source,xml] ---- -<!DOCTYPE html PUBLIC + ---- @@ -208,7 +208,7 @@ in various places. [source,xml] ---- -<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> + ---- @@ -217,9 +217,9 @@ in various places. [source,xml] ---- -<!ENTITY sys SYSTEM "http://www.example.com/ent.adoc[]> -<!ENTITY pub PUBLIC "-//Example//Public Entity//EN" - "http://www.example.com/pub-ent.adoc[]> + + ---- @@ -228,7 +228,7 @@ in various places. [source,xml] ---- -<!NOTATION not SYSTEM "../not.adoc[]> + ---- @@ -306,7 +306,7 @@ problems related to that. .Disabling XML entity processing with Expat ==== -[source,xml] +[source,java] ---- include::snippets/Tasks-Serialization-XML-Expat-EntityDeclHandler.adoc[] @@ -321,7 +321,7 @@ This handler must be installed when the .Creating an Expat XML parser ==== -[source,xml] +[source,java] ---- include::snippets/Tasks-Serialization-XML-Expat-Create.adoc[] @@ -354,7 +354,7 @@ parsing to stop when encountering entity declarations. .A QtXml entity handler which blocks entity processing ==== -[source,xml] +[source,java] ---- include::snippets/Tasks-Serialization-XML-Qt-NoEntityHandler.adoc[] @@ -375,7 +375,7 @@ may need adjusting. .A QtXml XML reader which blocks entity processing ==== -[source,xml] +[source,java] ---- include::snippets/Tasks-Serialization-XML-Qt-NoEntityReader.adoc[] @@ -397,7 +397,7 @@ return value and report any error. .Parsing an XML document with QDomDocument, without entity expansion ==== -[source,xml] +[source,java] ---- include::snippets/Tasks-Serialization-XML-Qt-QDomDocument.adoc[] @@ -437,14 +437,12 @@ include::snippets/Tasks-Serialization-XML-OpenJDK-NoEntityResolver.adoc[] ==== [[ex-Defensive_Coding-Tasks-Serialization-XML-OpenJDK-NoResourceResolver]] -.Helper class to prevent schema resolution in - OpenJDK +.Helper class to prevent schema resolution in OpenJDK ==== -[subs="quotes"] +[source,java] ---- -include::snippets/Tasks-Serialization-XML-OpenJDK-NoResourceResolver.adoc[] - +include::snippets/Tasks-Serialization-XML-OpenJDK-NoResourceResolver.adoc[] ---- ==== @@ -456,10 +454,9 @@ shows the imports used by the examples. .Java imports for OpenJDK XML parsing ==== -[subs="quotes"] +[source,java] ---- -include::snippets/Tasks-Serialization-XML-OpenJDK-Imports.adoc[] - +include::snippets/Tasks-Serialization-XML-OpenJDK-Imports.adoc[] ---- ==== @@ -477,9 +474,9 @@ instance in the `inputStream` variable. .DOM-based XML parsing in OpenJDK ==== +[source,java] ---- -include::snippets/Tasks-Serialization-XML-OpenJDK_Parse-DOM.adoc[] - +include::snippets/Tasks-Serialization-XML-OpenJDK_Parse-DOM.adoc[] ---- ==== @@ -506,13 +503,12 @@ using a SAX-based approach. The XML data is read from an `inputStream` variable. [[ex-Defensive_Coding-Tasks-Serialization-XML-OpenJDK_Parse-XMLSchema_SAX]] -.SAX-based validation against an XML schema in - OpenJDK +.SAX-based validation against an XML schema in OpenJDK ==== +[source,java] ---- -include::snippets/Tasks-Serialization-XML-OpenJDK_Parse-XMLSchema_SAX.adoc[] - +include::snippets/Tasks-Serialization-XML-OpenJDK_Parse-XMLSchema_SAX.adoc[] ---- ==== @@ -530,13 +526,12 @@ to perform the schema-based validation on the `document`. [[ex-Defensive_Coding-Tasks-Serialization-XML-OpenJDK_Parse-XMLSchema_DOM]] -.Validation of a DOM document against an XML schema in - OpenJDK +.Validation of a DOM document against an XML schema in OpenJDK ==== +[source,java] ---- include::snippets/Tasks-Serialization-XML-OpenJDK_Parse-XMLSchema_DOM.adoc[] - ---- ====