odoh

README

odoh-go

This library implements version 0x0001 of Oblivious DoH. It is based on the original implementation available here.

Test vector generation

To generate test vectors, run:

$ ODOH_TEST_VECTORS_OUT=test-vectors.json go test -v -run TestVectorGenerate

To check test vectors, run:

$ ODOH_TEST_VECTORS_IN=test-vectors.json go test -v -run TestVectorVerify

Documentation

Index

• Constants
• func SealQuery(dnsQuery []byte, publicKey ObliviousDoHConfigContents) (ObliviousDNSMessage, QueryContext, error)
• type ObliviousDNSMessage
  • func CreateObliviousDNSMessage(messageType ObliviousMessageType, keyID []byte, encryptedMessage []byte) *ObliviousDNSMessage
  • func UnmarshalDNSMessage(data []byte) (ObliviousDNSMessage, error)
  • func (m ObliviousDNSMessage) Marshal() []byte
  • func (m ObliviousDNSMessage) Type() ObliviousMessageType
• type ObliviousDNSMessageBody
  • func UnmarshalMessageBody(data []byte) (ObliviousDNSMessageBody, error)
  • func (m ObliviousDNSMessageBody) Marshal() []byte
  • func (m ObliviousDNSMessageBody) Message() []byte
• type ObliviousDNSQuery
  • func CreateObliviousDNSQuery(query []byte, paddingBytes uint16) *ObliviousDNSQuery
  • func UnmarshalQueryBody(data []byte) (*ObliviousDNSQuery, error)
• type ObliviousDNSResponse
  • func CreateObliviousDNSResponse(response []byte, paddingBytes uint16) *ObliviousDNSResponse
  • func UnmarshalResponseBody(data []byte) (*ObliviousDNSResponse, error)
• type ObliviousDoHConfig
  • func CreateObliviousDoHConfig(contents ObliviousDoHConfigContents) ObliviousDoHConfig
  • func UnmarshalObliviousDoHConfig(buffer []byte) (ObliviousDoHConfig, error)
  • func (c ObliviousDoHConfig) Marshal() []byte
• type ObliviousDoHConfigContents
  • func CreateObliviousDoHConfigContents(kemID hpke.KEMID, kdfID hpke.KDFID, aeadID hpke.AEADID, publicKeyBytes []byte) (ObliviousDoHConfigContents, error)
  • func UnmarshalObliviousDoHConfigContents(buffer []byte) (ObliviousDoHConfigContents, error)
  • func (k ObliviousDoHConfigContents) CipherSuite() (hpke.CipherSuite, error)
  • func (targetKey ObliviousDoHConfigContents) EncryptQuery(query *ObliviousDNSQuery) (ObliviousDNSMessage, QueryContext, error)
  • func (k ObliviousDoHConfigContents) KeyID() []byte
  • func (k ObliviousDoHConfigContents) Marshal() []byte
  • func (k ObliviousDoHConfigContents) PublicKey() []byte
• type ObliviousDoHConfigs
  • func CreateObliviousDoHConfigs(configs []ObliviousDoHConfig) ObliviousDoHConfigs
  • func UnmarshalObliviousDoHConfigs(buffer []byte) (ObliviousDoHConfigs, error)
  • func (c ObliviousDoHConfigs) Marshal() []byte
• type ObliviousDoHKeyPair
  • func CreateDefaultKeyPair() (ObliviousDoHKeyPair, error)
  • func CreateDefaultKeyPairFromSeed(seed []byte) (ObliviousDoHKeyPair, error)
  • func CreateKeyPair(kemID hpke.KEMID, kdfID hpke.KDFID, aeadID hpke.AEADID) (ObliviousDoHKeyPair, error)
  • func CreateKeyPairFromSeed(kemID hpke.KEMID, kdfID hpke.KDFID, aeadID hpke.AEADID, ikm []byte) (ObliviousDoHKeyPair, error)
  • func (privateKey ObliviousDoHKeyPair) DecryptQuery(message ObliviousDNSMessage) (*ObliviousDNSQuery, ResponseContext, error)
• type ObliviousMessageType
• type QueryContext
  • func (c QueryContext) DecryptResponse(message ObliviousDNSMessage) ([]byte, error)
  • func (c QueryContext) OpenAnswer(message ObliviousDNSMessage) ([]byte, error)
• type ResponseContext
  • func (c ResponseContext) EncryptResponse(response *ObliviousDNSResponse) (ObliviousDNSMessage, error)

Constants

const (
	ODOH_VERSION                    = uint16(0xFF06)
	ODOH_VERSION_ONE                = uint16(0x0001)
	ODOH_SECRET_LENGTH              = 32
	ODOH_PADDING_BYTE               = uint8(0)
	ODOH_LABEL_KEY_ID               = "odoh key id"
	ODOH_LABEL_KEY                  = "odoh key"
	ODOH_LABEL_NONCE                = "odoh nonce"
	ODOH_LABEL_QUERY                = "odoh query"
	ODOH_LABEL_RESPONSE             = "odoh response"
	ODOH_DEFAULT_KEMID  hpke.KEMID  = hpke.DHKEM_X25519
	ODOH_DEFAULT_KDFID  hpke.KDFID  = hpke.KDF_HKDF_SHA256
	ODOH_DEFAULT_AEADID hpke.AEADID = hpke.AEAD_AESGCM128
)

Functions

func SealQuery

func SealQuery(dnsQuery []byte, publicKey ObliviousDoHConfigContents) (ObliviousDNSMessage, QueryContext, error)

Types

type ObliviousDNSMessage

type ObliviousDNSMessage struct {
	MessageType      ObliviousMessageType
	KeyID            []byte
	EncryptedMessage []byte
}

struct {
   uint8  message_type;
   opaque key_id<0..2^16-1>;
   opaque encrypted_message<1..2^16-1>;
} ObliviousDoHMessage;

func CreateObliviousDNSMessage

func CreateObliviousDNSMessage(messageType ObliviousMessageType, keyID []byte, encryptedMessage []byte) *ObliviousDNSMessage

func UnmarshalDNSMessage

func UnmarshalDNSMessage(data []byte) (ObliviousDNSMessage, error)

func (ObliviousDNSMessage) Marshal

func (m ObliviousDNSMessage) Marshal() []byte

func (ObliviousDNSMessage) Type

func (m ObliviousDNSMessage) Type() ObliviousMessageType

type ObliviousDNSMessageBody

type ObliviousDNSMessageBody struct {
	DnsMessage []byte
	Padding    []byte
}

struct {
   opaque dns_message<1..2^16-1>;
   opaque padding<0..2^16-1>;
} ObliviousDoHQueryBody;

func UnmarshalMessageBody

func UnmarshalMessageBody(data []byte) (ObliviousDNSMessageBody, error)

func (ObliviousDNSMessageBody) Marshal

func (m ObliviousDNSMessageBody) Marshal() []byte

func (ObliviousDNSMessageBody) Message

func (m ObliviousDNSMessageBody) Message() []byte

type ObliviousDNSQuery

type ObliviousDNSQuery struct {
	ObliviousDNSMessageBody
}

func CreateObliviousDNSQuery

func CreateObliviousDNSQuery(query []byte, paddingBytes uint16) *ObliviousDNSQuery

func UnmarshalQueryBody

func UnmarshalQueryBody(data []byte) (*ObliviousDNSQuery, error)

type ObliviousDNSResponse

type ObliviousDNSResponse struct {
	ObliviousDNSMessageBody
}

func CreateObliviousDNSResponse

func CreateObliviousDNSResponse(response []byte, paddingBytes uint16) *ObliviousDNSResponse

func UnmarshalResponseBody

func UnmarshalResponseBody(data []byte) (*ObliviousDNSResponse, error)

type ObliviousDoHConfig

type ObliviousDoHConfig struct {
	Version  uint16
	Contents ObliviousDoHConfigContents
}

func CreateObliviousDoHConfig

func CreateObliviousDoHConfig(contents ObliviousDoHConfigContents) ObliviousDoHConfig

func UnmarshalObliviousDoHConfig

func UnmarshalObliviousDoHConfig(buffer []byte) (ObliviousDoHConfig, error)

func (ObliviousDoHConfig) Marshal

func (c ObliviousDoHConfig) Marshal() []byte

type ObliviousDoHConfigContents

type ObliviousDoHConfigContents struct {
	KemID          hpke.KEMID
	KdfID          hpke.KDFID
	AeadID         hpke.AEADID
	PublicKeyBytes []byte
}

func CreateObliviousDoHConfigContents

func CreateObliviousDoHConfigContents(kemID hpke.KEMID, kdfID hpke.KDFID, aeadID hpke.AEADID, publicKeyBytes []byte) (ObliviousDoHConfigContents, error)

func UnmarshalObliviousDoHConfigContents

func UnmarshalObliviousDoHConfigContents(buffer []byte) (ObliviousDoHConfigContents, error)

func (ObliviousDoHConfigContents) CipherSuite

func (k ObliviousDoHConfigContents) CipherSuite() (hpke.CipherSuite, error)

func (ObliviousDoHConfigContents) EncryptQuery

func (targetKey ObliviousDoHConfigContents) EncryptQuery(query *ObliviousDNSQuery) (ObliviousDNSMessage, QueryContext, error)

func (ObliviousDoHConfigContents) KeyID

func (k ObliviousDoHConfigContents) KeyID() []byte

func (ObliviousDoHConfigContents) Marshal

func (k ObliviousDoHConfigContents) Marshal() []byte

func (ObliviousDoHConfigContents) PublicKey

func (k ObliviousDoHConfigContents) PublicKey() []byte

type ObliviousDoHConfigs

type ObliviousDoHConfigs struct {
	Configs []ObliviousDoHConfig
}

func CreateObliviousDoHConfigs

func CreateObliviousDoHConfigs(configs []ObliviousDoHConfig) ObliviousDoHConfigs

func UnmarshalObliviousDoHConfigs

func UnmarshalObliviousDoHConfigs(buffer []byte) (ObliviousDoHConfigs, error)

func (ObliviousDoHConfigs) Marshal

func (c ObliviousDoHConfigs) Marshal() []byte

type ObliviousDoHKeyPair

type ObliviousDoHKeyPair struct {
	Config ObliviousDoHConfig

	Seed []byte
	// contains filtered or unexported fields
}

func CreateDefaultKeyPair

func CreateDefaultKeyPair() (ObliviousDoHKeyPair, error)

func CreateDefaultKeyPairFromSeed

func CreateDefaultKeyPairFromSeed(seed []byte) (ObliviousDoHKeyPair, error)

func CreateKeyPair

func CreateKeyPair(kemID hpke.KEMID, kdfID hpke.KDFID, aeadID hpke.AEADID) (ObliviousDoHKeyPair, error)

func CreateKeyPairFromSeed

func CreateKeyPairFromSeed(kemID hpke.KEMID, kdfID hpke.KDFID, aeadID hpke.AEADID, ikm []byte) (ObliviousDoHKeyPair, error)

func (ObliviousDoHKeyPair) DecryptQuery

func (privateKey ObliviousDoHKeyPair) DecryptQuery(message ObliviousDNSMessage) (*ObliviousDNSQuery, ResponseContext, error)

type ObliviousMessageType

type ObliviousMessageType uint8

const (
	QueryType    ObliviousMessageType = 0x01
	ResponseType ObliviousMessageType = 0x02
)

type QueryContext

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

func (QueryContext) DecryptResponse

func (c QueryContext) DecryptResponse(message ObliviousDNSMessage) ([]byte, error)

func (QueryContext) OpenAnswer

func (c QueryContext) OpenAnswer(message ObliviousDNSMessage) ([]byte, error)

type ResponseContext

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

func (ResponseContext) EncryptResponse

func (c ResponseContext) EncryptResponse(response *ObliviousDNSResponse) (ObliviousDNSMessage, error)