### Install goxmldsig

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Install the goxmldsig package using the go get command.

```bash
$ go get github.com/russellhaering/goxmldsig

```

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

### Get chain from TLSCertKeyStore

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Implements X509ChainStore using the underlying tls.Certificate.

```go
func (d TLSCertKeyStore) GetChain() ([][]byte, error)
```

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

### Get key pair from TLSCertKeyStore

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Implements X509KeyStore using the underlying tls.Certificate.

```go
func (d TLSCertKeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)
```

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

### Get signature method identifier

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Retrieves the identifier for the signature method used in the signing context.

```go
func (ctx *SigningContext) GetSignatureMethodIdentifier() string
```

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

### Get digest algorithm identifier

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Retrieves the identifier for the digest algorithm used in the signing context.

```go
func (ctx *SigningContext) GetDigestAlgorithmIdentifier() string
```

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

### Generate a random key store for testing

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Creates an X509KeyStore instance intended for testing purposes.

```go
func RandomKeyStoreForTest() X509KeyStore
```

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

### Define X509KeyStore interface

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Interface for retrieving private keys and certificates.

```go
type X509KeyStore interface {
	GetKeyPair() (privateKey *rsa.PrivateKey, cert []byte, err error)
}
```

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

### Define TLSCertKeyStore

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Wraps the standard library tls.Certificate to provide key and certificate access.

```go
type TLSCertKeyStore tls.Certificate
```

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

### Define X509CertificateStore interface

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Interface for retrieving root certificates.

```go
type X509CertificateStore interface {
	Certificates() (roots []*x509.Certificate, err error)
}
```

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

### Create a default validation context

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Initializes a validation context with the provided certificate store.

```go
func NewDefaultValidationContext(certificateStore X509CertificateStore) *ValidationContext
```

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

### Create a new SigningContext

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Initializes a signing context with a signer and certificate chain. The KeyStore field should not be used with this function.

```go
func NewSigningContext(signer crypto.Signer, certs [][]byte) (*SigningContext, error)
```

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

### TLSCertKeyStore Type and Methods

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Wrapper for tls.Certificate to implement X509ChainStore and X509KeyStore interfaces.

```APIDOC
## type TLSCertKeyStore

### Description
TLSCertKeyStore wraps the stdlib tls.Certificate to return its contained key and certs.

### Method
type

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Response Example
N/A
```

```APIDOC
## func (TLSCertKeyStore) GetChain

### Description
GetChain implements X509ChainStore using the underlying tls.Certificate.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## func (TLSCertKeyStore) GetKeyPair

### Description
GetKeyPair implements X509KeyStore using the underlying tls.Certificate.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Construct Inclusive Canonicalizers

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Constructs various inclusive canonicalizer implementations.

```go
func MakeC14N10RecCanonicalizer() Canonicalizer
```

```go
func MakeC14N10WithCommentsCanonicalizer() Canonicalizer
```

```go
func MakeC14N11Canonicalizer() Canonicalizer
```

```go
func MakeC14N11WithCommentsCanonicalizer() Canonicalizer
```

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

### Signing Context

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Configuration context for signing operations.

```go
type SigningContext struct {
	Hash crypto.Hash

	// This field will be nil and unused if the SigningContext is created with
	// NewSigningContext
	KeyStore      X509KeyStore
	IdAttribute   string
	Prefix        string
	Canonicalizer Canonicalizer
	// contains filtered or unexported fields
}
```

```go
func NewDefaultSigningContext(ks X509KeyStore) *SigningContext
```

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

### Interface Definitions

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Definitions for X509CertificateStore, X509ChainStore, and X509KeyStore interfaces.

```APIDOC
## type X509CertificateStore

### Description
X509CertificateStore is an interface for retrieving root certificates.

### Method
interface

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Response Example
N/A
```

```APIDOC
## type X509ChainStore

### Description
X509ChainStore is an interface for retrieving a certificate chain.

### Method
interface

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Response Example
N/A
```

```APIDOC
## type X509KeyStore

### Description
X509KeyStore is an interface for retrieving a private key and certificate pair.

### Method
interface

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Response Example
N/A
```

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

### NSContext Management

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Structures and methods for managing XML namespace contexts.

```go
type NSContext struct {
	// contains filtered or unexported fields
}
```

```go
func NSBuildParentContext(el *etree.Element) (NSContext, error)
```

```go
func NewDefaultNSContext() NSContext
```

```go
func (ctx NSContext) CheckLimit() error
```

```go
func (ctx NSContext) Copy() NSContext
```

```go
func (ctx NSContext) LookupPrefix(prefix string) (string, error)
```

```go
func (ctx NSContext) Prefixes() map[string]string
```

```go
func (ctx NSContext) SubContext(el *etree.Element) (NSContext, error)
```

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

### X509KeyStore Interface

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Defines the interface for storing and retrieving X.509 key pairs.

```APIDOC
## Interfaces

### X509KeyStore

`type X509KeyStore interface`

- `GetKeyPair() (*rsa.PrivateKey, []byte, error)`: Retrieves a private key and its corresponding certificate chain.

## Structs

### MemoryX509KeyStore

`type MemoryX509KeyStore struct`
```

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

### Memory X509 Key Store

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

An in-memory implementation of an X.509 key store.

```go
type MemoryX509KeyStore struct {
	// contains filtered or unexported fields
}
```

```go
func (ks *MemoryX509KeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)
```

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

### Define KeyInfo struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the KeyInfo element containing X509 data.

```go
type KeyInfo struct {
	XMLName  xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# KeyInfo"`
	X509Data X509Data `xml:"X509Data"`
}
```

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

### Define X509ChainStore interface

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Interface for retrieving certificate chains.

```go
type X509ChainStore interface {
	GetChain() (certs [][]byte, err error)
}
```

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

### Construct a signature

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Generates a signature for the provided etree element.

```go
func (ctx *SigningContext) ConstructSignature(el *etree.Element, enveloped bool) (*etree.Element, error)
```

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

### Supported Canonicalization Algorithms

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Constants defining well-known XML canonicalization and signature algorithm identifiers.

```go
const (
	// Supported canonicalization algorithms
	CanonicalXML10ExclusiveAlgorithmId             AlgorithmID = "http://www.w3.org/2001/10/xml-exc-c14n#"
	CanonicalXML10ExclusiveWithCommentsAlgorithmId AlgorithmID = "http://www.w3.org/2001/10/xml-exc-c14n#WithComments"

	CanonicalXML11AlgorithmId             AlgorithmID = "http://www.w3.org/2006/12/xml-c14n11"
	CanonicalXML11WithCommentsAlgorithmId AlgorithmID = "http://www.w3.org/2006/12/xml-c14n11#WithComments"

	CanonicalXML10RecAlgorithmId          AlgorithmID = "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
	CanonicalXML10WithCommentsAlgorithmId AlgorithmID = "http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"

	EnvelopedSignatureAltorithmId AlgorithmID = "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
)
```

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

### Define X509Certificate struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents an X509Certificate element.

```go
type X509Certificate struct {
	XMLName xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# X509Certificate"`
	Data    string   `xml:",chardata"`
}
```

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

### Memory X509 Certificate Store

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

An in-memory implementation of an X.509 certificate store.

```go
type MemoryX509CertificateStore struct {
	Roots []*x509.Certificate
}
```

```go
func (mX509cs *MemoryX509CertificateStore) Certificates() ([]*x509.Certificate, error)
```

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

### Sign XML Element

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Generates a key, creates a signing context, and signs an etree.Element. Ensure the element is not modified after signing to maintain signature validity.

```go
package main

import (
    "github.com/beevik/etree"
    "github.com/russellhaering/goxmldsig"
)

func main() {
    // Generate a key and self-signed certificate for signing
    randomKeyStore := dsig.RandomKeyStoreForTest()
    ctx := dsig.NewDefaultSigningContext(randomKeyStore)
    elementToSign := &etree.Element{
        Tag: "ExampleElement",
    }
    elementToSign.CreateAttr("ID", "id1234")

    // Sign the element
    signedElement, err := ctx.SignEnveloped(elementToSign)
    if err != nil {
        panic(err)
    }

    // Serialize the signed element. It is important not to modify the element
    // after it has been signed - even pretty-printing the XML will invalidate
    // the signature.
    doc := etree.NewDocument()
    doc.SetRoot(signedElement)
    str, err := doc.WriteToString()
    if err != nil {
        panic(err)
    }

    println(str)
}

```

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

### Type: X509KeyStore

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Interface for storing and retrieving X.509 key pairs.

```APIDOC
## Type: X509KeyStore

### Test Key Store Constructor

```go
func RandomKeyStoreForTest() X509KeyStore
```

Provides a random X509KeyStore for testing purposes.
```

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

### Define X509Data struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the X509Data element containing a list of certificates.

```go
type X509Data struct {
	XMLName          xml.Name          `xml:"http://www.w3.org/2000/09/xmldsig# X509Data"`
	X509Certificates []X509Certificate `xml:"X509Certificate"`
}
```

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

### Define SignedInfo struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the SignedInfo element containing canonicalization, signature method, and references.

```go
type SignedInfo struct {
	XMLName                xml.Name               `xml:"http://www.w3.org/2000/09/xmldsig# SignedInfo"`
	CanonicalizationMethod CanonicalizationMethod `xml:"CanonicalizationMethod"`
	SignatureMethod        SignatureMethod        `xml:"SignatureMethod"`
	References             []Reference            `xml:"Reference"`
}
```

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

### NSDetatch Function

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Creates a copy of an etree element and attaches namespaces from the provided context to the new element.

```go
func NSDetatch(ctx NSContext, el *etree.Element) (*etree.Element, error)
```

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

### X509CertificateStore Interface

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Defines the interface for storing and retrieving X.509 certificates.

```APIDOC
## Interfaces

### X509CertificateStore

`type X509CertificateStore interface`

- `Certificates() ([]*x509.Certificate, error)`: Retrieves a list of certificates.

## Structs

### MemoryX509CertificateStore

`type MemoryX509CertificateStore struct`

- `Roots []*x509.Certificate`: A slice of root certificates.
```

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

### SigningContext Struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Represents the context for signing XML documents.

```APIDOC
## Structs

### SigningContext

`type SigningContext struct`

Represents the context for signing XML documents.

- `Hash crypto.Hash`: The hash algorithm to use for signing.
- `KeyStore X509KeyStore`: The keystore to retrieve signing keys from. This field will be nil and unused if the SigningContext is created with `NewSigningContext`.
- `IdAttribute string`: The attribute name to use for the ID.
- `Prefix string`: The prefix to use for the signature.
- `Canonicalizer Canonicalizer`: The canonicalizer to use for preparing the XML before signing.

## Functions

### SigningContext Creation Functions

- `NewDefaultSigningContext(ks X509KeyStore) *SigningContext`: Creates a new SigningContext with default settings.
```

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

### Error Handling for Namespace Prefixes

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Custom error type for undeclared namespace prefixes.

```go
type ErrUndeclaredNSPrefix struct {
	Prefix string
}
```

```go
func (e ErrUndeclaredNSPrefix) Error() string
```

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

### Sign a string

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Signs a string, useful for HTTP-Redirect bindings like SAML AuthnRequests.

```go
func (ctx *SigningContext) SignString(content string) ([]byte, error)
```

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

### Type: MemoryX509KeyStore

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

An in-memory store for X.509 key pairs.

```APIDOC
## Type: MemoryX509KeyStore

### GetKeyPair Method

```go
func (ks *MemoryX509KeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)
```

Retrieves the RSA private key and its associated public certificate chain from the in-memory store.
```

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

### Construct Exclusive Canonicalizers

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Constructs exclusive canonicalizers using a prefix list in NMTOKENS format.

```go
func MakeC14N10ExclusiveCanonicalizerWithPrefixList(prefixList string) Canonicalizer
```

```go
func MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList(prefixList string) Canonicalizer
```

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

### Define Signature struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the root Signature element.

```go
type Signature struct {
	XMLName        xml.Name        `xml:"http://www.w3.org/2000/09/xmldsig# Signature"`
	SignedInfo     *SignedInfo     `xml:"SignedInfo"`
	SignatureValue *SignatureValue `xml:"SignatureValue"`
	KeyInfo        *KeyInfo        `xml:"KeyInfo"`
	// contains filtered or unexported fields
}
```

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

### Signature element methods

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Methods for managing the underlying XML element of a Signature.

```go
func (s *Signature) SetUnderlyingElement(el *etree.Element)
```

```go
func (s *Signature) UnderlyingElement() *etree.Element
```

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

### Type: X509CertificateStore

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Interface for storing and retrieving X.509 certificates.

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

### NSDetatch

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Creates a copy of an element and declares namespaces from the provided context onto the new element.

```APIDOC
## NSDetatch

### Description
NSDetatch makes a copy of the passed element, and declares any namespaces in the passed context onto the new element before returning it.

### Parameters
- **ctx** (NSContext) - Required - The namespace context to apply.
- **el** (*etree.Element) - Required - The element to detach and copy.

### Response
- **(*etree.Element, error)** - Returns the new detached element or an error if the operation fails.
```

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

### Find XML Elements by Namespace

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Functions for locating elements within an etree structure using namespace-aware searches.

```go
func NSFindOneChild(el *etree.Element, namespace, tag string) (*etree.Element, error)
```

```go
func NSFindOneChildCtx(ctx NSContext, el *etree.Element, namespace, tag string) (*etree.Element, error)
```

```go
func NSFindOneCtx(ctx NSContext, el *etree.Element, namespace, tag string) (*etree.Element, error)
```

```go
func NSSelectOne(el *etree.Element, namespace, tag string) (*etree.Element, error)
```

```go
func NSSelectOneCtx(ctx NSContext, el *etree.Element, namespace, tag string) (*etree.Element, error)
```

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

### Null Canonicalizer

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Constructs a null canonicalizer implementation.

```go
func MakeNullCanonicalizer() Canonicalizer
```

```go
type NullCanonicalizer struct {
}
```

```go
func (c *NullCanonicalizer) Algorithm() AlgorithmID
```

```go
func (c *NullCanonicalizer) Canonicalize(el *etree.Element) ([]byte, error)
```

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

### Traverse and Iterate XML Elements

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Utilities for iterating over children or traversing entire element trees with context awareness.

```go
func NSIterateChildren(ctx NSContext, el *etree.Element, handle NSIterHandler) error
```

```go
func NSTraverse(ctx NSContext, el *etree.Element, handle NSIterHandler) error
```

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

### Set signature method

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Configures the signature method algorithm identifier.

```go
func (ctx *SigningContext) SetSignatureMethod(algorithmID string) error
```

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

### Type: TLSCertKeyStore

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

A key store that uses TLS certificates.

```APIDOC
## Type: TLSCertKeyStore

### GetChain Method

```go
func (d TLSCertKeyStore) GetChain() ([][]byte, error)
```

Retrieves the certificate chain.

### GetKeyPair Method

```go
func (d TLSCertKeyStore) GetKeyPair() (*rsa.PrivateKey, []byte, error)
```

Retrieves the RSA private key and its associated public certificate.
```

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

### Signing Context Functions

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Functions for creating and manipulating the signing context.

```APIDOC
## func NewSigningContext

### Description
NewSigningContext creates a new signing context with the given signer and certificate chain. Note that e.g. rsa.PrivateKey implements the crypto.Signer interface. The certificate chain is a slice of ASN.1 DER-encoded X.509 certificates. A SigningContext created with this function should not use the KeyStore field. It will return error if passed a nil crypto.Signer.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## func (*SigningContext) ConstructSignature

### Description
Constructs an enveloped signature for the given element.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## func (*SigningContext) GetDigestAlgorithmIdentifier

### Description
Gets the identifier for the digest algorithm used by the signing context.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## func (*SigningContext) GetSignatureMethodIdentifier

### Description
Gets the identifier for the signature method used by the signing context.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## func (*SigningContext) SetSignatureMethod

### Description
Sets the signature method to be used by the signing context.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## func (*SigningContext) SignEnveloped

### Description
Signs the given element using an enveloped signature.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## func (*SigningContext) SignString

### Description
Signs the given string content. Useful for signing query strings (including DEFLATED AuthnRequest) when using HTTP-Redirect to make a signed request. See 3.4.4.1 DEFLATE Encoding of https://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### XML and XMLNS Namespace Constants

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Defines constants for the standard XML and XMLNS namespaces.

```go
const (
	XMLNamespace   = "http://www.w3.org/XML/1998/namespace"
	XMLNSNamespace = "http://www.w3.org/2000/xmlns/"
)
```

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

### Type: MemoryX509CertificateStore

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

An in-memory store for X.509 certificates.

```APIDOC
## Type: MemoryX509CertificateStore

### Certificates Method

```go
func (mX509cs *MemoryX509CertificateStore) Certificates() ([]*x509.Certificate, error)
```

Retrieves all certificates stored in memory.
```

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

### Test Utility Function

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

A utility function for generating a random key store for testing purposes.

```APIDOC
## func RandomKeyStoreForTest

### Description
RandomKeyStoreForTest generates a random X509KeyStore suitable for testing.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Define Reference struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents a Reference element within a SignedInfo block.

```go
type Reference struct {
	XMLName     xml.Name     `xml:"http://www.w3.org/2000/09/xmldsig# Reference"`
	URI         string       `xml:"URI,attr"`
	DigestValue string       `xml:"DigestValue"`
	DigestAlgo  DigestMethod `xml:"DigestMethod"`
	Transforms  Transforms   `xml:"Transforms"`
}
```

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

### Define SignatureMethod struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the SignatureMethod element.

```go
type SignatureMethod struct {
	XMLName   xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# SignatureMethod"`
	Algorithm string   `xml:"Algorithm,attr"`
}
```

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

### NSFindOne

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Finds a single element matching the namespace and tag using the default namespace context.

```APIDOC
## NSFindOne

### Description
NSFindOne behaves identically to NSFindOneCtx, but uses DefaultNSContext for context.

### Parameters
- **el** (*etree.Element) - Required - The element to search within.
- **namespace** (string) - Required - The target namespace URI.
- **tag** (string) - Required - The target element tag name.

### Response
- **(*etree.Element, error)** - Returns the found element or an error if not found.
```

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

### NSFindOne Function

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Finds a single element matching the specified namespace and tag using the DefaultNSContext.

```go
func NSFindOne(el *etree.Element, namespace, tag string) (*etree.Element, error)
```

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

### Type: SigningContext

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Context for signing XML elements.

```APIDOC
## Type: SigningContext

### SigningContext Constructors

```go
func NewDefaultSigningContext(ks X509KeyStore) *SigningContext
func NewSigningContext(signer crypto.Signer, certs [][]byte) (*SigningContext, error)
```

### SigningContext Methods

```go
func (ctx *SigningContext) ConstructSignature(el *etree.Element, enveloped bool) (*etree.Element, error)
func (ctx *SigningContext) GetDigestAlgorithmIdentifier() string
func (ctx *SigningContext) GetSignatureMethodIdentifier() string
func (ctx *SigningContext) SetSignatureMethod(algorithmID string) error
func (ctx *SigningContext) SignEnveloped(el *etree.Element) (*etree.Element, error)
func (ctx *SigningContext) SignString(content string) ([]byte, error)
```

Provides methods for constructing and signing XML elements, including enveloped signatures, and managing signature methods.
```

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

### NSFindIterate Function

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Performs an element search using the DefaultNSContext, behaving identically to NSFindIterateCtx.

```go
func NSFindIterate(el *etree.Element, namespace, tag string, handle NSIterHandler) error
```

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

### Define InclusiveNamespaces struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the InclusiveNamespaces element for XML canonicalization.

```go
type InclusiveNamespaces struct {
	XMLName    xml.Name `xml:"http://www.w3.org/2001/10/xml-exc-c14n# InclusiveNamespaces"`
	PrefixList string   `xml:"PrefixList,attr"`
}
```

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

### NSFindChildrenIterateCtx Function

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Iterates through the children of an element, searching for matches based on namespace and tag, and invoking a handler for each match.

```go
func NSFindChildrenIterateCtx(ctx NSContext, el *etree.Element, namespace, tag string, handle NSIterHandler) error
```

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

### String Method for AlgorithmID

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Converts an AlgorithmID to its string representation.

```go
func (id AlgorithmID) String() string
```

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

### Canonicalizer Interface

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Defines the interface for XML canonicalization implementations.

```go
type Canonicalizer interface {
	Canonicalize(el *etree.Element) ([]byte, error)
	Algorithm() AlgorithmID
}
```

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

### Define ValidationContext

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Structure for validating XML signatures.

```go
type ValidationContext struct {
	CertificateStore X509CertificateStore
	IdAttribute      string
	Clock            *Clock
}
```

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

### Type: Clock

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Interface for time-related operations, allowing for mockable clocks.

```APIDOC
## Type: Clock

### Clock Constructors

```go
func NewFakeClock(wrapped clockwork.Clock) *Clock
func NewFakeClockAt(t time.Time) *Clock
func NewRealClock() *Clock
```

### Clock Methods

```go
func (c *Clock) After(d time.Duration) <-chan time.Time
func (c *Clock) Now() time.Time
func (c *Clock) Sleep(d time.Duration)
```

Provides methods for time-related operations like checking elapsed time, getting the current time, and sleeping.
```

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

### XML Unmarshaling and Transformation

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Utilities for unmarshaling XML elements into Go types and performing XML canonicalization.

```APIDOC
## NSUnmarshalElement

### Description
Unmarshals an etree Element into a Go value using encoding/xml within a specific namespace context.

### Parameters
- **ctx** (NSContext) - Required - The namespace context.
- **el** (*etree.Element) - Required - The element to unmarshal.
- **v** (any) - Required - The target value pointer.
```

```APIDOC
## TransformExcC14n

### Description
Transforms the passed element into xml-exc-c14n (Exclusive Canonical XML) form.

### Parameters
- **el** (*etree.Element) - Required - The element to transform.
- **inclusiveNamespacesPrefixList** (string) - Required - Prefix list for inclusive namespaces.
- **comments** (bool) - Required - Whether to include comments.
```

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

### Clock Abstraction

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Wraps clockwork.Clock to provide a real or fake clock for time-dependent operations.

```go
type Clock struct {
	// contains filtered or unexported fields
}
```

```go
func NewFakeClock(wrapped clockwork.Clock) *Clock
```

```go
func NewFakeClockAt(t time.Time) *Clock
```

```go
func NewRealClock() *Clock
```

```go
func (c *Clock) After(d time.Duration) <-chan time.Time
```

```go
func (c *Clock) Now() time.Time
```

```go
func (c *Clock) Sleep(d time.Duration)
```

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

### Include Signature Struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Include the types.Signature struct from the goxmldsig/types package in your application messages.

```go
import (
    sigtypes "github.com/russellhaering/goxmldsig/types"
)

type AppHdr struct {
    ...
    Signature *sigtypes.Signature
}

```

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

### Clock Implementation

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Provides a Clock struct that wraps a clockwork.Clock, defaulting to the real system clock when nil.

```APIDOC
## Structs

### Clock

`type Clock struct`

Clock wraps a clockwork.Clock, defaulting to the real system clock when a nil *Clock is used. This allows Clock to be easily added to structs with methods that currently reference the time package, without requiring every instantiation of that struct to be updated.

## Functions

### Clock Creation Functions

- `NewFakeClock(wrapped clockwork.Clock) *Clock`: Creates a new fake clock.
- `NewFakeClockAt(t time.Time) *Clock`: Creates a new fake clock at a specific time.
- `NewRealClock() *Clock`: Creates a new real clock.

## Methods

### (*Clock) Methods

- `After(d time.Duration) <-chan time.Time`: Returns a channel that delivers at times when the clock's time is after the duration.
- `Now() time.Time`: Returns the current time on the clock.
- `Sleep(d time.Duration)`: Sleeps for the specified duration.
```

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

### X509Certificate Type

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents an X509Certificate element within X509Data.

```APIDOC
## Type: X509Certificate

### Description
Represents an X509Certificate element within X509Data.

### Fields
- **XMLName** (xml.Name) - The XML element name and namespace.
- **Data** (string) - The base64 encoded certificate data.
```

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

### Validate XML Element

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Validates an etree.Element against a root certificate using a default validation context. Only use the returned validated element for security.

```go
// Validate an element against a root certificate
func validate(root *x509.Certificate, el *etree.Element) {
    // Construct a signing context with one or more roots of trust.
    ctx := dsig.NewDefaultValidationContext(&dsig.MemoryX509CertificateStore{
        Roots: []*x509.Certificate{root},
    })

    // It is important to only use the returned validated element.
    // See: https://www.w3.org/TR/xmldsig-best-practices/#check-what-is-signed
    validated, err := ctx.Validate(el)
    if err != nil {
        panic(err)
    }

    doc := etree.NewDocument()
    doc.SetRoot(validated)
    str, err := doc.WriteToString()
    if err != nil {
        panic(err)
    }

    println(str)
}

```

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

### NSFindIterateCtx Function

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Conducts a depth-first traversal to find elements matching a specific namespace and tag, invoking a handler for each. Traversal halts on error, with specific handling for ErrTraversalHalted.

```go
func NSFindIterateCtx(ctx NSContext, el *etree.Element, namespace, tag string, handle NSIterHandler) error
```

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

### NSIterHandler Definition

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Function signature for handling elements during traversal.

```go
type NSIterHandler func(NSContext, *etree.Element) error
```

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

### Constants

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Defines constants used throughout the goxmldsig library for namespaces, tags, and attributes.

```APIDOC
## Constants

### Namespace and Default Prefix

```go
const (
	DefaultPrefix = "ds"
	Namespace     = "http://www.w3.org/2000/09/xmldsig#"
)
```

### XML Element and Attribute Tags

```go
const (
	SignatureTag              = "Signature"
	SignedInfoTag             = "SignedInfo"
	CanonicalizationMethodTag = "CanonicalizationMethod"
	SignatureMethodTag        = "SignatureMethod"
	ReferenceTag              = "Reference"
	TransformsTag             = "Transforms"
	TransformTag              = "Transform"
	DigestMethodTag           = "DigestMethod"
	DigestValueTag            = "DigestValue"
	SignatureValueTag         = "SignatureValue"
	KeyInfoTag                = "KeyInfo"
	X509DataTag               = "X509Data"
	X509CertificateTag        = "X509Certificate"
	InclusiveNamespacesTag    = "InclusiveNamespaces"
)
```

### Attribute Names

```go
const (
	AlgorithmAttr  = "Algorithm"
	URIAttr        = "URI"
	DefaultIdAttr  = "ID"
	PrefixListAttr = "PrefixList"
)
```

### Signature Method Identifiers

```go
const (
	RSASHA1SignatureMethod     = "http://www.w3.org/2000/09/xmldsig#rsa-sha1"
	RSASHA256SignatureMethod   = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
	RSASHA384SignatureMethod   = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha384"
	RSASHA512SignatureMethod   = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"
	ECDSASHA1SignatureMethod   = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1"
	ECDSASHA256SignatureMethod = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"
	ECDSASHA384SignatureMethod = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384"
	ECDSASHA512SignatureMethod = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512"
)
```
```

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

### Canonicalizer Interface and Implementations

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Defines the Canonicalizer interface and provides functions to create various canonicalizer implementations.

```APIDOC
## Interfaces

### Canonicalizer

`type Canonicalizer interface`

Canonicalizer is an implementation of a canonicalization algorithm.

- `Canonicalize(el *etree.Element) ([]byte, error)`: Performs canonicalization on an etree.Element.
- `Algorithm() AlgorithmID`: Returns the AlgorithmID of the canonicalizer.

## Functions

### Canonicalizer Creation Functions

- `MakeC14N10ExclusiveCanonicalizerWithPrefixList(prefixList string) Canonicalizer`: Constructs an exclusive Canonicalizer with a prefix list.
- `MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList(prefixList string) Canonicalizer`: Constructs an exclusive Canonicalizer with comments and a prefix list (added in v1.2.0).
- `MakeC14N10RecCanonicalizer() Canonicalizer`: Constructs an inclusive canonicalizer (XML 1.0).
- `MakeC14N10WithCommentsCanonicalizer() Canonicalizer`: Constructs an inclusive canonicalizer with comments (XML 1.0, added in v1.2.0).
- `MakeC14N11Canonicalizer() Canonicalizer`: Constructs an inclusive canonicalizer (XML 1.1).
- `MakeC14N11WithCommentsCanonicalizer() Canonicalizer`: Constructs an inclusive canonicalizer with comments (XML 1.1, added in v1.2.0).
- `MakeNullCanonicalizer() Canonicalizer`: Constructs a null canonicalizer (added in v1.1.1).
```

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

### NSFindIterateCtx

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Conducts a depth-first traversal searching for elements with a specific tag and namespace using a provided context.

```APIDOC
## NSFindIterateCtx

### Description
NSFindIterateCtx conducts a depth-first traversal searching for elements with the specified tag in the specified namespace. It uses the passed NSContext for prefix lookups. For each such element, the passed handler function is invoked.

### Parameters
- **ctx** (NSContext) - Required - The namespace context for prefix lookups.
- **el** (*etree.Element) - Required - The root element to start the traversal.
- **namespace** (string) - Required - The target namespace URI.
- **tag** (string) - Required - The target element tag name.
- **handle** (NSIterHandler) - Required - The handler function invoked for each match.

### Response
- **error** - Returns nil on success, or an error if the handler returns one (unless it is ErrTraversalHalted).
```

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

### Variables

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Defines common error variables and well-known errors for the goxmldsig library.

```APIDOC
## Variables

### General Errors

```go
var (
	ErrNonRSAKey           = fmt.Errorf("Private key was not RSA")
	ErrMissingCertificates = fmt.Errorf("No public certificates provided")
)
```

### Signature Verification Errors

```go
var (
	// ErrMissingSignature indicates that no enveloped signature was found referencing
	// the top level element passed for signature verification.
	ErrMissingSignature = errors.New("Missing signature referencing the top-level element")
	ErrInvalidSignature = errors.New("Invalid Signature")
)
```
```

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

### Validation Context Functions

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Functions for creating and using the validation context.

```APIDOC
## type ValidationContext

### Description
ValidationContext holds the necessary information for validating XML signatures.

### Method
type

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Response Example
N/A
```

```APIDOC
## func NewDefaultValidationContext

### Description
NewDefaultValidationContext creates a new validation context with the given certificate store.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## func (*ValidationContext) Validate

### Description
Validate verifies that the passed element contains a valid enveloped signature matching a currently-valid certificate in the context's CertificateStore.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Define Transform struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents a single Transform element.

```go
type Transform struct {
	XMLName             xml.Name             `xml:"http://www.w3.org/2000/09/xmldsig# Transform"`
	Algorithm           string               `xml:"Algorithm,attr"`
	InclusiveNamespaces *InclusiveNamespaces `xml:"InclusiveNamespaces"`
}
```

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

### NullCanonicalizer Implementation

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

A NullCanonicalizer that performs no canonicalization.

```APIDOC
## Structs

### NullCanonicalizer

`type NullCanonicalizer struct` (added in v1.1.1)

## Methods

### (*NullCanonicalizer) Methods

- `Algorithm() AlgorithmID`: Returns the AlgorithmID for null canonicalization.
- `Canonicalize(el *etree.Element) ([]byte, error)`: Returns the raw bytes of the element without canonicalization.
```

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

### Validate an element

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Verifies that an element contains a valid enveloped signature.

```go
func (ctx *ValidationContext) Validate(el *etree.Element) (*etree.Element, error)
```

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

### Define DigestMethod struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the DigestMethod element in an XML signature.

```go
type DigestMethod struct {
	XMLName   xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# DigestMethod"`
	Algorithm string   `xml:"Algorithm,attr"`
}
```

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

### Define SignatureValue struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the SignatureValue element containing the signature data.

```go
type SignatureValue struct {
	XMLName xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# SignatureValue"`
	Data    string   `xml:",chardata"`
}
```

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

### etreeutils Error Variables

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Declares common error variables used within the etreeutils package for namespace and traversal issues.

```go
var (
	EmptyNSContext = NSContext{}

	ErrReservedNamespace       = errors.New("disallowed declaration of reserved namespace")
	ErrInvalidDefaultNamespace = errors.New("invalid default namespace declaration")
	ErrTraversalHalted         = errors.New("traversal halted")
	ErrTraversalLimit          = errors.New("traversal limit reached")
)
```

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

### Signature.UnderlyingElement Method

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Returns a reference to the XML element this Signature was unmarshaled from.

```APIDOC
## Method: (*Signature) UnderlyingElement

### Description
UnderlyingElement returns a reference to the Element this signature was unmarshaled from, where applicable.

### Returns
- **(*etree.Element)** - A reference to the underlying XML element.
```

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

### AlgorithmID Constants

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Defines the supported canonicalization and signature algorithms as constants of type AlgorithmID.

```APIDOC
## Constants

### AlgorithmID

`type AlgorithmID string`

Constants representing supported canonicalization algorithms:
- `CanonicalXML10ExclusiveAlgorithmId`: "http://www.w3.org/2001/10/xml-exc-c14n#"
- `CanonicalXML10ExclusiveWithCommentsAlgorithmId`: "http://www.w3.org/2001/10/xml-exc-c14n#WithComments"
- `CanonicalXML11AlgorithmId`: "http://www.w3.org/2006/12/xml-c14n11"
- `CanonicalXML11WithCommentsAlgorithmId`: "http://www.w3.org/2006/12/xml-c14n11#WithComments"
- `CanonicalXML10RecAlgorithmId`: "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
- `CanonicalXML10WithCommentsAlgorithmId`: "http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"
- `EnvelopedSignatureAltorithmId`: "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
```

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

### SortedAttrs Sorting Capabilities

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Type and methods for sorting attributes, useful for XML C14N compliance.

```go
type SortedAttrs []etree.Attr
```

```go
func (a SortedAttrs) Len() int
```

```go
func (a SortedAttrs) Less(i, j int) bool
```

```go
func (a SortedAttrs) Swap(i, j int)
```

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

### Define CanonicalizationMethod struct

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the CanonicalizationMethod element in an XML signature.

```go
type CanonicalizationMethod struct {
	XMLName   xml.Name `xml:"http://www.w3.org/2000/09/xmldsig# CanonicalizationMethod"`
	Algorithm string   `xml:"Algorithm,attr"`
}
```

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

### Type: Canonicalizer

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig

Interface for XML canonicalization.

```APIDOC
## Type: Canonicalizer

### Canonicalization Functions

```go
func MakeC14N10ExclusiveCanonicalizerWithPrefixList(prefixList string) Canonicalizer
func MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList(prefixList string) Canonicalizer
func MakeC14N10RecCanonicalizer() Canonicalizer
func MakeC14N10WithCommentsCanonicalizer() Canonicalizer
func MakeC14N11Canonicalizer() Canonicalizer
func MakeC14N11WithCommentsCanonicalizer() Canonicalizer
func MakeNullCanonicalizer() Canonicalizer
```

These functions create different types of canonicalizers for XML data.
```

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

### KeyInfo Type

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/types

Represents the KeyInfo element within an XML Digital Signature.

```APIDOC
## Type: KeyInfo

### Description
Represents the KeyInfo element within an XML Digital Signature.

### Fields
- **XMLName** (xml.Name) - The XML element name and namespace.
- **X509Data** (X509Data) - Contains X.509 certificate information.
```

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

### XML Element Search and Traversal

Source: https://pkg.go.dev/github.com/russellhaering/goxmldsig/etreeutils

Functions for searching and iterating through XML elements while respecting namespace contexts.

```APIDOC
## NSFindOneCtx

### Description
Conducts a depth-first search for the specified element within a given namespace context.

### Parameters
- **ctx** (NSContext) - Required - The namespace context.
- **el** (*etree.Element) - Required - The root element to search from.
- **namespace** (string) - Required - The namespace URI.
- **tag** (string) - Required - The element tag name.

### Response
- Returns (*etree.Element, error) - A reference to the found element or an error.
```

```APIDOC
## NSTraverse

### Description
Traverses an element tree, invoking the provided handler for each element in the tree.

### Parameters
- **ctx** (NSContext) - Required - The namespace context.
- **el** (*etree.Element) - Required - The root element.
- **handle** (NSIterHandler) - Required - The function to invoke for each element.
```