dsig

package module
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 30, 2022 License: Apache-2.0 Imports: 20 Imported by: 0

README

goxmldsig

Build Status GoDoc

XML Digital Signatures implemented in pure Go.

Installation

Install goxmldsig using go get:

$ go get github.com/russellhaering/goxmldsig

Usage

Signing
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)
}
Signature Validation
// 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-bestpractices/#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)
}
Working with Manifest
package main

import (
    "crypto"
    "github.com/beevik/etree"
    "github.com/austdev/goxmldsig"
    "github.com/austdev/goxmldsig/types"
)

func main() {
    // Generate a key and self-signed certificate for signing
    randomKeyStore := dsig.RandomKeyStoreForTest()
    ctx := dsig.NewDefaultSigningContext(randomKeyStore)

    digest := []byte{0x45, 0xf1, 0xab, 0xd7, 0x8a, 0x6f, 0x92, 0xe6, 0xa4, 0xb6, 0x8e, 0xba, 0x8f, 0xe7, 0x91, 0x96, 0xe0, 0xb2, 0x16, 0xd6, 0x0b, 0x82, 0x1b, 0x00, 0x45, 0xfa, 0xb8, 0xad, 0xd4, 0xfa, 0xff, 0xf9}

    sig := ctx.CreateSignature("id1234")

    // Get SHA256 hash of "package" data and add it as a reference
    err := ctx.AddManifestRef(sig, "package", crypto.SHA256, digest)
    if err != nil {
        panic(err)
    }

    // Sign the signature
    signed, err := ctx.SignManifest(sig)
    if err != nil {
        panic(err)
    }

    // Serialize the signature.
    doc := etree.NewDocument()
    doc.SetRoot(signed)
    str, err := doc.WriteToString()
    if err != nil {
        panic(err)
    }

    println(str)
}

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

    manifest, err := ctx.ValidateManifest(signed)
    if err != nil {
        panic(err)
    }

    for idx := range manifest.References {
        ref := &manifest.References[idx]
        // Pass raw data of "package" for validating
        err := ctx.VerifyReference(ref, test_data)
        if err != nil {
            panic(err)
        }
    }
}

Limitations

This library was created in order to implement SAML 2.0 without needing to execute a command line tool to create and validate signatures. It currently only implements the subset of relevant standards needed to support that implementation, but I hope to make it more complete over time. Contributions are welcome.

Documentation

Index

Constants

View Source 
const (
	DefaultPrefix = "ds"
	Namespace     = "http://www.w3.org/2000/09/xmldsig#"
)
View Source 
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"
	ObjectTag                 = "Object"
	ManifestTag               = "Manifest"
)

Tags

View Source 
const (
	AlgorithmAttr  = "Algorithm"
	TypeAttr       = "Type"
	URIAttr        = "URI"
	DefaultIdAttr  = "ID"
	PrefixListAttr = "PrefixList"
	ManifestPrefix = "Package"
)
View Source 
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"
)
View Source 
const (
	ManifestRefType = "http://www.w3.org/2000/09/xmldsig#Manifest"
)

Variables

View Source 
var (
	ErrNotSigner           = fmt.Errorf("private key does not implement crypto.Signer")
	ErrNonRSAKey           = fmt.Errorf("private key was not RSA")
	ErrMissingCertificates = fmt.Errorf("no public certificates provided")
)

Well-known errors

View Source 
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")

	ErrUnsupportedMethod = errors.New("dsig: unsupported algorithm")
	ErrInvalidSignature  = errors.New("dsig: invalid signature")
	ErrBadCertificate    = errors.New("dsig: bad certificate")
	ErrInvalidDigest     = errors.New("dsig: digest was broken")
)

Functions

This section is empty.

Types

type AlgorithmID 

type AlgorithmID string
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"
)

Well-known signature algorithms

func (AlgorithmID) String 

func (id AlgorithmID) String() string

type Canonicalizer 

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

Canonicalizer is an implementation of a canonicalization algorithm.

func MakeC14N10ExclusiveCanonicalizerWithPrefixList 

func MakeC14N10ExclusiveCanonicalizerWithPrefixList(prefixList string) Canonicalizer

MakeC14N10ExclusiveCanonicalizerWithPrefixList constructs an exclusive Canonicalizer from a PrefixList in NMTOKENS format (a white space separated list).

func MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList 

func MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList(prefixList string) Canonicalizer

MakeC14N10ExclusiveWithCommentsCanonicalizerWithPrefixList constructs an exclusive Canonicalizer from a PrefixList in NMTOKENS format (a white space separated list).

func MakeC14N10RecCanonicalizer 

func MakeC14N10RecCanonicalizer() Canonicalizer

MakeC14N10RecCanonicalizer constructs an inclusive canonicalizer.

func MakeC14N10WithCommentsCanonicalizer 

func MakeC14N10WithCommentsCanonicalizer() Canonicalizer

MakeC14N10WithCommentsCanonicalizer constructs an inclusive canonicalizer.

func MakeC14N11Canonicalizer 

func MakeC14N11Canonicalizer() Canonicalizer

MakeC14N11Canonicalizer constructs an inclusive canonicalizer.

func MakeC14N11WithCommentsCanonicalizer 

func MakeC14N11WithCommentsCanonicalizer() Canonicalizer

MakeC14N11WithCommentsCanonicalizer constructs an inclusive canonicalizer.

func MakeNullCanonicalizer 

func MakeNullCanonicalizer() Canonicalizer

type CertificateVerifier added in v1.4.1 

type CertificateVerifier interface {
	VerifyKeyChain(x509data [][]byte) (*x509.Certificate, error)
}

type Clock 

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

Clock wraps a clockwork.Clock (which could be real or fake) in order to default to a real clock when a nil *Clock is used. In other words, if you attempt to use a nil *Clock it will defer to the real system clock. 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.

func NewFakeClock 

func NewFakeClock(wrapped clockwork.Clock) *Clock

func NewFakeClockAt 

func NewFakeClockAt(t time.Time) *Clock

func NewRealClock 

func NewRealClock() *Clock

func (*Clock) After 

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

func (*Clock) Now 

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

func (*Clock) Sleep 

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

type CryptoSigner added in v1.4.0 

type CryptoSigner interface {
	Signer() (signer crypto.Signer, err error)
}

type MemoryX509CertificateStore 

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

func (*MemoryX509CertificateStore) Certificates 

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

type MemoryX509KeyStore 

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

func (*MemoryX509KeyStore) GetKeyPair 

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

type MemoryX509Signer added in v1.4.0 

type MemoryX509Signer struct {
	// contains filtered or unexported fields
}

func (*MemoryX509Signer) GetChain added in v1.4.0 

func (ms *MemoryX509Signer) GetChain() ([][]byte, error)

func (*MemoryX509Signer) GetKeyPair added in v1.4.0 

func (ms *MemoryX509Signer) GetKeyPair() (*rsa.PrivateKey, []byte, error)

func (*MemoryX509Signer) Signer added in v1.4.0 

func (ms *MemoryX509Signer) Signer() (signer crypto.Signer, err error)

type NullCanonicalizer 

type NullCanonicalizer struct {
}

func (*NullCanonicalizer) Algorithm 

func (c *NullCanonicalizer) Algorithm() AlgorithmID

func (*NullCanonicalizer) Canonicalize 

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

type SigningContext 

type SigningContext struct {
	Hash          crypto.Hash
	KeyStore      X509KeyStore
	IdAttribute   string
	Prefix        string
	Canonicalizer Canonicalizer
}

func NewDefaultSigningContext 

func NewDefaultSigningContext(ks X509KeyStore) *SigningContext

func (*SigningContext) AddManifestRef 

func (ctx *SigningContext) AddManifestRef(sig *etree.Element, name string, hash_id crypto.Hash, digest []byte) error

func (*SigningContext) ConstructSignature 

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

func (*SigningContext) CreateSignature 

func (ctx *SigningContext) CreateSignature(id string) *etree.Element

func (*SigningContext) GetDigestAlgorithmIdentifier 

func (ctx *SigningContext) GetDigestAlgorithmIdentifier() string

func (*SigningContext) GetSignatureMethodIdentifier 

func (ctx *SigningContext) GetSignatureMethodIdentifier() string

func (*SigningContext) SetSignatureMethod 

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

func (*SigningContext) SignEnveloped 

func (ctx *SigningContext) SignEnveloped(el *etree.Element) (*etree.Element, error)

func (*SigningContext) SignManifest added in v1.4.0 

func (ctx *SigningContext) SignManifest(sig *etree.Element) (*etree.Element, error)

func (*SigningContext) SignString 

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

Useful for signing query string (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

type TLSCertKeyStore 

type TLSCertKeyStore tls.Certificate

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

func (TLSCertKeyStore) GetChain 

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

GetChain impliments X509ChainStore using the underlying tls.Certificate

func (TLSCertKeyStore) GetKeyPair 

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

GetKeyPair implements X509KeyStore using the underlying tls.Certificate

func (TLSCertKeyStore) Signer added in v1.4.0 

func (d TLSCertKeyStore) Signer() (crypto.Signer, error)

type ValidationContext 

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

func NewDefaultValidationContext 

func NewDefaultValidationContext(certificateStore X509CertificateStore) *ValidationContext

func (*ValidationContext) DecodeRef 

func (ctx *ValidationContext) DecodeRef(ref *types.Reference) (crypto.Hash, []byte, error)

func (*ValidationContext) Validate 

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

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

func (*ValidationContext) ValidateManifest 

func (ctx *ValidationContext) ValidateManifest(el *etree.Element) (*types.Manifest, error)

Validate verifies that the passed element contains a valid signatures matching a currently-valid certificate in the context's CertificateStore.

func (*ValidationContext) VerifyReference 

func (ctx *ValidationContext) VerifyReference(ref *types.Reference, data []byte) error

Caclculate and compare digest of referenced element

type X509CertificateStore 

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

type X509ChainStore 

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

type X509KeyStore 

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

func RandomKeyStoreByType added in v1.4.0 

func RandomKeyStoreByType(algorithmID string) X509KeyStore

func RandomKeyStoreForTest 

func RandomKeyStoreForTest() X509KeyStore

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.