# `SignCore.XML.Builder`
[🔗](https://github.com/utaladriz/pkcs11ex/blob/v0.1.0/lib/sign_core/xml/builder.ex#L1)

Builds XML-DSig elements for the XAdES B-B sign flow.

The shape produced is the W3C XML Signature 1.1 envelope:

    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm=".../exc-c14n#"/>
        <ds:SignatureMethod Algorithm="..."/>
        <ds:Reference URI="...">
          <ds:Transforms>
            <ds:Transform Algorithm=".../enveloped-signature"/>
            <ds:Transform Algorithm=".../exc-c14n#"/>
          </ds:Transforms>
          <ds:DigestMethod Algorithm=".../sha256"/>
          <ds:DigestValue>...</ds:DigestValue>
        </ds:Reference>
        <ds:Reference Type="...SignedProperties" URI="#xades-...">
          <ds:Transforms>
            <ds:Transform Algorithm=".../exc-c14n#"/>
          </ds:Transforms>
          <ds:DigestMethod Algorithm=".../sha256"/>
          <ds:DigestValue>...</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>...</ds:SignatureValue>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
          ...
        </ds:X509Data>
      </ds:KeyInfo>
      <ds:Object>
        <xades:QualifyingProperties .../>
      </ds:Object>
    </ds:Signature>

Builder functions emit raw binary XML — exc-c14n is applied during
digest / signature computation, so attribute order and whitespace
in these strings is normalised away before any hash is taken.

# `alg_from_signature_method_uri`

```elixir
@spec alg_from_signature_method_uri(String.t()) :: {:ok, atom()} | {:error, term()}
```

Map an XML Signature URI back to a JOSE alg atom. Inverse of
`signature_method_uri/1`.

# `c14n_exclusive_uri`

Canonicalisation method URI for Exclusive XML C14N 1.0.

# `digest_sha256_uri`

Digest method URI for SHA-256.

# `ds_ns`

URI namespace for the XML Signature `ds:` prefix (W3C XMLDSig).

# `random_id`

```elixir
@spec random_id() :: String.t()
```

Helper: 8-byte hex random id suitable for XML Id attributes.

# `reference`

```elixir
@spec reference(String.t(), [String.t()], binary(), keyword()) :: String.t()
```

Build a `<ds:Reference>` element targeting a fragment of the
enveloping document. `:transforms` is a list of transform URIs
applied left-to-right; the typical XAdES B-B set is
`[envelope, exc_c14n]` for the data reference and `[exc_c14n]`
for the SignedProperties reference.

# `reference_xades_signed_properties_type`

URI tag for the standard XAdES SignedProperties reference Type attribute.

# `signature`

```elixir
@spec signature(String.t(), binary(), [binary()], String.t(), keyword()) :: String.t()
```

# `signature_method_uri`

```elixir
@spec signature_method_uri(atom()) :: String.t()
```

Returns the XML Signature URI for a given JOSE alg atom.

    iex> SignCore.XML.Builder.signature_method_uri(:RS256)
    "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"

    iex> SignCore.XML.Builder.signature_method_uri(:PS256)
    "http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1"

# `signature_value`

```elixir
@spec signature_value(binary()) :: String.t()
```

Build a standalone `<ds:SignatureValue>` element with the `ds`
namespace declared inline. Used by the B-T attach path to compute
the canonical bytes of the signature-value element exactly the way
a verifier would re-derive them when extracting it from the signed
document.

`value_b64` MUST be base64 already (RFC 4648). The caller is
responsible for producing it; this builder just wraps the bytes.

# `signed_info`

```elixir
@spec signed_info([String.t()], atom()) :: String.t()
```

Build a `<ds:SignedInfo>` element wrapping the supplied
references. The `:alg` selects the `<ds:SignatureMethod>` URI.

# `transform_envelope_uri`

Transform URI for the `enveloped-signature` rewrite.

# `xades_ns`

URI namespace for the XAdES `xades:` prefix.

---

*Consult [api-reference.md](api-reference.md) for complete listing*