Skip to content
moov-ioPublic

About

pure go library for processing signed XML documents

Resources

Security policy

Stars

66 stars

Watchers

4 watching

Forks

Latest commit

 

History

248 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Moov Banner Logo

moov-io/signedxml

GoDoc Build Status Coverage Status Go Report Card Repo Size MIT  License Slack Channel Twitter

The signedxml package transforms and validates signed xml documents. The main use case is to support Single Sign On protocols like SAML and WS-Federation.

The xmlenc subpackage provides XML Encryption 1.1 support for encrypting and decrypting XML documents.

Other packages that provide similar functionality rely on C libraries, which makes them difficult to run across platforms without significant configuration. signedxml is written in pure go, and can be easily used on any platform. This package was originally created by Matt Smith and is in use at Moov Financial.

Install

This project requires Go 1.26 or higher. The current go.mod also sets toolchain go1.27.4.

go get github.com/moov-io/signedxml

Runnable examples live in examples/.

Included Algorithms

Examples

Validating signed XML

If your signed xml contains the signature and certificate, then you can just pass in the xml and call ValidateReferences().

validator, err := signedxml.NewValidator(`<YourXMLString></YourXMLString>`)
if err != nil {
    // handle error
}
refs, err := validator.ValidateReferences()
if err != nil {
    // handle error
}
// Use only the returned refs, not the original document. Callers that ignore
// the returned references and keep using the input XML are vulnerable to XML
// injection and signature wrapping.

ValidateReferences() verifies the DigestValue and SignatureValue in the xml document, and returns the signed payload(s). If the error value is nil, then the signed xml is valid.

The x509.Certificate that was successfully used to validate the xml will be available by calling:

validator.SigningCert()

signedxml does not build a certificate chain or check expiry. Trust is the caller's responsibility:

  • If you do not set Validator.Certificates, any self-signed certificate embedded in the XML can be used to validate the signature. After a successful call you must check SigningCert() against your own trust store.
  • If you do set Certificates, only those certificates are tried. A signature produced by a different key fails with "Calculated signature does not match the SignatureValue provided", not a separate "untrusted signer" error.

Using an external Signature

If you need to specify an external Signature, you can use the SetSignature() function to assign it:

validator.SetSignature(`<Signature></Signature>`)

Generating signed XML

The input XML must already contain a Signature element with the parameters set (except DigestValue and SignatureValue). By default references are looked up with an ID attribute (ID="doc" with URI="#doc"). Include KeyInfo/X509Data/X509Certificate if you want the validator to find the certificate in the document.

Minimal enveloped-signature template:

<?xml version="1.0"?>
<Document ID="doc">
  <Amount>100.00</Amount>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
      <Reference URI="#doc">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
          <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
        <DigestValue></DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue></SignatureValue>
    <KeyInfo>
      <X509Data>
        <X509Certificate><!-- base64 DER of the signing certificate --></X509Certificate>
      </X509Data>
    </KeyInfo>
  </Signature>
</Document>
signer, err := signedxml.NewSigner(xml)
if err != nil {
    // handle error
}
signedXML, err := signer.Sign(privateKey) // *rsa.PrivateKey or ed25519.PrivateKey
if err != nil {
    // handle error
}

validator, err := signedxml.NewValidator(signedXML)
if err != nil {
    // handle error
}
validator.Certificates = []x509.Certificate{trustedCert}
refs, err := validator.ValidateReferences()

A complete sign-and-validate example is in examples/example_test.go.

Generating signed XML with Ed25519

Use the same template, with SignatureMethod set to http://www.w3.org/2021/04/xmldsig-more#eddsa-ed25519:

import (
    "crypto/ed25519"
    "crypto/rand"
)

signer, err := signedxml.NewSigner(xml)
if err != nil {
    // handle error
}
_, privKey, err := ed25519.GenerateKey(rand.Reader)
if err != nil {
    // handle error
}
signedXML, err := signer.Sign(privKey)

Implementing custom transforms

Additional Transform algorithms can be included by adding to the CanonicalizationAlgorithms map. This interface will need to be implemented:

type CanonicalizationAlgorithm interface {
	ProcessElement(inputXML *etree.Element, transformXML string) (outputXML string, err error)
	ProcessDocument(doc *etree.Document, transformXML string) (outputXML string, err error)
	Process(inputXML string, transformXML string) (outputXML string, err error)
}

Simple Example:

type NoChangeCanonicalization struct{}

func (n NoChangeCanonicalization) Process(inputXML string,
	transformXML string) (outputXML string, err error) {
	return inputXML, nil
}

func (n NoChangeCanonicalization) ProcessElement(inputXML *etree.Element,
	transformXML string) (outputXML string, err error) {
	doc := etree.NewDocument()
	doc.SetRoot(inputXML.Copy())
	return n.ProcessDocument(doc, transformXML)
}

func (n NoChangeCanonicalization) ProcessDocument(doc *etree.Document,
	transformXML string) (outputXML string, err error) {
	return doc.WriteToString()
}

signedxml.CanonicalizationAlgorithms["http://myTransform"] = NoChangeCanonicalization{}

See envelopedsignature.go and exclusivecanonicalization.go for examples of actual implementations.

Using a custom reference ID attribute

It is possible to set a custom reference ID attribute for both the signer and the validator. The default value is "ID"

Signer example:

signer.SetReferenceIDAttribute("customId")

Validator example:

validator.SetReferenceIDAttribute("customId")

Getting help

channel info
Twitter @moov You can follow Moov.io's Twitter feed to get updates on our project(s). You can also tweet us questions or just share blogs or stories.
GitHub Issue If you are able to reproduce a problem please open a GitHub Issue under the specific project that caused the error.
moov-io slack Join our slack channel to have an interactive discussion about the development of the project.

Contributions

Contributions are welcome. Just fork the repo and send a pull request.

Related Projects

  • Moov RTP20022 implements ISO20022 messages in Go for Real Time Payments (RTP)

About

pure go library for processing signed XML documents

Resources

Security policy

Stars

66 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages