README ¶
signedxml
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.
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.
Install
go get github.com/ma314smith/signedxml
Included Algorithms
-
Hashes
-
Signatures
- http://www.w3.org/2001/04/xmldsig-more#rsa-md2
- http://www.w3.org/2001/04/xmldsig-more#rsa-md5
- http://www.w3.org/2000/09/xmldsig#rsa-sha1
- http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
- http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
- http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
- http://www.w3.org/2000/09/xmldsig#dsa-sha1
- http://www.w3.org/2000/09/xmldsig#dsa-sha256
- http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1
- http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256
- http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384
- http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512
-
Canonicalization Methods/Transforms
Examples
Validating signed XML
If your signed xml contains the signature and certificate, then you can just pass in the xml and call Validate()
.
validator, err := signedxml.NewValidator(`<YourXMLString></YourXMLString>`)
xml, err = validator.ValidateReferences()
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()
You can then verify that you trust the certificate. You can optionally supply your trusted certificates ahead of time by assigning them to the Certificates
property of the Validator
object, which is an x509.Certificate array.
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
It is expected that your XML contains the Signature element with all the parameters set (except DigestValue and SignatureValue).
signer, err := signedxml.NewSigner(`<YourXMLString></YourXMLString`)
signedXML, err := signer.Sign(`*rsa.PrivateKey object`)
Sign()
will generate the DigestValue and SignatureValue, populate it in the XML, and return the signed XML string.
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 {
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
}
signedxml.CanonicalizationAlgorithms["http://myTranform"] = 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")
Contributions
Contributions are welcome. Just fork the repo and send a pull request.
Documentation ¶
Overview ¶
Package signedxml transforms and validates signedxml documents
Index ¶
- Variables
- type CanonicalizationAlgorithm
- type EnvelopedSignature
- type ExclusiveCanonicalization
- type Signer
- type Validator
- func (v *Validator) SetReferenceIDAttribute(refIDAttribute string)
- func (s *Validator) SetSignature(sig string) error
- func (v *Validator) SetXML(xml string) error
- func (v *Validator) SigningCert() x509.Certificate
- func (v *Validator) Validate() errordeprecated
- func (v *Validator) ValidateReferences() ([]string, error)
Constants ¶
This section is empty.
Variables ¶
var CanonicalizationAlgorithms map[string]CanonicalizationAlgorithm
CanonicalizationAlgorithms maps the CanonicalizationMethod or Transform Algorithm URIs to a type that implements the CanonicalizationAlgorithm interface.
Implementations are provided for the following transforms:
http://www.w3.org/2001/10/xml-exc-c14n# (ExclusiveCanonicalization) http://www.w3.org/2001/10/xml-exc-c14n#WithComments (ExclusiveCanonicalizationWithComments) http://www.w3.org/2000/09/xmldsig#enveloped-signature (EnvelopedSignature)
Custom implementations can be added to the map
Functions ¶
This section is empty.
Types ¶
type CanonicalizationAlgorithm ¶
type CanonicalizationAlgorithm interface {
Process(inputXML string, transformXML string) (outputXML string, err error)
}
CanonicalizationAlgorithm defines an interface for processing an XML document into a standard format.
If any child elements are in the Transform node, the entire transform node will be passed to the Process method through the transformXML parameter as an XML string. This is necessary for transforms that need additional processing data, like XPath (http://www.w3.org/TR/xmldsig-core/#sec-XPath). If there are no child elements in Transform (or CanonicalizationMethod), then an empty string will be passed through.
type EnvelopedSignature ¶
type EnvelopedSignature struct{}
EnvelopedSignature implements the CanonicalizationAlgorithm interface and is used for processing the http://www.w3.org/2000/09/xmldsig#enveloped-signature transform algorithm
type ExclusiveCanonicalization ¶
type ExclusiveCanonicalization struct { WithComments bool // contains filtered or unexported fields }
ExclusiveCanonicalization implements the CanonicalizationAlgorithm interface and is used for processing the http://www.w3.org/2001/10/xml-exc-c14n# and http://www.w3.org/2001/10/xml-exc-c14n#WithComments transform algorithms
type Signer ¶
type Signer struct {
// contains filtered or unexported fields
}
Signer provides options for signing an XML document
func (*Signer) SetReferenceIDAttribute ¶
SetReferenceIDAttribute set the referenceIDAttribute
func (*Signer) SetSignature ¶
SetSignature can be used to assign an external signature for the XML doc that Validator will verify
type Validator ¶
type Validator struct { Certificates []x509.Certificate // contains filtered or unexported fields }
Validator provides options for verifying a signed XML document
func NewValidator ¶
NewValidator returns a *Validator for the XML provided
func (*Validator) SetReferenceIDAttribute ¶
SetReferenceIDAttribute set the referenceIDAttribute
func (*Validator) SetSignature ¶
SetSignature can be used to assign an external signature for the XML doc that Validator will verify
func (*Validator) SigningCert ¶
func (v *Validator) SigningCert() x509.Certificate
SigningCert returns the certificate, if any, that was used to successfully validate the signature of the XML document. This will be a zero value x509.Certificate before Validator.Validate is successfully called.
func (*Validator) ValidateReferences ¶
ValidateReferences validates the Reference digest values, and the signature value over the SignedInfo.
If the signature is enveloped in the XML, then it will be used. Otherwise, an external signature should be assigned using Validator.SetSignature.
The references returned by this method can be used to verify what was signed.