hyperledger/fabric · error

failed generating TLS Binding material

Error message

failed generating TLS Binding material

What it means

exportKM wraps tls.ConnectionState.ExportKeyingMaterial, used to build the TLS binding between a client and the ordering service. If the TLS stack cannot export keying material (most commonly because the connection's TLS session does not permit it — e.g. session resumption, TLS 1.3 exporter semantics, or a non-TLS connection), this wrapped error is returned.

Source

Thrown at orderer/common/cluster/util.go:683

	switch t := request.GetPayload().(type) {
	case *orderer.StepRequest_SubmitRequest:
		if t.SubmitRequest == nil || t.SubmitRequest.Payload == nil {
			return fmt.Sprintf("Empty SubmitRequest: %v", t.SubmitRequest)
		}
		return fmt.Sprintf("SubmitRequest for channel %s with payload of size %d",
			t.SubmitRequest.Channel, len(t.SubmitRequest.Payload.Payload))
	case *orderer.StepRequest_ConsensusRequest:
		return fmt.Sprintf("ConsensusRequest for channel %s with payload of size %d",
			t.ConsensusRequest.Channel, len(t.ConsensusRequest.Payload))
	default:
		return fmt.Sprintf("unknown type: %v", request)
	}
}

func exportKM(cs tls.ConnectionState, label string, context []byte) ([]byte, error) {
	tlsBinding, err := cs.ExportKeyingMaterial(label, context, 32)
	if err != nil {
		return nil, errors.Wrap(err, "failed generating TLS Binding material")
	}
	return tlsBinding, nil
}

func GetSessionBindingHash(authReq *orderer.NodeAuthRequest) []byte {
	return util.ComputeSHA256(util.ConcatenateBytes(
		[]byte(strconv.FormatUint(uint64(authReq.Version), 10)),
		EncodeTimestamp(authReq.Timestamp),
		[]byte(strconv.FormatUint(authReq.FromId, 10)),
		[]byte(strconv.FormatUint(authReq.ToId, 10)),
		[]byte(authReq.Channel),
	))
}

func GetTLSSessionBinding(ctx context.Context, bindingPayload []byte) ([]byte, error) {
	peerInfo, ok := peer.FromContext(ctx)
	if !ok {
		return nil, errors.New("failed extracting stream context")

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Ensure the connection is end-to-end TLS to the orderer — no TLS termination at a proxy/load balancer in front of the ordering port.
2. Disable TLS session resumption/tickets or require the extended master secret extension so keying material can be exported.
3. Align TLS versions/cipher suites in the orderer TLS config with the peers/clients (prefer TLS 1.2+ with EMS-supporting suites).
4. Check the wrapped cause for the exact TLS-layer reason and adjust tls.Config accordingly.

Example fix

// before: TLS terminated at proxy -> orderer sees no exportable session
// after: pass TLS through, or in tls.Config disable resumption
// tlsConfig := &tls.Config{ SessionTicketsDisabled: true, MinVersion: tls.VersionTLS12 }

// Ensure TLS version supports exporters and EMS before binding
if cs.Version < tls.VersionTLS12 {
    return errors.New("TLS binding requires TLS 1.2 or higher with EMS")
}

binding, err := exportKM(cs, label, context)
if err != nil {
    if strings.Contains(err.Error(), "failed generating TLS Binding material") {
        // re-establish a fresh (non-resumed) TLS connection and retry once
        conn = redialFreshTLS(addr, tlsConfig)
        return exportKM(conn.ConnectionState(), label, context)
    }
    return err
}

When it happens

Trigger: Calling exportKM (via the cluster mutual-TLS authentication path) when cs.ExportKeyingMaterial(label, context, 32) errors — typically on connections resumed via TLS session tickets, TLS versions/handshakes that disable exporters, or cipher suites without extended master secret.

Common situations: Orderer-client connections established through TLS-terminating proxies or load balancers (the orderer sees a resumed/re-terminated session), older TLS configurations without the extended-master-secret extension, misaligned TLS 1.3 usage between nodes.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• session binding read failed
• session binding mismatch
• invalid certificate DER
• forbidden pulling the channel
• failed to create new stream

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/765d414edc13aaf9. Report an issue: GitHub.