README
¶
Binary Cookies 
Go (golang) implementation of an encoder and decoder for the Binary Cookies file format used by Safari and other applications based on WebKit to store HTTP cookies. A CLI program is also included to allow you to inspect and manipulate the binary cookies from the commodity of your Terminal.
Usage
If you are going to use this Go module in your project:
go get github.com/cixtor/binarycookies
If you want to install the command line interface (CLI):
go get github.com/cixtor/binarycookies/cmd/binarycookies
Example
The majority of macOS applications store their web cookies in ~/Library/Cookies/ while others —using containers— do so in ~/Library/Containers/<APP_ID>/Data/Library/Cookies/. We can use simple Unix commands to find all these files and dump their content using the CLI, like so:
find ~/Library/Cookies/ -name "*.binarycookies" -exec binarycookies {} \;
Specification
Binary Cookies are binary files containing several pieces of data that together form an array of objects representing persistent web cookies for different applications in the macOS and iOS application ecosystem. Nowadays, almost every application implements some sort of web view to offer in-app purchases and license validation. All the information transmitted via these web views is stored in these binary files.
Note: BE stands for Big-endian and LE stands for Little-endian.
| Variable | Size | Type | Description |
|---|---|---|---|
| signature | 4 | byte | File signature must be equal to []byte{0x636f6f6b} or String("cook") |
| numPages | 4 | BE_uint32 | Number of pages in the file |
| pageOffset | 4 | BE_uint32 | Page offset. Repeat this N times where N = numPages |
| pageStart | 4 | byte | Marks the beginning of a page. Must be equal to []byte{0x00000100} |
| numCookies | 4 | LE_uint32 | Number of cookies in the page |
| cookieOffset | 4 | LE_uint32 | Cookie offset. Repeat this N times where N = numCookies |
| pageEnd | 4 | byte | Marks the end of a page. Must be equal to []byte{0x00000000} |
Immediately after pageEnd we can read the page cookies. Repeat the steps below N times where N = numCookies.
| Variable | Size | Type | Description |
|---|---|---|---|
| cookieSize | 4 | LE_uint32 | Cookie size. Number of bytes associated to the cookie |
| unknownOne | 4 | byte | Unknown field possibly related to the cookie flags |
| cookieFlags | 4 | LE_uint32 | 0x0:None - 0x1:Secure - 0x4:HttpOnly - 0x5:Secure+HttpOnly |
| unknownTwo | 4 | byte | Unknown field possibly related to the cookie flags |
| domainOffset | 4 | LE_uint32 | Cookie domain offset |
| nameOffset | 4 | LE_uint32 | Cookie name offset |
| pathOffset | 4 | LE_uint32 | Cookie path offset |
| valueOffset | 4 | LE_uint32 | Cookie value offset |
| commentOffset | 4 | LE_uint32 | Cookie comment offset |
| endHeader | 4 | byte | Marks the end of a header. Must be equal to []byte{0x00000000} |
| expires | 8 | float64 | Cookie expiration time in Mac epoch time. Add 978307200 to turn into Unix |
| creation | 8 | float64 | Cookie creation time in Mac epoch time. Add 978307200 to turn into Unix |
| comment | N | LE_uint32 | Cookie comment string. N = domainOffset - commentOffset |
| domain | N | LE_uint32 | Cookie domain string. N = nameOffset - domainOffset |
| name | N | LE_uint32 | Cookie name string. N = pathOffset - nameOffset |
| path | N | LE_uint32 | Cookie path string. N = valueOffset - pathOffset |
| value | N | LE_uint32 | Cookie value string. N = cookieSize - valueOffset |
Immediately after the last cookie in the page we can read another page with pageStart.
The last cookie of the last page in the file is followed by an 8-bytes checksum.
An optional number of bytes follow the checksum, these are part of a Binary Property List that contains a dictionary with additional information like the cookie accept policy for all tasks within sessions based on the software configuration. A bplist00 file is a completely different file format we need to decode separately. The first 4-bytes after the checksum are the BE_uint32 representing the size of the binary property list. The remaining bytes represent the data we need to decode using a bplist parser.
Documentation
¶
Overview ¶
Package binarycookies implements an encoder and decoder to create and read binary cookies respectively.
In computing, a magic cookie, or just cookie for short, is a token or short packet of data passed between communicating programs, where the data is typically not meaningful to the recipient program. The contents are opaque and not usually interpreted until the recipient passes the cookie data back to the sender or perhaps another program at a later time. The cookie is often used like a ticket – to identify a particular event or transaction.
An HTTP cookie is a small piece of data sent from a website and stored on the user's computer by the user's web browser while the user is browsing. Cookies were designed to be a reliable mechanism for websites to remember stateful information or to record the user's browsing activity. They can also be used to remember arbitrary pieces of information that the user previously entered into form fields such as names, addresses, passwords, and credit-card numbers.
References:
- https://en.wikipedia.org/wiki/Magic_cookie - https://en.wikipedia.org/wiki/HTTP_cookie - https://tools.ietf.org/html/rfc2109 - https://tools.ietf.org/html/rfc2965 - https://tools.ietf.org/html/rfc6265
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BinaryCookies ¶
type BinaryCookies struct {
// contains filtered or unexported fields
}
BinaryCookies is a struct representing relevant parts of the binary cookies archive. A couple of methods are available to read and validate the archive and to extract relevant information.
func New ¶
func New(reader io.Reader) *BinaryCookies
New returns an instance of the Binary Cookies class.
func (*BinaryCookies) Decode ¶
func (b *BinaryCookies) Decode() ([]Page, error)
Decode reads the entire file, validates and returns all cookies.
type Cookie ¶
type Cookie struct {
Size uint32
Flags uint32
Secure bool
HttpOnly bool
Comment []byte
Domain []byte
Name []byte
Path []byte
Value []byte
Expires time.Time
Creation time.Time
// contains filtered or unexported fields
}
Cookie or HTTP cookie is a small piece of data sent from a website and stored on the user's computer by the user's web browser while the user is browsing. Cookies were designed to be a reliable mechanism for websites to remember stateful information or to record the user's browsing activity.
They can also be used to remember arbitrary pieces of information that the user previously entered into form fields such as names, addresses, passwords and credit-card numbers.
The term "cookie" was coined by web-browser programmer Lou Montulli. It was derived from the term "magic cookie", which is a packet of data a program receives and sends back unchanged, used by Unix programmers.
Source Files
Directories