### Input XML Document Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-c14n.html

An example XML document with DTD, namespaces, and attributes, used to demonstrate canonicalization.

```xml
<!DOCTYPE doc [
  <!ATTLIST e2 xml:space (default|preserve) 'preserve'>
  <!ATTLIST e3 id ID #IMPLIED>
]> 
<doc xmlns="http://www.ietf.org" xmlns:w3c="http://www.w3.org" xml:base="something/else">
     <e1>
        <e2 xmlns="" xml:id="abc" xml:base="bar/">
           <e3 id="E3" xml:base="foo"/>
        </e2>
     </e1>
</doc>
```

--------------------------------

### Example of DerivedKey with ConcatKDF

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example XML element demonstrating the use of the ConcatKDF algorithm for key derivation. It includes the KeyDerivationMethod, ConcatKDFParams, and MasterKeyName.

```xml
<xenc11:DerivedKey
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
    xmlns:xenc11="http://www.w3.org/2009/xmlenc11#">
  <xenc11:KeyDerivationMethod Algorithm="http://www.w3.org/2009/xmlenc11#ConcatKDF">
    <xenc11:ConcatKDFParams AlgorithmID="0000" PartyUInfo="03D8" PartyVInfo="03D0">
      <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
    </xenc11:ConcatKDFParams>
  </xenc11:KeyDerivationMethod>
  <xenc:ReferenceList>
    <xenc:DataReference URI="#ED"/>
  </xenc:ReferenceList>
  <xenc11:MasterKeyName>Our other secret</xenc11:MasterKeyName>
</xenc11:DerivedKey>
```

--------------------------------

### Original Document Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-exc-c14n.html

An example of an original XML document structure.

```xml
<n0:local xmlns:n0="foo:bar"
          xmlns:n3="ftp://example.org">
      <n1:elem2 xmlns:n1="http://example.net"
                xml:lang="en">
          <n3:stuff xmlns:n3="ftp://example.org"/>
      </n1:elem2>
   </n0:local>
```

--------------------------------

### Example Payment Information XML

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

Illustrates a sample XML structure for payment information, including name and credit card details. This example is used to demonstrate encryption granularity.

```xml
<?xml version="1.0"?>

<PaymentInfo xmlns="http://example.org/paymentv2" >
  <Name>John Smith</Name>
  <CreditCard Limit="5,000" Currency="USD" >
    <Number>4019 2445 0277 5567</Number>
    <Issuer>Example Bank</Issuer>
    <Expiration>04/02</Expiration>
  </CreditCard>
</PaymentInfo>
```

--------------------------------

### Diffie-Hellman Legacy KDF Initial KM(1) Calculation Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example illustrating the initial calculation of KM(1) for the Diffie-Hellman Legacy KDF. It shows the substitution of placeholders like ZZ, counter, EncryptionAlg, KA-Nonce, and KeySize.

```text
SHA-1 ( ZZ01Example:Block/Algfoo80 )
```

--------------------------------

### Example Function

Source: https://github.com/kushaldas/bergshamra/blob/main/test-data/oss-fuzz/README.md

A simple C function demonstrating basic addition.

```c
func_add(int x, int y) { return x+y; }
```

--------------------------------

### Diffie-Hellman Legacy KDF Example with Specific Values

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

This example demonstrates the Diffie-Hellman Legacy KDF calculation with concrete values for ZZ (shared secret) and other parameters, showing the byte sequence representation.

```text
SHA-1( 0xDEADBEEF30314578616D706C653A426C6F636B2F416C67666F6F3830 )
```

--------------------------------

### Unit Test Example

Source: https://github.com/kushaldas/bergshamra/blob/main/test-data/oss-fuzz/README.md

A basic unit test for the func_add function using an assertion.

```c
ASSERT((func_add(4,5)==9))
```

--------------------------------

### GeneralizedTime Format Example

Source: https://github.com/kushaldas/bergshamra/blob/main/test-data/external-data/rfc3161.txt

An example of the GeneralizedTime syntax, which includes year, month, day, hour, minute, second, and fractional seconds, ending with 'Z' for Zulu time.

```text
19990609001326.34352Z
```

--------------------------------

### For Expression Expansion Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Illustrates how a multi-variable for expression is expanded into nested single-variable for expressions.

```xpath
for $x in X, $y in Y return $x + $y
```

```xpath
for $x in X return for $y in Y return $x + $y
```

--------------------------------

### X509Data Element Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-dsig.html

Demonstrates the usage of the X509Data element within KeyInfo to include various identifiers for certificates, such as issuer serial number, subject name, and the certificate itself. This example shows how to group related certificate information within a single X509Data element or across multiple elements.

```xml
<KeyInfo>
  <X509Data> <!-- two pointers to certificate-A -->
    <X509IssuerSerial> 
      <X509IssuerName>
        CN=TAMURA Kent, OU=TRL, O=IBM, L=Yamato-shi, ST=Kanagawa, C=JP
      </X509IssuerName>
      <X509SerialNumber>12345678</X509SerialNumber>
    </X509IssuerSerial>
    <X509SKI>31d97bd7</X509SKI> 
  </X509Data>
  <X509Data><!-- single pointer to certificate-B -->
    <X509SubjectName>Subject of Certificate B</X509SubjectName>
  </X509Data>
  <X509Data> <!-- certificate chain -->
    <!--Signer cert, issuer CN=arbolCA,OU=FVT,O=IBM,C=US, serial 4-->
    <X509Certificate>MIICXTCCA..</X509Certificate>
    <!-- Intermediate cert subject CN=arbolCA,OU=FVT,O=IBM,C=US 
         issuer CN=tootiseCA,OU=FVT,O=Bridgepoint,C=US -->
    <X509Certificate>MIICPzCCA...</X509Certificate>
    <!-- Root cert subject CN=tootiseCA,OU=FVT,O=Bridgepoint,C=US -->
    <X509Certificate>MIICSTCCA...</X509Certificate>
  </X509Data>
</KeyInfo>
```

--------------------------------

### XPath 3.1 FunctionTest Examples

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Illustrates various FunctionTest constructs in XPath 3.1.

```xpath
function(*)
```

```xpath
function(int, int) as int
```

```xpath
function(xs:anyAtomicType) as item()*
```

```xpath
function(xs:integer) as item()*
```

--------------------------------

### AES EncryptionMethod Example (256-bit)

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example of an EncryptionMethod element for AES 256-bit encryption in CBC mode. This specifies the algorithm for encrypting data.

```xml
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc" />
```

--------------------------------

### XPath 3.1 Examples Returning True

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Illustrates basic XPath 3.1 logical expressions that evaluate to true.

```xpath
1 eq 1 and 2 eq 2
```

```xpath
1 eq 1 or 2 eq 3
```

--------------------------------

### XPath General Comparison: Inverse Operators Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Shows that '=' and '!=' are not always inverse operators. Both comparisons in this example evaluate to true.

```xpath
(1, 2) = (2, 3)
(1, 2) != (2, 3)
```

--------------------------------

### RSA-OAEP with MGF1 SHA1 Encryption Method (Duplicate Example)

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

Another instance of an RSA-OAEP EncryptionMethod using MGF1 with SHA1. This example is identical to the previous one in terms of code content.

```xml
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
            <OAEPparams>9lWu3Q==</OAEPparams>
            <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
            <EncryptionMethod>
```

--------------------------------

### Valid Nested Comment Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Demonstrates a syntactically valid nested comment structure in XPath. This example shows how balanced '(:' and ':)' pairs allow for nesting.

```xpath
(: commenting out a (: comment :) may be confusing, but often helpful :)
```

--------------------------------

### RSA SignatureMethod Element Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-dsig.html

This snippet shows an example of an RSA SignatureMethod element used in XML Signature. It specifies the algorithm for RSA-based digital signatures.

```xml
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
```

--------------------------------

### XPath 3.1 EQName Examples

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Illustrates different forms of EQNames in XPath 3.1, including lexical QNames and URIQualifiedNames.

```xpath
invoice
```

```xpath
my:invoice
```

```xpath
Q{http://example.com/ns}invoice
```

```xpath
Q{}invoice
```

```xpath
pi
```

```xpath
math:pi
```

```xpath
Q{http://www.w3.org/2005/xpath-functions/math}pi
```

--------------------------------

### Example: Referencing the fn:concat function

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

References the built-in 'fn:concat' function which expects five arguments.

```xpath
fn:concat#5
```

--------------------------------

### Whitespace Handling Examples

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Illustrates how whitespace and comments affect the parsing of XPath expressions. Demonstrates scenarios where whitespace is required to separate terminals.

```text
*   `foo- foo` results in a syntax error. "foo-" would be recognized as a QName.
    
*   `foo -foo` is syntactically equivalent to `foo - foo`, two QNames separated by a subtraction operator.
    
*   `foo(: This is a comment :)- foo` is syntactically equivalent to `foo - foo`. This is because the comment prevents the two adjacent terminals from being recognized as one.
    
*   `foo-foo` is syntactically equivalent to single QName. This is because "-" is a valid character in a QName. When used as an operator after the characters of a name, the "-" must be separated from the name, e.g. by using whitespace or parentheses.
    
*   `10div 3` results in a syntax error.
    
*   `10 div3` also results in a syntax error.
    
*   `10div3` also results in a syntax error.
```

--------------------------------

### XML Document Subset Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-c14n.html

Illustrates the structure of an XML document used to demonstrate canonicalization with xml:base attributes. This example shows nested elements with xml:base attributes that are affected by the removal of parent elements.

```xml
<a xml:base="foo/bar">
 <b xml:base="..">
  <c xml:base="..">
   <d xml:base="x">
   </d>
  </c>
 </b>
</a>
```

--------------------------------

### Example DerivedKey with PBKDF2

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

Demonstrates an xenc11:DerivedKey element utilizing the PBKDF2 key derivation method with HMAC-SHA256 as the PRF.

```xml
<xenc11:DerivedKey
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
    xmlns:xenc11="http://www.w3.org/2009/xmlenc11#">
  <xenc11:KeyDerivationMethod Algorithm="http://www.w3.org/2009/xmlenc11#pbkdf2"/>
  <xenc11:PBKDF2-params>
    <xenc11:Salt>
      <xenc11:Specified>Df3dRAhjGh8=</xenc11:Specified>
    </xenc11:Salt>
    <xenc11:IterationCount>2000</xenc11:IterationCount>
    <xenc11:KeyLength>16</xenc11:KeyLength>
    <xenc11:PRF Algorithm="http://www.w3.org/2001/04/xmldsig-more#hmac-sha256"/>
  </xenc11:PBKDF2-params>
<xenc:ReferenceList>
  <xenc:DataReference URI="#ED"/>
</xenc:ReferenceList>
<xenc11:MasterKeyName>Our shared secret</xenc11:MasterKeyName>
</xenc11:DerivedKey>
```

--------------------------------

### Example: Referencing a local function

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

References a user-defined function named 'myfunc' in the 'local' namespace, expecting two arguments.

```xpath
local:myfunc#2
```

--------------------------------

### Multi-Variable For Expression Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Demonstrates a for expression with multiple variables, iterating over two sequences and returning the sum of their elements.

```xpath
for $i in (10, 20),
    $j in (1, 2)
return ($i + $j)
```

--------------------------------

### XML Encryption AgreementMethod Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

Demonstrates the use of the AgreementMethod element within an EncryptedData structure, including KA-Nonce, KeyDerivationMethod, and Originator/RecipientKeyInfo.

```xml
<EncryptedData>
  <EncryptionMethod Algorithm="Example:Block/Alg">
    <KeySize>80</KeySize>
  </EncryptionMethod>
  <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <AgreementMethod Algorithm="example:Agreement/Algorithm">
      <KA-Nonce>Zm9v</KA-Nonce>
      <xenc11:KeyDerivationMethod
          Algorithm="http://www.w3.org/2009/xmlenc11#ConcatKDF">
        <xenc11:ConcatKDFParams 
            AlgorithmID="00" PartyUInfo="" PartyVInfo=""> 
          <ds:DigestMethod 
              Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
        </xenc11:ConcatKDFParams>
      </xenc11:KeyDerivationMethod>
          
      <OriginatorKeyInfo>
        <ds:KeyValue>....</ds:KeyValue>
      </OriginatorKeyInfo>
      <RecipientKeyInfo>
        <ds:KeyValue>....</ds:KeyValue>
      </RecipientKeyInfo> 
    </AgreementMethod>
  </ds:KeyInfo>
  <CipherData>...</CipherData>
</EncryptedData>
```

--------------------------------

### Example: Referencing the fn:abs function

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

References the built-in 'fn:abs' function which expects a single argument.

```xpath
fn:abs#1
```

--------------------------------

### Numeric Operator Mapping Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Illustrates the four distinct operators for the '+' operator when applied to numeric types.

```xpath
Operator
First operand type
Second operand type
Result type

+ 
xs:integer
xs:integer
xs:integer

+ 
xs:decimal
xs:decimal
xs:decimal

+ 
xs:float
xs:float
xs:float

+ 
xs:double
xs:double
xs:double
```

--------------------------------

### Valid GeneralizedTime Representations

Source: https://github.com/kushaldas/bergshamra/blob/main/test-data/external-data/rfc3161.txt

Provides examples of valid GeneralizedTime strings, including representations with and without fractional seconds.

```text
"19920521000000Z"
"19920622123421Z"
"19920722132100.3Z"
```

--------------------------------

### Select all 'para' elements in the document

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Selects all 'para' elements in the same document as the context node. Starts the selection from the document root.

```XPath
/descendant::para
```

--------------------------------

### XPath 3.1 Literal Examples

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Illustrates various literal expressions in XPath 3.1, showing how they are interpreted as strings, integers, decimals, or doubles.

```xpath
"12.5"
```

```xpath
12
```

```xpath
12.5
```

```xpath
125E2
```

```xpath
"He said, ""I don't like it."""
```

--------------------------------

### HMAC-SHA1 SignatureValue Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-dsig.html

Example of a base64 encoded SignatureValue for an HMAC-SHA1 digest.

```xml
<SignatureValue>kpRyejY4uxwT9I74FYv8nQ==</SignatureValue>
```

--------------------------------

### Example Document with EncryptedData

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example XML document containing an EncryptedData element.

```xml
<!DOCTYPE Document [
<!ENTITY dsig "http://www.w3.org/2000/09/xmldsig#">
]>
<Document xmlns="http://example.org/"
>
  <foo:Body xmlns:foo="http://example.org/foo"
>
    <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#"
                   Type="http://www.w3.org/2001/04/xmlenc#Element"
>
      ...
    </EncryptedData>
  </foo:Body>
</Document>
```

--------------------------------

### XPath 3.1 SchemaAttributeTest Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Example of a SchemaAttributeTest matching an attribute node named 'color'.

```xpath
schema-attribute(color)
```

--------------------------------

### Build and Test Commands

Source: https://github.com/kushaldas/bergshamra/blob/main/README.md

Standard Cargo commands for building, testing, linting, and formatting the project.

```bash
cargo build                    # Debug build
cargo build --release          # Release build (needed for integration tests)
cargo test                     # Run all unit tests
cargo clippy --workspace       # Lint
cargo fmt --all -- --check     # Check formatting
```

--------------------------------

### CipherValue Example for RSA Version 1.5

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example of a CipherValue element containing the base64 encoding of an encrypted key using RSA Version 1.5. Note that the newline in the example is for display purposes only and not part of the actual value.

```xml
<CipherData>
  <CipherValue>IWijxQjUrcXBYoCei4QxjWo9Kg8D3p9tlWoT4
t0/gyTE96639In0FZFY2/rvP+/bMJ01EArmKZsR5VW3rwoPxw=</CipherValue>
</CipherData>
```

--------------------------------

### Configure SAML Context Programmatically

Source: https://github.com/kushaldas/bergshamra/blob/main/README.md

Set up a DsigContext for SAML verification with security-focused options enabled. Ensure keys are managed externally and verification is strict.

```rust
let mut ctx = DsigContext::new(keys_manager);
cctx.trusted_keys_only = true;     // reject inline keys
cctx.strict_verification = true;   // reject unexpected reference positions
cctx.verify_keys = true;           // validate the IdP certificate chain
```

--------------------------------

### SHA1 DigestValue Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

Example of a DigestValue element for a SHA-1 digest. The content is the base64 encoding of the 160-bit digest.

```xml
<DigestValue>qZk+NkcGgWq6PiVxeFDCbJzQ2J0=</DigestValue>
```

--------------------------------

### Create NSS Database and Import PKCS12

Source: https://github.com/kushaldas/bergshamra/blob/main/test-data/keys/README.md

Removes an existing NSS database, creates a new one, and imports a PKCS12 file into it. It then sets restrictive permissions on the imported files.

```bash
rm -rf nssdb
mkdir nssdb
pk12util -d nssdb -i rsa-4096-key.p12
chmod a-w nssdb/*
```

--------------------------------

### AES EncryptionMethod Example (192-bit)

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example of an EncryptionMethod element for AES 192-bit encryption in CBC mode. This specifies the algorithm for encrypting data.

```xml
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes192-cbc" />
```

--------------------------------

### AES EncryptionMethod Example (128-bit)

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example of an EncryptionMethod element for AES 128-bit encryption in CBC mode. This specifies the algorithm for encrypting data.

```xml
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc" />
```

--------------------------------

### Sign an XML Template

Source: https://github.com/kushaldas/bergshamra/blob/main/README.md

Command-line usage for signing an XML template with a private key and specifying an output file.

```bash
bergshamra sign -k private.pem --output signed.xml template.xml
```

--------------------------------

### XPath 3.1 Example Comment

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

An example of a comment in XPath 3.1. Comments can be used anywhere ignorable whitespace is allowed and do not affect expression processing.

```xpath
(: Houston, we have a problem :)
```

--------------------------------

### Build X.509 KeyInfo XML Fragments

Source: https://github.com/kushaldas/bergshamra/blob/main/CHANGELOG.md

Generate `<ds:KeyInfo>` XML fragments containing X.509 certificates using base64-encoded strings or raw DER bytes.

```rust
let xml = bergshamra_keys::build_x509_key_info(&[cert_b64]);
```

```rust
let xml = bergshamra_keys::build_x509_key_info_from_der(&[cert_der]);
```

--------------------------------

### Sign a file using xmlsec.exe with mscng

Source: https://github.com/kushaldas/bergshamra/blob/main/test-data/keysstore/README.md

Use this command to sign a file with the mscng crypto backend. Ensure the P12 key is imported and accessible.

```bash
win32/binaries/xmlsec.exe sign --crypto mscng --output out.xml tests/keysstore/keysstore.xml
```

--------------------------------

### ECDSA SignatureMethod Element Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-dsig.html

An example of an ECDSA SignatureMethod element using the ecdsa-sha256 algorithm. This element specifies the algorithm used for digital signatures.

```xml
<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256" />
```

--------------------------------

### Triple DES EncryptionMethod Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example of an EncryptionMethod element for Triple DES encryption in CBC mode. This is used to specify the algorithm for encrypting data.

```xml
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc" />
```

--------------------------------

### Configure DsigContext using Builder Pattern

Source: https://github.com/kushaldas/bergshamra/blob/main/CHANGELOG.md

Use the new builder methods on `DsigContext` for fluent configuration. Direct field assignment is still supported.

```rust
let mut ctx = DsigContext::new(keys_manager);
ctx.trusted_keys_only = true;
ctx.strict_verification = true;
ctx.hmac_min_out_len = 128;
```

```rust
let ctx = DsigContext::new(keys_manager)
    .with_trusted_keys_only(true)
    .with_strict_verification(true)
    .with_hmac_min_out_len(128);
```

--------------------------------

### XPath Filter Element Example

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmldsig-filter2.html

Example of an XPath element used for signature filtering with the 'subtract' operation. This filters the entire input node-set except for elements with identifiers 'foo' and 'bar'.

```xml
<XPath Filter="subtract"
    xmlns="http://www.w3.org/2002/06/xmldsig-filter2">
      id("foo bar")
   </XPath>
```

--------------------------------

### Example WS-Security SignedInfo with `cid:` URI

Source: https://github.com/kushaldas/bergshamra/blob/main/docs/adr/0002-cid-uri-scheme-skip.md

Illustrates a `<SignedInfo>` element from a WS-Security SOAP message containing a `cid:` URI reference to an external attachment.

```xml
<ds:SignedInfo>
  <ds:Reference URI="">
    <!-- references the SOAP Body (normal in-document ref) -->
  </ds:Reference>
  <ds:Reference URI="cid:attachment-1@example.com">
    <!-- references a MIME attachment outside the XML document -->
    <ds:Transforms>
      <ds:Transform Algorithm="http://docs.oasis-open.org/wss/oasis-wss-SwAProfile-1.1#Attachment-Content-Signature-Transform"/>
    </ds:Transforms>
    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
    <ds:DigestValue>abc123...</ds:DigestValue>
  </ds:Reference>
</ds:SignedInfo>
```

--------------------------------

### Canonical Form - Start and End Tags Normalization

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-c14n.html

Illustrates the canonicalization of start and end tags, including conversion of empty elements to start-end tag pairs, whitespace normalization, and attribute ordering.

```xml
<doc>      <e1></e1>      <e2></e2>      <e3 id="elem3" name="elem3"></e3>      <e4 id="elem4" name="elem4"></e4>      <e5 xmlns="http://example.org" xmlns:a="http://www.w3.org" xmlns:b="http://www.ietf.org" attr="I'm" attr2="all" b:attr="sorted" a:attr="out"></e5>      <e6 xmlns:a="http://www.w3.org">         <e7 xmlns="http://www.ietf.org">            <e8 xmlns="">               <e9 xmlns:a="http://www.ietf.org" attr="default"></e9>            </e8>         </e7>      </e6>   </doc>
```

--------------------------------

### Run XML Encryption Integration Tests

Source: https://github.com/kushaldas/bergshamra/blob/main/README.md

Executes encryption integration tests using a provided script and OpenSSL.

```bash
cd /path/to/bergshamra

# Enc tests
bash test-data/testrun.sh test-data/testEnc.sh openssl \
    "$(pwd)/test-data" "$(pwd)/tests/xmlsec1-shim.py" pem
```

--------------------------------

### Canonical XML Example with Namespace Context

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-exc-c14n.html

Demonstrates how Canonical XML includes namespace context, which can break signatures when XML is enveloped and then extracted.

```xml
<n1:elem1 xmlns:n1="http://b.example">
    content
</n1:elem1>
```

```xml
<n0:pdu xmlns:n0="http://a.example">
   <n1:elem1 xmlns:n1="http://b.example">
       content
   </n1:elem1>
</n0:pdu>
```

```xml
<n1:elem1 xmlns:n0="http://a.example"
            xmlns:n1="http://b.example">
    content
</n1:elem1>
```

--------------------------------

### Partial Application of a Built-In Function

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Shows how to create a specialized function by partially applying a built-in function. This example creates a function to compute the sum of squares.

```xpath
let $sum-of-squares := fn:fold-right(?, 0, function($a, $b) { $a*$a + $b })
return $sum-of-squares(1 to 3)
```

--------------------------------

### Document with Changed Enveloping

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-exc-c14n.html

An example of an XML document where the enveloping of 'elem2' has been changed.

```xml
<n2:pdu xmlns:n1="http://example.com"
          xmlns:n2="http://foo.example"
          xml:lang="fr"
          xml:space="retain">
      <n1:elem2 xmlns:n1="http://example.net"
                xml:lang="en">
          <n3:stuff xmlns:n3="ftp://example.org"/>
      </n1:elem2>
   </n2:pdu>
```

--------------------------------

### Run XML Digital Signature Integration Tests

Source: https://github.com/kushaldas/bergshamra/blob/main/README.md

Executes digital signature integration tests using a provided script and OpenSSL.

```bash
# DSig tests
bash test-data/testrun.sh test-data/testDSig.sh openssl \
    "$(pwd)/test-data" "$(pwd)/tests/xmlsec1-shim.py" pem
```

--------------------------------

### DSA SignatureMethod Element

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-dsig.html

Example of a DSA SignatureMethod element using DSA with SHA256.

```xml
<SignatureMethod Algorithm="http://www.w3.org/2009/xmldsig11#dsa-sha256"/>
```

--------------------------------

### Generate and Sign GOST 2012 (512-bit) Key and Certificate

Source: https://github.com/kushaldas/bergshamra/blob/main/test-data/keys/README.md

Generates a GOST 2012 (512-bit) key pair and certificate request, signs it with a second-level CA, verifies it, and converts the certificate to DER format. It also creates a PKCS12 bundle.

```bash
openssl req -config ./openssl.cnf -newkey gost2012_512 -pkeyopt paramset:A -nodes -keyout gost2012_512key.pem -out gost2012_512req.pem
openssl ca -config ./openssl.cnf -cert ca2cert.pem -keyfile ca2key.pem -out gost2012_512cert.pem -infiles gost2012_512req.pem
OPENSSL_CONF=./openssl.cnf openssl verify -CAfile cacert.pem -untrusted ca2cert.pem gost2012_512cert.pem
rm gost2012_512req.pem

openssl x509 -outform DER -in gost2012_512cert.pem -out gost2012_512cert.der

OPENSSL_CONF=./openssl.cnf openssl pkcs8 -in gost2012_512key.pem -inform pem -out gost2012_512key.p8-pem -outform pem -topk8

cat gost2012_512key.pem gost2012_512cert.pem ca2cert.pem cacert.pem > all-gost2012_512.pem
OPENSSL_CONF=./openssl.cnf openssl pkcs12 -export -in all-gost2012_512.pem -name TestGost2012_512Key -out gost2012_512key.p12
rm all-gost2012_512.pem
```

--------------------------------

### SHA256 DigestMethod Element

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

Example of an SHA-256 DigestMethod element. SHA-256 is recommended over SHA-1.

```xml
<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
```

--------------------------------

### XML Element with xml:base Attribute

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example of a parent XML element 'Baz' with an 'xml:base' attribute, demonstrating context inheritance.

```xml
<Baz xml:base="http://example.org/"/>
```

--------------------------------

### XML Fragment with Default Namespace

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

An example of an XML fragment where 'ToBeEncrypted' is in the default namespace.

```xml
<Document xmlns="http://example.org/" >
  <ToBeEncrypted xmlns="" />
</Document>
```

--------------------------------

### HMAC SignatureMethod Element

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xml-dsig.html

Example of an HMAC SignatureMethod element specifying the algorithm and truncation length.

```xml
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1">
  <HMACOutputLength>128</HMACOutputLength>
</SignatureMethod>
```

--------------------------------

### Configure and Verify GOST Engine

Source: https://github.com/kushaldas/bergshamra/blob/main/test-data/keys/README.md

Sets environment variables for OpenSSL GOST support and verifies the engine and version. This is a prerequisite for generating GOST keys.

```bash
export OPENSSL_TOP_DIR=<path to openssl>
export PATH=$OPENSSL_TOP_DIR/bin:$PATH
export LD_LIBRARY_PATH=$OPENSSL_TOP_DIR/lib64:$OPENSSL_TOP_DIR/lib:$LD_LIBRARY_PATH
OPENSSL_CONF=./openssl.cnf openssl version -e
OPENSSL_CONF=./openssl.cnf openssl engine
```

--------------------------------

### RIPEMD-160 DigestMethod Element

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xmlenc-core1.html

Example of a RIPEMD-160 DigestMethod element. RIPEMD-160 produces a 160-bit digest.

```xml
<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#ripemd160" />
```

--------------------------------

### Partial Application of a Map to a Function

Source: https://github.com/kushaldas/bergshamra/blob/main/specs/xpath-31.html

Demonstrates converting a map to a function using partial application. The resulting function is not a map.

```xpath
let $a := map {"A": 1, "B": 2}(?)
return $a("A")
```