Skip to content

Verify one selected signature without using tags #169

Open

Description

@rosylilly

Use case

My ActivityPub server (mycroblog/my) verifies the first signature in Signature-Input, because its acceptance policy runs on that signature before the library is called. Fediverse signatures don't use tags, so WithRequiredTag can't select it, and I have to use WithValidateAllSignatures. Then any other signature on the message, such as one added by an intermediary, fails the whole call if it can't be verified.

Current workaround

I rebuild Signature-Input and Signature so they contain only the label I want, then pass that copy to Verify.

Possible shape

Now that #166 adds VerifyOption, WithLabel could be one:

result, err := verifier.Verify(msg, httpsig.WithLabel(label))

Only that signature would be selected, and a missing label would return NoApplicableSignatureError.

Security

The label isn't signed, but here it only chooses what to check. The signature must still verify, and a changed label fails closed.

A KeyResolver can't do this selection, because the time and component checks run before ResolveKey, so an unrelated signature could still fail the call.

I'm happy to open a PR if you'd like this.

Activity

  1. dadrus commented on Nov 4, 2026

    @dadrus
    Owner

    Thanks @rosylilly for the FR. I definitely see the need. I'm wondering however, how you see the policy configuration of the Verifieritself. Right now, the NewVerifier constructor function requires either WithValidateAllSignatures or at least one WithRequiredTag option to be present. That would mean, the entire code would look like this:

    verifier, err := httpsig.NewVerifier(
        resolver,
        httpsig.WithValidateAllSignatures(), // accept all signature
        httpsig.WithComponents("@method", "@target-uri"),
    )
    
    
    results, err := verifier.Verify(
        msg,
        httpsig.WithLabel("sig1"), // filter for this label
    )

    In my personal taste, this feels not natural and even contradicting. It would be much better if we could express the requirement like:

    verifier, err := httpsig.NewVerifier(
        resolver,
        httpsig.WithComponents("@method", "@target-uri"),
    )
    
    results, err := verifier.Verify(
        msg,
        httpsig.WithLabel("sig1"),
    )

    So, without the need to use httpsig.WithValidateAllSignatures(). This would however mean a bigger change. Maybe it would eben be better if we go one step further and introduce kind of a "signature selector", which would allow filtering of applicable signatures based on whatever properties of the signature.

    What are your thoughts on that?

  2. rosylilly commented on Nov 4, 2026

    @rosylilly
    ContributorAuthor

    I agree that WithValidateAllSignatures followed by WithLabel reads like a contradiction, and a selector sounds good to me. I'd also like to keep today's behaviour unchanged, including the construction error for a verifier with neither WithValidateAllSignatures nor WithRequiredTag. So how about making selection an explicit declaration on NewVerifier? The name is only a placeholder:

    verifier, err := httpsig.NewVerifier(
        resolver,
        httpsig.WithSignatureSelection(),
        httpsig.WithComponents("@method", "@target-uri"),
    )
    
    results, err := verifier.Verify(
        msg,
        httpsig.WithLabel("sig1"),
    )

    The behaviour would be:

    • WithSignatureSelection can't be combined with WithValidateAllSignatures, WithRequiredTag, or WithSignatureNegotiation. Each combination is a construction error.
    • Verify checks only the signature with that label and returns one result. The verifier's policy, such as WithComponents, applies to it, and other signatures don't affect the result.
    • If the message has no signature with that label, Verify returns NoApplicableSignatureError.
    • If WithLabel is missing, empty, or given more than once, Verify returns ErrParameter. The same applies to WithLabel on a verifier without the declaration, because ignoring it would verify signatures the caller didn't ask for.

    This would also leave room for your selector idea. Verify(msg, WithSignatureSelector(...)) could be added later under the same declaration, with WithLabel remaining as a shorthand, and nothing existing would need to change.

    What do you think?

  3. dadrus commented on Nov 4, 2026

    @dadrus
    Owner

    Like it! If you like, go for it and open a PR – ideally based on #166, so it'll be easier to rebase once #166 is merged.

  4. rosylilly commented on Nov 5, 2026

    @rosylilly
    ContributorAuthor

    @dadrus I've opened #174. Please review it.

  5. dadrus commented on Nov 10, 2026

    @dadrus
    Owner

    As agreed in the discussion of #174, this functionality will be implemented by replacing WithRequiredTag() and WithValidateAllSignatures() with a new API. The idea is to introduce a new WithExpectedSignature() option and to make it the only VerifierOption accepted by NewVerifier(). Each call would define a required signature profile, consisting of a SignatureSelector and its own verification options. This would eliminate the current global policy configuration and the inheritance and override rules between global and tag-specific policies, making the API much more consistent and easier to understand.

    The SignatureSelector would be defined as follows:

    type SignatureSelector struct {
        Label      string
        Tag        string
        Parameters SignatureParameters
    }

    This would allow signatures to be selected by label, tag, custom signature parameters, or any combination of them. For example:

    verifier, err := httpsig.NewVerifier(
        resolver,
        httpsig.WithExpectedSignature(
            httpsig.SignatureSelector{Label: "sig1"},
            httpsig.WithComponents(`"@method"`, `"@target-uri"`),
        ),
    )

    As already supported today, multiple required signature profiles could be configured, each with its own verification policy and optional signature negotiation. For example:

    verifier, err := httpsig.NewVerifier(
        resolver,
        httpsig.WithExpectedSignature(
            httpsig.SignatureSelector{
                Label: "sig1",
            },
            httpsig.WithComponents(`"@method"`, `"@target-uri"`),
            httpsig.WithValidityTolerance(5 * time.Second),
            httpsig.WithMaxAge(2 * time.Minute),
            httpsig.WithParameter("audience", "service-a"),
            httpsig.WithRequiredParameters("transaction-id"),
            httpsig.WithForbiddenParameters("legacy-mode"),
            httpsig.WithSignatureNegotiation(
                httpsig.WithKeyID("client-key"),
                httpsig.WithSignatureAlgorithm(httpsig.EcdsaP256Sha256),
                httpsig.WithNonceGetter(nonceGetter),
            ),
        ),
        httpsig.WithExpectedSignature(
            httpsig.SignatureSelector{
                Tag: "proxy-attestation",
                Parameters: httpsig.SignatureParameters{
                    "purpose": "request-forwarding",
                },
            },
            httpsig.WithComponents(`"@authority"`, `"content-digest"`),
            httpsig.WithParameter("issuer", "trusted-proxy"),
            httpsig.WithSignatureNegotiation(),
        ),
    )

    An empty selector (httpsig.SignatureSelector{}) would select all signatures. At least one signature must be present in this case.

    The semantics would be quite simple:

    • Each expected signature profile requires at least one matching signature.
    • All matching signatures must pass its verification policy.
    • If a signature matches multiple selectors, all applicable policies must be satisfied.
    • Signatures not matching any selector are not verified.

    As mentioned above, the existing verification policy options would still be available, but configured per expected signature profile. The existing security defaults (required created and expires, 30s maximum age and zero validity tolerance) would apply independently to each profile, unless explicitly overridden. I'd also require WithComponents() for each profile, even if called without arguments, to make the decision not to require any covered components explicit. Multiple calls would be cumulative.

    As can be seen from the examples above, signature negotiation would also be configured per expected signature. The selector criteria would automatically become part of the corresponding Accept-Signature requirements. Negotiation would not be allowed for an empty selector. If any required signature profile fails, negotiation would be prepared for all profiles having it enabled, leaving it to the application to decide whether to use it.

    The existing per-call VerifyOption mechanism would remain available, with its requirements applying to all selected signatures, cumulatively with the profile-specific policies.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions