webauthncose

Documentation

Index

• Variables
• func DisplayPublicKey(cpk []byte) string
• func HasherFromCOSEAlg(coseAlg COSEAlgorithmIdentifier) func() hash.Hash
• func ParsePublicKey(keyBytes []byte) (any, error)
• func VerifySignature(key any, data []byte, sig []byte) (bool, error)
• type COSEAlgorithmIdentifier
• type COSEEllipticCurve
• type COSEKeyType
• type EC2PublicKeyData
  • func ParseFIDOPublicKey(keyBytes []byte) (data EC2PublicKeyData, err error)
  • func (k *EC2PublicKeyData) TPMCurveID() tpm2.EllipticCurve
  • func (k *EC2PublicKeyData) Verify(data []byte, sig []byte) (bool, error)
• type Error
  • func (err *Error) Error() string
  • func (passedError *Error) WithDetails(details string) *Error
• type OKPPublicKeyData
  • func (k *OKPPublicKeyData) Verify(data []byte, sig []byte) (bool, error)
• type PublicKeyData
• type RSAPublicKeyData
  • func (k *RSAPublicKeyData) Verify(data []byte, sig []byte) (bool, error)
• type SignatureAlgorithm
  • func SigAlgFromCOSEAlg(coseAlg COSEAlgorithmIdentifier) SignatureAlgorithm

Variables

var (
	ErrUnsupportedKey = &Error{
		Type:    "invalid_key_type",
		Details: "Unsupported Public Key Type",
	}
	ErrUnsupportedAlgorithm = &Error{
		Type:    "unsupported_key_algorithm",
		Details: "Unsupported public key algorithm",
	}
	ErrSigNotProvidedOrInvalid = &Error{
		Type:    "signature_not_provided_or_invalid",
		Details: "Signature invalid or not provided",
	}
)

var SignatureAlgorithmDetails = []struct {
	algo    SignatureAlgorithm
	coseAlg COSEAlgorithmIdentifier
	name    string
	hasher  func() hash.Hash
}{
	{SHA1WithRSA, AlgRS1, "SHA1-RSA", crypto.SHA1.New},
	{SHA256WithRSA, AlgRS256, "SHA256-RSA", crypto.SHA256.New},
	{SHA384WithRSA, AlgRS384, "SHA384-RSA", crypto.SHA384.New},
	{SHA512WithRSA, AlgRS512, "SHA512-RSA", crypto.SHA512.New},
	{SHA256WithRSAPSS, AlgPS256, "SHA256-RSAPSS", crypto.SHA256.New},
	{SHA384WithRSAPSS, AlgPS384, "SHA384-RSAPSS", crypto.SHA384.New},
	{SHA512WithRSAPSS, AlgPS512, "SHA512-RSAPSS", crypto.SHA512.New},
	{ECDSAWithSHA256, AlgES256, "ECDSA-SHA256", crypto.SHA256.New},
	{ECDSAWithSHA384, AlgES384, "ECDSA-SHA384", crypto.SHA384.New},
	{ECDSAWithSHA512, AlgES512, "ECDSA-SHA512", crypto.SHA512.New},
	{UnknownSignatureAlgorithm, AlgEdDSA, "EdDSA", crypto.SHA512.New},
}

Functions

func DisplayPublicKey

func DisplayPublicKey(cpk []byte) string

func HasherFromCOSEAlg

func HasherFromCOSEAlg(coseAlg COSEAlgorithmIdentifier) func() hash.Hash

HasherFromCOSEAlg returns the Hashing interface to be used for a given COSE Algorithm.

func ParsePublicKey

func ParsePublicKey(keyBytes []byte) (any, error)

ParsePublicKey figures out what kind of COSE material was provided and create the data for the new key.

func VerifySignature

func VerifySignature(key any, data []byte, sig []byte) (bool, error)

Types

type COSEAlgorithmIdentifier

type COSEAlgorithmIdentifier int

COSEAlgorithmIdentifier is a number identifying a cryptographic algorithm. The algorithm identifiers SHOULD be values registered in the IANA COSE Algorithms registry [https://www.w3.org/TR/webauthn/#biblio-iana-cose-algs-reg], for instance, -7 for "ES256" and -257 for "RS256".

Specification: §5.8.5. Cryptographic Algorithm Identifier (https://www.w3.org/TR/webauthn/#sctn-alg-identifier)

const (
	// AlgES256 ECDSA with SHA-256.
	AlgES256 COSEAlgorithmIdentifier = -7

	// AlgES384 ECDSA with SHA-384.
	AlgES384 COSEAlgorithmIdentifier = -35

	// AlgES512 ECDSA with SHA-512.
	AlgES512 COSEAlgorithmIdentifier = -36

	// AlgRS1 RSASSA-PKCS1-v1_5 with SHA-1.
	AlgRS1 COSEAlgorithmIdentifier = -65535

	// AlgRS256 RSASSA-PKCS1-v1_5 with SHA-256.
	AlgRS256 COSEAlgorithmIdentifier = -257

	// AlgRS384 RSASSA-PKCS1-v1_5 with SHA-384.
	AlgRS384 COSEAlgorithmIdentifier = -258

	// AlgRS512 RSASSA-PKCS1-v1_5 with SHA-512.
	AlgRS512 COSEAlgorithmIdentifier = -259

	// AlgPS256 RSASSA-PSS with SHA-256.
	AlgPS256 COSEAlgorithmIdentifier = -37

	// AlgPS384 RSASSA-PSS with SHA-384.
	AlgPS384 COSEAlgorithmIdentifier = -38

	// AlgPS512 RSASSA-PSS with SHA-512.
	AlgPS512 COSEAlgorithmIdentifier = -39

	// AlgEdDSA EdDSA.
	AlgEdDSA COSEAlgorithmIdentifier = -8

	// AlgES256K is ECDSA using secp256k1 curve and SHA-256.
	AlgES256K COSEAlgorithmIdentifier = -47
)

type COSEEllipticCurve

type COSEEllipticCurve int

COSEEllipticCurve is an enumerator that represents the COSE Elliptic Curves.

Specification: https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves

const (
	// EllipticCurveReserved is the COSE EC Reserved value.
	EllipticCurveReserved COSEEllipticCurve = iota

	// P256 represents NIST P-256 also known as secp256r1.
	P256

	// P384 represents NIST P-384 also known as secp384r1.
	P384

	// P521 represents NIST P-521 also known as secp521r1.
	P521

	// X25519 for use w/ ECDH only.
	X25519

	// X448 for use w/ ECDH only.
	X448

	// Ed25519 for use w/ EdDSA only.
	Ed25519

	// Ed448 for use w/ EdDSA only.
	Ed448

	// Secp256k1 is the SECG secp256k1 curve.
	Secp256k1
)

type COSEKeyType

type COSEKeyType int

COSEKeyType is The Key type derived from the IANA COSE AuthData.

const (
	// KeyTypeReserved is a reserved value.
	KeyTypeReserved COSEKeyType = iota

	// OctetKey is an Octet Key.
	OctetKey

	// EllipticKey is an Elliptic Curve Public Key.
	EllipticKey

	// RSAKey is an RSA Public Key.
	RSAKey

	// Symmetric Keys.
	Symmetric

	// HSSLMS is the public key for HSS/LMS hash-based digital signature.
	HSSLMS
)

type EC2PublicKeyData

type EC2PublicKeyData struct {
	PublicKeyData

	// If the key type is EC2, the curve on which we derive the signature from.
	Curve int64 `cbor:"-1,keyasint,omitempty" json:"crv"`

	// A byte string 32 bytes in length that holds the x coordinate of the key.
	XCoord []byte `cbor:"-2,keyasint,omitempty" json:"x"`

	// A byte string 32 bytes in length that holds the y coordinate of the key.
	YCoord []byte `cbor:"-3,keyasint,omitempty" json:"y"`
}

func ParseFIDOPublicKey

func ParseFIDOPublicKey(keyBytes []byte) (data EC2PublicKeyData, err error)

ParseFIDOPublicKey is only used when the appID extension is configured by the assertion response.

func (*EC2PublicKeyData) TPMCurveID

func (k *EC2PublicKeyData) TPMCurveID() tpm2.EllipticCurve

func (*EC2PublicKeyData) Verify

func (k *EC2PublicKeyData) Verify(data []byte, sig []byte) (bool, error)

Verify Elliptic Curve Public Key Signature.

type Error

type Error struct {
	// Short name for the type of error that has occurred.
	Type string `json:"type"`
	// Additional details about the error.
	Details string `json:"error"`
	// Information to help debug the error.
	DevInfo string `json:"debug"`
}

func (*Error) Error

func (err *Error) Error() string

func (*Error) WithDetails

func (passedError *Error) WithDetails(details string) *Error

type OKPPublicKeyData

type OKPPublicKeyData struct {
	PublicKeyData

	Curve int64

	// A byte string that holds the x coordinate of the key.
	XCoord []byte `cbor:"-2,keyasint,omitempty" json:"x"`
}

func (*OKPPublicKeyData) Verify

func (k *OKPPublicKeyData) Verify(data []byte, sig []byte) (bool, error)

Verify Octet Key Pair (OKP) Public Key Signature.

type PublicKeyData

type PublicKeyData struct {

	// The type of key created. Should be OKP, EC2, or RSA.
	KeyType int64 `cbor:"1,keyasint" json:"kty"`

	// A COSEAlgorithmIdentifier for the algorithm used to derive the key signature.
	Algorithm int64 `cbor:"3,keyasint" json:"alg"`
	// contains filtered or unexported fields
}

PublicKeyData The public key portion of a Relying Party-specific credential key pair, generated by an authenticator and returned to a Relying Party at registration time. We unpack this object using fxamacker's cbor library ("github.com/fxamacker/cbor/v2") which is why there are cbor tags included. The tag field values correspond to the IANA COSE keys that give their respective values.

Specification: §6.4.1.1. Examples of credentialPublicKey Values Encoded in COSE_Key Format (https://www.w3.org/TR/webauthn/#sctn-encoded-credPubKey-examples)

type RSAPublicKeyData

type RSAPublicKeyData struct {
	PublicKeyData

	// Represents the modulus parameter for the RSA algorithm.
	Modulus []byte `cbor:"-1,keyasint,omitempty" json:"n"`

	// Represents the exponent parameter for the RSA algorithm.
	Exponent []byte `cbor:"-2,keyasint,omitempty" json:"e"`
}

func (*RSAPublicKeyData) Verify

func (k *RSAPublicKeyData) Verify(data []byte, sig []byte) (bool, error)

Verify RSA Public Key Signature.

type SignatureAlgorithm

type SignatureAlgorithm int

SignatureAlgorithm represents algorithm enumerations used for COSE signatures.

const (
	UnknownSignatureAlgorithm SignatureAlgorithm = iota
	MD2WithRSA
	MD5WithRSA
	SHA1WithRSA
	SHA256WithRSA
	SHA384WithRSA
	SHA512WithRSA
	DSAWithSHA1
	DSAWithSHA256
	ECDSAWithSHA1
	ECDSAWithSHA256
	ECDSAWithSHA384
	ECDSAWithSHA512
	SHA256WithRSAPSS
	SHA384WithRSAPSS
	SHA512WithRSAPSS
)

func SigAlgFromCOSEAlg

func SigAlgFromCOSEAlg(coseAlg COSEAlgorithmIdentifier) SignatureAlgorithm

SigAlgFromCOSEAlg return which signature algorithm is being used from the COSE Key.