(xmlsec-docs) Fixed typos and corrected minor mistakes

docs/md/c14n.md

@@ -1,13 +1,12 @@
 # XML Security Library: Canonical XML / Exclusive Canonical XML
 
-Both [XML Signature](http://www.w3.org/TR/xmldsig-core) and
-[XML Encryption](http://www.w3.org/TR/xmlenc-core/) use XML Canonicalization
+[XML Signature](http://www.w3.org/TR/xmldsig-core) uses the XML Canonicalization
 standards to produce the canonical form of the original XML document. Except for
 limitations regarding a few unusual cases, if two documents have the same
 canonical form, then the two documents are logically equivalent within the
-given application context. Implementations of both these standards were included
-in the LibXML2 library because these algorithms could be of interest to other
-applications as well.
+given application context. Implementations of the Canonical XML and Exclusive
+Canonical XML algorithms were included in the LibXML2 library because they
+could be of interest to other applications as well.
 
 - [Canonical XML 1.0](http://www.w3.org/TR/xml-c14n) (included in the LibXML2 library)
 - [Exclusive Canonical XML 1.0](http://www.w3.org/TR/xml-exc-c14n) (included in the LibXML2 library)

docs/md/download.md

@@ -33,7 +33,7 @@ the following cryptographic libraries:
 | XML Security Library | Cryptographic library | Notes |
 |---|---|---|
 | **xmlsec-openssl** with OpenSSL| [OpenSSL](http://www.openssl.org/) version 3.0.13 or newer. | **OpenSSL 3.5.0 or newer is recommended** (supports all REQUIRED and all RECOMMENDED [XML Digital Signature 1.1](xmldsig.md) and [XML Encryption 1.1](xmlenc.md) algorithms).|
-| **xmlsec-openssl** with OpenSSL forks| [AWS-LC](https://github.com/aws/aws-lc) v1.66.0 or newer; [LibreSSL](https://www.libressl.org/) version 3.9.0 or newer; [BoringSSL](https://boringssl.googlesource.com/boringssl/) version 1.1.0 or newer.| Some of the OpenSSL forks do not have a stable API (e.g. BoringSSL) and the latest versions of the libraries might not work with XML Security Library. |
+| **xmlsec-openssl** with OpenSSL forks| [AWS-LC](https://github.com/aws/aws-lc) v1.63.0 or newer; [LibreSSL](https://www.libressl.org/) version 3.9.0 or newer; [BoringSSL](https://boringssl.googlesource.com/boringssl/) version 1.1.0 or newer.| Some of the OpenSSL forks do not have a stable API (e.g. BoringSSL) and the latest versions of the libraries might not work with XML Security Library. |
 | **xmlsec-nss** | [NSS](http://www.mozilla.org/projects/security/pki/nss/) (Mozilla cryptographic library) 3.91 or newer | Requires [NSPR](https://firefox-source-docs.mozilla.org/nspr/index.html) 4.34.1 or newer |
 | **xmlsec-gnutls** | [GnuTLS](http://www.gnu.org/software/gnutls/) 3.8.3 or newer | Supports multiple cryptographic backends; the exact feature set for xmlsec-gnutls depends on the backend in use. |
 | **xmlsec-mscng** | [Microsoft Cryptography API: Next Generation](https://learn.microsoft.com/en-us/windows/win32/seccng/cng-portal) (requires Windows 7, Windows Server 2008 R2, or newer) | xmlsec-mscng is the recommended version on the Windows platform. |

docs/md/tutorial/compiling-and-linking.md

@@ -118,6 +118,13 @@ clean:
 	@rm -rf $(PROGRAM)
 ```
 
+Note: the `xmlsec1` pkg-config package enables dynamic loading of the
+crypto library only when the XML Security Library itself is built with
+dynamic crypto library loading enabled. When built without it, `xmlsec1.pc`
+is a symlink to the `xmlsec1-<default-crypto>.pc` file, so the application
+is linked directly against the default crypto backend (and no dynamic
+loading takes place).
+
 ### xmlsec1-config script
 
 #### Example: xmlsec1-config to select GnuTLS at link time
@@ -217,8 +224,9 @@ dynamic linking, and debug vs release builds. The
 rule is simple: ***exactly the same runtime MUST be used throughout
 the application (including all dependencies)***.
 
-By default, `configure.ps1` uses the `/MD` (non-debug version of 
-the multithreaded DLL runtime) runtime libraries. 
+By default, `configure.ps1` uses the `/MD` (non-debug version of
+the multithreaded DLL runtime) runtime libraries, or `/MDd` for
+debug builds.
 Use the `cruntime=<new runtime>` option to change it (see the XML Security
 Library [installation tutorial](install.md) for more details).
 

docs/md/tutorial/creating-templates.md

@@ -74,7 +74,11 @@ create_signature_template(xmlDocPtr doc){
     }
 
     /* add <dsig:Signature/> node to the doc */
-    xmlAddChild(xmlDocGetRootElement(doc), signNode);
+    if(xmlAddChild(xmlDocGetRootElement(doc), signNode) == NULL) {
+        fprintf(stderr, "Error: failed to add signature node to the document\n");
+        xmlFreeNode(signNode);
+        return(NULL);
+    }
 
     /* add <dsig:Reference/> node */
     refNode = xmlSecTmplSignatureAddReference(signNode, xmlSecTransformSha256Id, NULL, BAD_CAST "", NULL);
@@ -166,22 +170,27 @@ create_encryption_template(xmlDocPtr doc) {
     /* add <enc:CipherValue/> node */
     if(xmlSecTmplEncDataEnsureCipherValue(encDataNode) == NULL) {
         fprintf(stderr, "Error: failed to add CipherValue node\n");
-        return(NULL);
+        goto done;
     }
 
     /* add <dsig:KeyInfo/> and <dsig:KeyName/> nodes to put key name in the encrypted document */
     keyInfoNode = xmlSecTmplEncDataEnsureKeyInfo(encDataNode, NULL);
     if(keyInfoNode == NULL) {
         fprintf(stderr, "Error: failed to add key info\n");
-        return(NULL);
+        goto done;
     }
     if(xmlSecTmplKeyInfoAddKeyName(keyInfoNode, NULL) == NULL) {
         fprintf(stderr, "Error: failed to add key name\n");
-        return(NULL);
+        goto done;
     }
 
-    /* done */
+    /* success */
     return(encDataNode);
+
+done:
+    /* free the partially created template node and its subtree */
+    xmlFreeNode(encDataNode);
+    return(NULL);
 }
 ```
 [Full program listing](../examples/encrypt2.md)

docs/md/tutorial/index.md

@@ -50,8 +50,8 @@ xmlsec-gnutls, xmlsec-gcrypt, xmlsec-nss, ...).
 ![The library structure and dependencies](images/structure.png)
 
 The core library has no dependencies on any crypto library and
-implements all engines as well as all non-crypto transforms (XML
-parser, C14N transforms, XPath and XSLT transforms, ...). The XML
+implements all non-crypto transforms (XML parser, C14N transforms,
+XPath and XSLT transforms, ...). The XML
 Security Crypto library implements crypto transforms, crypto key data,
 and key data stores. An application links against a particular XML
 Security Crypto library (or even multiple libraries), but the

docs/md/tutorial/install.md

@@ -9,7 +9,7 @@ And at least one of the following cryptographic libraries:
 - [OpenSSL](https://www.openssl.org) >= 3.0.13 (>= 3.5.0 is recommended)
 - [LibreSSL](https://www.libressl.org/) >= 3.9.0
 - [BoringSSL](https://boringssl.googlesource.com/boringssl/) >= 1.1.0
-- [AWS-LC](https://github.com/aws/aws-lc) >= 1.66.0
+- [AWS-LC](https://github.com/aws/aws-lc) >= 1.63.0
 - [NSS](https://firefox-source-docs.mozilla.org/security/nss/index.html) >= 3.91 (with [NSPR](https://firefox-source-docs.mozilla.org/nspr/index.html) >= 4.34.1)
 - [GnuTLS](https://www.gnutls.org/) >= 3.8.3
 - [Microsoft Cryptography API: Next Generation (CNG)](https://learn.microsoft.com/en-us/windows/win32/seccng/cng-portal)
@@ -27,7 +27,7 @@ apt install automake autoconf libtool libtool-bin gcc
 apt install libltdl7 libltdl-dev
 
 # core libxml2 and libxslt libraries
-apt install libxml2 libxml2-dev libxslt1.1 libxslt1-dev
+apt install libxml2-dev libxslt1.1 libxslt1-dev
 
 # openssl libraries
 apt install openssl libssl-dev

docs/md/tutorial/sign-and-encrypt.md

@@ -112,7 +112,10 @@ sign_file(const char* tmpl_file, const char* key_file, const char* key_name) {
     }
 
     /* print signed document to stdout */
-    xmlDocDump(stdout, doc);
+    if(xmlDocDump(stdout, doc) < 0) {
+        fprintf(stderr, "Error: failed to write the signed document to stdout\n");
+        goto done;
+    }
 
     /* success */
     res = 0;
@@ -226,7 +229,10 @@ encrypt_file(const char* tmpl_file, const char* key_file,
     }
 
     /* print encrypted data with the document to stdout */
-    xmlDocDump(stdout, doc);
+    if(xmlDocDump(stdout, doc) < 0) {
+        fprintf(stderr, "Error: failed to write the encrypted document to stdout\n");
+        goto done;
+    }
 
     /* success */
     res = 0;

docs/md/tutorial/using-keysmngr.md

@@ -199,9 +199,9 @@ create_files_keys_mngr(void) {
 
 /******************************************************************************
  *
- * Files Keys Store: we assume that key's name (content of the
- * <dsig:KeyName/> element is a name of the file with a key (in the
- * current folder).
+ * Files Keys Store: we assume that the key name (content of the
+ * <dsig:KeyName/> or <xenc:KeyName/> element) is a name of the file
+ * with a key in the current folder.
  * Attention: this is probably not a good solution for high traffic systems.
  *
   *****************************************************************************/

docs/md/xmldsig.md

@@ -117,7 +117,7 @@ XML Security library supports the following features as defined in
 | [The RSAKeyValue Element](https://www.w3.org/TR/xmldsig-core1/#sec-RSAKeyValue) | Optional | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) |
 | [The ECKeyValue Element](https://www.w3.org/TR/xmldsig-core/#sec-ECKeyValue) | Optional | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | No | Yes |
 | [The X509Data Element](https://www.w3.org/TR/xmldsig-core1/#sec-X509Data) | Optional | Yes | Yes | Yes | Yes | Yes | No |
-| [The X509Digest Element](https://www.w3.org/TR/xmldsig-core1/#sec-X509Data) | Optional | Yes | Yes | Yes | Yes [(7)](#mscng-limited-x509-digest) | No | No |
+| [The X509Digest Element](https://www.w3.org/TR/xmldsig-core1/#sec-X509Data) | Optional | Yes | Yes | Yes | Yes [(7)](#mscng-limited-x509-digest) | Yes [(15)](#mscrypto-x509-digest-write-only) | No |
 | [The PGPData Element](https://www.w3.org/TR/xmldsig-core1/#sec-PGPData) | Optional | No | No | No | No | No | No |
 | [The SPKIData Element](https://www.w3.org/TR/xmldsig-core1/#sec-SPKIData) | Optional | No | No | No | No | No | No |
 | [The DEREncodedKeyValue Element](https://www.w3.org/TR/xmldsig-core1/#sec-DEREncodedKeyValue) | Optional | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) | Yes [(13)](#keydata-runtime) [(11)](#only-x25519) | No | No |
@@ -138,6 +138,7 @@ XML Security library supports the following features as defined in
 12. <a id="openssl35-required"></a> Requires OpenSSL 3.5.0 or newer.
 13. <a id="keydata-runtime"></a> The feature is disabled by default but can be enabled at runtime (for example, with the `xmlsec --enabled-key-data` command line option).
 14. <a id="gnutls-eddsa-limited"></a> Only Ed25519 and Ed448 are supported; the Ed25519ctx, Ed25519ph and Ed448ph variants are not supported.
+15. <a id="mscrypto-x509-digest-write-only"></a> MSCrypto can only write the X509Digest element (i.e. it is supported when creating a signature); the key cannot be resolved from the X509Digest element during verification.
 
 ### Test vectors
 

docs/md/xmlenc.md

@@ -70,7 +70,7 @@ XML Security library supports the following features as defined in
 | [Elliptic Curve Diffie-Hellman (ECDH)](https://www.w3.org/TR/xmlenc-core1/#sec-ECDH-ES) | Required | Yes [(3)](#openssl3-required) | Yes | Yes | Yes [(5)](#new-windows-required) | No | No |
 | [XDH Key Agreement](https://www.w3.org/2021/04/xmldsig-more) (X25519, X448) | Optional | Yes [(3)](#openssl3-required) | Yes [(9)](#x25519-only) | Yes | Yes [(9)](#x25519-only) | No | No |
 | [Diffie-Hellman with legacy KDF](https://www.w3.org/TR/xmlenc-core1/#sec-DHKeyAgreement) | Optional | No | No | No | No | No | No |
-| [Diffie-Hellman with explicit KDF](https://www.w3.org/TR/xmlenc-core1/#sec-DHKeyAgreement) | Optional | Yes [(3)](#openssl3-required) [(8)](#dhx-only) | No | No | Yes [(8)](#dhx-only) | No | No |
+| [Diffie-Hellman with explicit KDF](https://www.w3.org/TR/xmlenc-core1/#sec-DHKeyAgreement) | Optional | Yes [(3)](#openssl3-required) [(12)](#openssl-dh-key-formats) | No | No | Yes [(8)](#dhx-only) | No | No |
 | **Key Encapsulation** [(1)](#feature-disabled) | EXPERIMENTAL | | | | | | |
 | ML-KEM-512 | EXPERIMENTAL | Yes [(1)](#feature-disabled) [(10)](#openssl35-required) | No | No | No | No | No |
 | ML-KEM-768 | EXPERIMENTAL | Yes [(1)](#feature-disabled) [(10)](#openssl35-required) | No | No | No | No | No |
@@ -91,6 +91,7 @@ XML Security library supports the following features as defined in
 9. <a id="x25519-only"></a> Only X25519 (Curve25519) is supported, the X448 (Curve448) is not supported.
 10. <a id="openssl35-required"></a> Requires OpenSSL 3.5.0 or newer.
 11. <a id="stream-algorithms"></a> The XML Encryption Core specification defines no specific stream encryption algorithm; xmlsec implements ChaCha20 and ChaCha20-Poly1305 (see the rows above, xmldsig-more identifiers).
+12. <a id="openssl-dh-key-formats"></a> Both the PKCS#3 and X9.42 (DHX) DH key formats are accepted.
 
 ### Test vectors
 

examples/decrypt3.c

@@ -176,7 +176,11 @@ decrypt_file(xmlSecKeysMngrPtr mngr, const char* enc_file) {
     assert(enc_file);
 
     /* load encrypted file */
+#if LIBXML_VERSION >= 21300
+    doc = xmlReadFile(enc_file, NULL, XML_PARSE_PEDANTIC | XML_PARSE_NONET | XML_PARSE_NOENT | XML_PARSE_NO_XXE);
+#else /* LIBXML_VERSION >= 21300 */
     doc = xmlReadFile(enc_file, NULL, XML_PARSE_PEDANTIC | XML_PARSE_NONET | XML_PARSE_NOENT);
+#endif /* LIBXML_VERSION >= 21300 */
     if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
         fprintf(stderr, "Error: unable to parse file \"%s\"\n", enc_file);
         goto done;

examples/verify-saml.c

@@ -8,9 +8,10 @@
 /**
  * @brief XML Security Library example: Verifying a simple SAML response with an X509 certificate
  * @details Verifies a simple SAML response. In addition to regular verification
- * it also ensures that the signature has only one <dsig:Reference/> element
- * with an empty or NULL URI attribute and one enveloped signature transform
- * as required by the SAML specification.
+ * it also ensures that the <dsig:Signature/> element is a direct child of the
+ * SAML Response element, that the signature has only one <dsig:Reference/>
+ * element with an empty or NULL URI attribute and one enveloped signature
+ * transform, as required by the SAML specification.
  *
  * This example was developed and tested with OpenSSL crypto library. The
  * certificate management policies for another crypto library may break it.
@@ -248,12 +249,18 @@ verify_file(xmlSecKeysMngrPtr mngr, const char* xml_file) {
         goto done;
     }
 
-    /* find start node */
+    /* find start node; per the SAML specification the signature must be a
+     * direct child of the signed element, so the <dsig:Signature/> node
+     * must be a direct child of the SAML Response (the document root) */
     node = xmlSecFindNode(xmlDocGetRootElement(doc), xmlSecNodeSignature, xmlSecDSigNs);
     if(node == NULL) {
         fprintf(stderr, "Error: start node not found in \"%s\"\n", xml_file);
         goto done;
     }
+    if(node->parent != (xmlNodePtr)xmlDocGetRootElement(doc)) {
+        fprintf(stderr, "Error: the signature node is not a direct child of the SAML response\n");
+        goto done;
+    }
 
     /* create signature context */
     dsigCtx = xmlSecDSigCtxCreate(mngr);

examples/verify1.c

@@ -68,6 +68,10 @@ main(int argc, char **argv) {
 #ifndef XMLSEC_NO_XSLT
     /* disable all XSLT file and network access */
     xsltSecPrefs = xsltNewSecurityPrefs();
+    if(xsltSecPrefs == NULL) {
+        fprintf(stderr, "Error: failed to create the xslt security prefs\n");
+        goto done;
+    }
     xsltSetSecurityPrefs(xsltSecPrefs,  XSLT_SECPREF_READ_FILE,        xsltSecurityForbid);
     xsltSetSecurityPrefs(xsltSecPrefs,  XSLT_SECPREF_WRITE_FILE,       xsltSecurityForbid);
     xsltSetSecurityPrefs(xsltSecPrefs,  XSLT_SECPREF_CREATE_DIRECTORY, xsltSecurityForbid);
@@ -148,7 +152,7 @@ main(int argc, char **argv) {
  * @details Verifies the XML signature in #xml_file using the public key from #key_file.
  * @param xml_file the signed XML file name.
  * @param key_file the PEM public key file name.
- * @param key_name the name to assign to the key (used to match the signature KeyName).
+ * @param key_name the name to assign to the key.
  * @return 0 on success or a negative value if an error occurs.
  */
 int

examples/verify2.c

@@ -257,7 +257,9 @@ verify_file(xmlSecKeysMngrPtr mngr, const char* xml_file) {
         goto done;
     }
 
-    /* find start node */
+    /* find start node; note: only the first <dsig:Signature/> element in
+     * document order is verified, a document with multiple signatures
+     * is not fully checked */
     node = xmlSecFindNode(xmlDocGetRootElement(doc), xmlSecNodeSignature, xmlSecDSigNs);
     if(node == NULL) {
         fprintf(stderr, "Error: start node not found in \"%s\"\n", xml_file);

src/mscng/certkeys.c

@@ -2378,7 +2378,7 @@ xmlSecMSCngCreateDerForBCryptPubkey(xmlSecKeyDataPtr data, LPVOID* ppDer, DWORD*
 /**
  * @brief Loads a public key of any supported type (RSA, DSA, EC, DH) from a raw SubjectPublicKeyInfo DER blob.
  * @param derData DER-encoded SubjectPublicKeyInfo.
- * @param derDataLen length of @p derData.
+ * @param derDataSize length of @p derData.
  *
  * @return new key data or NULL on failure.
  */