Skip to content

Commit

Permalink
Document adding custom fake TLS extensions (#115)
Browse files Browse the repository at this point in the history
* Document adding custom TLS extensions

* Fix custom extension example
  • Loading branch information
fedosgad committed Sep 7, 2022
1 parent 7344e34 commit 4d3785b
Showing 1 changed file with 66 additions and 0 deletions.
66 changes: 66 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,72 @@ To reuse tickets, create a shared cache and set it on current and further config
func (uconn *UConn) SetSessionCache(cache ClientSessionCache)
```

## Custom TLS extensions
If you want to add your own fake (placeholder, without added functionality) extension for mimicry purposes, you can embed `*tls.GenericExtension` into your own struct and override `Len()` and `Read()` methods. For example, [DelegatedCredentials](https://datatracker.ietf.org/doc/draft-ietf-tls-subcerts/) extension can be implemented as follows:

```Golang
const FakeDelegatedCredentials uint16 = 0x0022

type FakeDelegatedCredentialsExtension struct {
*tls.GenericExtension
SignatureAlgorithms []tls.SignatureScheme
}

func (e *FakeDelegatedCredentialsExtension) Len() int {
return 6 + 2*len(e.SignatureAlgorithms)
}

func (e *FakeDelegatedCredentialsExtension) Read(b []byte) (n int, err error) {
if len(b) < e.Len() {
return 0, io.ErrShortBuffer
}
offset := 0
appendUint16 := func(val uint16) {
b[offset] = byte(val >> 8)
b[offset+1] = byte(val & 0xff)
offset += 2
}

// Extension type
appendUint16(fakeDelegatedCredentials)

algosLength := 2 * len(e.SignatureAlgorithms)

// Extension data length
appendUint16(uint16(algosLength) + 2)

// Algorithms list length
appendUint16(uint16(algosLength))

// Algorithms list
for _, a := range e.SignatureAlgorithms {
appendUint16(uint16(a))
}
return e.Len(), io.EOF
}
```

Then it can be used just like normal extension:

```Golang
&tls.ClientHelloSpec{
//...
Extensions: []tls.TLSExtension{
//...
&FakeDelegatedCredentialsExtension{
SignatureAlgorithms: []tls.SignatureScheme{
tls.ECDSAWithP256AndSHA256,
tls.ECDSAWithP384AndSHA384,
tls.ECDSAWithP521AndSHA512,
tls.ECDSAWithSHA1,
},
},
//...
}
//...
}
```

# Client Hello IDs
See full list of `clientHelloID` values [here](https://godoc.org/github.com/refraction-networking/utls#ClientHelloID).
There are different behaviors you can get, depending on your `clientHelloID`:
Expand Down

0 comments on commit 4d3785b

Please sign in to comment.