webauthn_sign

README

webauthn-sign

ECDSA digital signatures with WebAuthn

---

This package implements digital signatures with WebAuthn. It depends on DuoLabs WebAuthn library.

Example

For full example, see https://github.com/pantonov/webauthn-sign-example .

Principles

WebAuthn uses ECDSA-P256 signatures to verify user credentials. However, it cannot be used for general purpose digital signatures as-is, because WebAuthn authenticators mix in various auxiliary data (such as origin, signature counter, etc.) into the data prior to signing. This can be resolved by creating compound signature which carries such auxiliary data along with ECDSA signature. This package defines this compound signature as Signature type.

The verification process is also slightly different: first, we check if challenge from Signature matches the hash of our data, and then we re-create full signature data (including auxiliary data from Signature) before checking ECDSA signature. This works because challenge in Signature can't be tampered with, otherwise ECDSA verification will fail.

Workflow

1. Register authenticator (hardware key) in the same way as for authentication, this provides webauthn.Credential
2. Use PrepareSignatureAssertion and ParseSignatureCredentialsResponse when interacting with authenticator (see example for details). The latter takes reply from authenticator and generates Signature
3. Use Signature.Verify (or Signature.VerifySha256) methods to verify signature of your data, providing it with Credential.PublicKey.

License

MIT

Documentation

Index

• func PrepareSignatureAssertion(wa *webauthn.WebAuthn, dataHash []byte, user webauthn.User) (*protocol.CredentialAssertion, error)
• type Signature
  • func ParseSignatureCredentialResponse(r *http.Request) (*Signature, error)
  • func (signature *Signature) Verify(pubKey []byte, dataHash []byte) (bool, error)
  • func (signature *Signature) VerifySha256(pubKey []byte, data []byte) (bool, error)

Functions

func PrepareSignatureAssertion

func PrepareSignatureAssertion(wa *webauthn.WebAuthn,
	dataHash []byte,
	user webauthn.User) (*protocol.CredentialAssertion, error)

PrepareSignatureAssertion prepares data for credentials.get() on browser. Use it only if you want your own implementation of sign requests.

Types

type Signature

type Signature struct {
	AuthenticatorData protocol.URLEncodedBase64 `json:"a"`
	ClientData        protocol.URLEncodedBase64 `json:"c"`
	SignatureData     protocol.URLEncodedBase64 `json:"s"`
}

Signature represents document hash signature object. Unlike normal ECDSA signature, it also carries some extra information (AuthenticatorData and ClientData), which is necessary to be hashed together with user data to check correctness of WebAuthn signature.

func ParseSignatureCredentialResponse

func ParseSignatureCredentialResponse(r *http.Request) (*Signature, error)

ParseSignatureCredentialResponse creates signature from CredentialRequestResponse.

func (*Signature) Verify

func (signature *Signature) Verify(pubKey []byte, dataHash []byte) (bool, error)

Verify data against the signature, provided COSE-encoded public key. Public key can be obtained during registration process as Credential.PubKey.

dataHash should be between 16 and 64 bytes long.

func (*Signature) VerifySha256

func (signature *Signature) VerifySha256(pubKey []byte, data []byte) (bool, error)

VerifySha256 hashes data with SHA256 before passing it to Verify().