...
 
Commits (2)
......@@ -10,6 +10,7 @@ import (
"time"
"git.autistici.org/id/go-sso"
"github.com/awnumar/memguard"
"git.autistici.org/id/keystore/backend"
"git.autistici.org/id/keystore/userenckey"
......@@ -29,7 +30,7 @@ type Database interface {
}
type userKey struct {
pkey []byte
pkey *memguard.LockedBuffer
expiry time.Time
}
......@@ -117,7 +118,7 @@ func (s *KeyStore) expire() {
s.mx.Lock()
for u, k := range s.userKeys {
if k.expiry.After(t) {
wipeBytes(k.pkey)
k.pkey.Destroy()
delete(s.userKeys, u)
}
}
......@@ -150,10 +151,15 @@ func (s *KeyStore) Open(ctx context.Context, username, password string, ttlSecon
if err != nil {
return err
}
buf, err := memguard.NewImmutableFromBytes(pkey)
if err != nil {
wipeBytes(pkey)
return err
}
s.mx.Lock()
s.userKeys[username] = userKey{
pkey: pkey,
pkey: buf,
expiry: time.Now().Add(time.Duration(ttlSeconds) * time.Second),
}
s.mx.Unlock()
......@@ -181,7 +187,7 @@ func (s *KeyStore) Get(username, ssoTicket string) ([]byte, error) {
if !ok {
return nil, errNoKeys
}
return u.pkey, nil
return u.pkey.Buffer(), nil
}
// Close the user's key store and wipe the associated unencrypted key
......@@ -189,7 +195,7 @@ func (s *KeyStore) Get(username, ssoTicket string) ([]byte, error) {
func (s *KeyStore) Close(username string) {
s.mx.Lock()
if k, ok := s.userKeys[username]; ok {
wipeBytes(k.pkey)
k.pkey.Destroy()
delete(s.userKeys, username)
}
s.mx.Unlock()
......
......@@ -28,6 +28,7 @@ func (s *keyStoreServer) handleOpen(w http.ResponseWriter, r *http.Request) {
return
}
log.Printf("decrypted key for %s", req.Username)
serverutil.EncodeJSONResponse(w, &emptyResponse)
}
......
# This is the official list of MemGuard authors for copyright purposes.
# Names should be added to this file as
# Name or Organization <email address>
# - Contribution
# The email address is not required for organizations.
Awn Umar <awn@cryptolosophy.io>
- Main developer.
Carlo Alberto Ferraris <cafxx@strayorange.com>
- Implemented buffer leaking protection via finalizers.
dotcppfile <dotcppfile@gmail.com>
- Implemented guard pages.
- Various bug fixes and optimisations.
Joseph Richey <joerichey@google.com>
- Suggested using system calls for memory allocation.
# Contributor Code of Conduct
This project adheres to No Code of Conduct. We are all adults. We accept anyone's contributions. Nothing else matters.
For more information please visit the [No Code of Conduct](https://github.com/domgetter/NCoC) homepage.
# Contributing Guide
We accept contributions from anyone. Here is the general process:
1. Make a fork of the repository.
2. Make your changes, preferably to the `development` branch.
3. Add your contribution to the [`AUTHORS`](/AUTHORS) file. If you're a first-time contributor, first add your name and email (in alphabetical order).
4. Open a PR against the `development` branch.
Changes are squashed and merged into `development`, and then `development` is merged conventionally into `master`.
This diff is collapsed.
<p align="center">
<img src="https://cdn.rawgit.com/awnumar/memguard/master/logo.svg" height="140" />
<h3 align="center">MemGuard</h3>
<p align="center">Easy and secure handling of sensitive memory, in pure Go.</p>
<p align="center">
<a href="https://travis-ci.org/awnumar/memguard"><img src="https://travis-ci.org/awnumar/memguard.svg?branch=master"></a>
<a href="https://ci.appveyor.com/project/awnumar/memguard/branch/master"><img src="https://ci.appveyor.com/api/projects/status/nrtqmdolndm0pcac/branch/master?svg=true"></a>
<a href="https://godoc.org/github.com/awnumar/memguard"><img src="https://godoc.org/github.com/awnumar/memguard?status.svg"></a>
<a href="https://goreportcard.com/report/github.com/awnumar/memguard"><img src="https://goreportcard.com/badge/github.com/awnumar/memguard"></a>
</p>
</p>
---
This is a thread-safe package, designed to allow you to easily handle sensitive values in memory. It supports all major operating systems and is written in pure Go.
## Features
* Interference from the garbage-collector is blocked by using system-calls to manually allocate memory ourselves.
* It is very difficult for another process to find or access sensitive memory as the data is sandwiched between guard-pages. This feature also acts as an immediate access alarm in case of buffer overflows.
* Buffer overflows are further protected against using a random canary value. If this value changes, the process will panic.
* We try our best to prevent the system from writing anything sensitive to the disk. The data is locked to prevent swapping, system core dumps can be disabled, and the kernel is advised (where possible) to never include the secure memory in dumps.
* True kernel-level immutability is implemented. That means that if _anything_ attempts to modify an immutable container, the kernel will throw an access violation and the process will terminate.
* All sensitive data is wiped before the associated memory is released back to the operating system.
* Side-channel attacks are mitigated against by making sure that the copying and comparison of data is done in constant-time.
* Accidental memory leaks are mitigated against by harnessing Go's own garbage-collector to automatically destroy containers that have run out of scope.
Some of these features were inspired by [libsodium](https://github.com/jedisct1/libsodium), so credits to them.
Full documentation and a complete overview of the API can be found [here](https://godoc.org/github.com/awnumar/memguard).
## Installation
Although we do recommend using a release, the simplest way to install the library is to `go get` it:
```
$ go get github.com/awnumar/memguard
```
If you would prefer a signed release that you can verify and manually compile yourself, download and extract the [latest release](https://github.com/awnumar/memguard/releases/latest). Then go ahead and run:
```
$ go install -v ./
```
The releases are cryptographically signed with my PGP key, which can be found on [keybase](https://keybase.io/awn). To import it directly into GPG, run:
```
$ curl https://keybase.io/awn/pgp_keys.asc | gpg --import
```
We **strongly** encourage you to vendor your dependencies for a clean and reliable build. [Glide](http://glide.sh/) makes this task relatively frictionless.
version: '{build}'
platform: Any CPU
clone_folder: c:\go\src\github.com\awnumar\memguard
environment:
GOPATH: c:\go
install:
- set PATH=%GOPATH%\bin;c:\go\bin;%PATH%
- go version
build_script:
- go build -race -v .
test_script:
- go test -race -v ./...
notifications:
- provider: Slack
incoming_webhook:
secure: WjopZ/uuTGqqu1XhbjE05ZHSGcoVa7M07WwKQuGLqkO4AD1xGj+G817tMC1Ke0XxB3dBNQ++Ryr/SlzrjUVSHetvUgEpjE380XaCzXIdXP8=
on_build_success: true
on_build_failure: true
on_build_status_changed: true
package memguard
import (
"crypto/subtle"
"runtime"
"sync"
"unsafe"
"github.com/awnumar/memguard/memcall"
)
/*
LockedBuffer is a structure that holds secure values.
The protected memory itself can be accessed with the Buffer() method. The various states can be accessed with the IsDestroyed() and IsMutable() methods, both of which are pretty self-explanatory.
The number of LockedBuffers that you are able to create is limited by how much memory your system kernel allows each process to mlock/VirtualLock. Therefore you should call Destroy on LockedBuffers that you no longer need, or simply defer a Destroy call after creating a new LockedBuffer.
The entire memguard API handles and passes around pointers to LockedBuffers, and so, for both security and convenience, you should refrain from dereferencing a LockedBuffer.
If an API function that needs to edit a LockedBuffer is given one that is immutable, the call will return an ErrImmutable. Similarly, if a function is given a LockedBuffer that has been destroyed, the call will return an ErrDestroyed.
*/
type LockedBuffer struct {
*container // Import all the container fields.
*littleBird // Monitor this for auto-destruction.
}
// container implements the actual data container.
type container struct {
sync.Mutex // Local mutex lock.
buffer []byte // Slice that references the protected memory.
mutable bool // Is this LockedBuffer mutable?
}
// littleBird is a value that we monitor instead of the LockedBuffer
// itself. It allows us to tell the GC to auto-destroy LockedBuffers.
type littleBird [16]byte
// Global internal function used to create new secure containers.
func newContainer(size int, mutable bool) (*LockedBuffer, error) {
// Return an error if length < 1.
if size < 1 {
return nil, ErrInvalidLength
}
// Allocate a new LockedBuffer.
ib := new(container)
b := &LockedBuffer{ib, new(littleBird)}
// Round length + 32 bytes for the canary to a multiple of the page size..
roundedLength := roundToPageSize(size + 32)
// Calculate the total size of memory including the guard pages.
totalSize := (2 * pageSize) + roundedLength
// Allocate it all.
memory := memcall.Alloc(totalSize)
// Make the guard pages inaccessible.
memcall.Protect(memory[:pageSize], false, false)
memcall.Protect(memory[pageSize+roundedLength:], false, false)
// Lock the pages that will hold the sensitive data.
memcall.Lock(memory[pageSize : pageSize+roundedLength])
// Set the canary.
subtle.ConstantTimeCopy(1, memory[pageSize+roundedLength-size-32:pageSize+roundedLength-size], canary)
// Set Buffer to a byte slice that describes the reigon of memory that is protected.
b.buffer = getBytes(uintptr(unsafe.Pointer(&memory[pageSize+roundedLength-size])), size)
// Set appropriate mutability state.
b.mutable = true
if !mutable {
b.MakeImmutable()
}
// Use a finalizer to make sure the buffer gets destroyed if forgotten.
runtime.SetFinalizer(b.littleBird, func(_ *littleBird) {
go ib.Destroy()
})
// Append the container to allLockedBuffers. We have to add container
// instead of LockedBuffer so that littleBird can become unreachable.
allLockedBuffersMutex.Lock()
allLockedBuffers = append(allLockedBuffers, ib)
allLockedBuffersMutex.Unlock()
// Return a pointer to the LockedBuffer.
return b, nil
}
/*
Package memguard lets you easily handle sensitive values in memory.
package main
import (
"fmt"
"github.com/awnumar/memguard"
)
func main() {
// Tell memguard to listen out for interrupts, and cleanup in case of one.
memguard.CatchInterrupt(func() {
fmt.Println("Interrupt signal received. Exiting...")
})
// Make sure to destroy all LockedBuffers when returning.
defer memguard.DestroyAll()
// Normal code continues from here.
foo()
}
func foo() {
// Create a 32 byte, immutable, random key.
key, err := memguard.NewImmutableRandom(32)
if err != nil {
// Oh no, an error. Safely exit.
fmt.Println(err)
memguard.SafeExit(1)
}
// Remember to destroy this key when the function returns.
defer key.Destroy()
// Do something with the key.
fmt.Printf("This is a %d byte key.\n", key.Size())
fmt.Printf("This key starts with %x\n", key.Buffer()[0])
}
The number of LockedBuffers that you are able to create is limited by how much memory your system kernel allows each process to mlock/VirtualLock. Therefore you should call Destroy on LockedBuffers that you no longer need, or simply defer a Destroy call after creating a new LockedBuffer.
If a function that you're using requires an array, you can cast the buffer to an array and then pass around a pointer. Make sure that you do not dereference the pointer and pass around the resulting value, as this will leave copies all over the place.
key, err := memguard.NewImmutableRandom(16)
if err != nil {
fmt.Println(err)
memguard.SafeExit(1)
}
defer key.Destroy()
// Make sure the size of the array matches the size of the Buffer.
// In this case that size is 16. This is very important.
keyArrayPtr := (*[16]byte)(unsafe.Pointer(&key.Buffer()[0]))
The MemGuard API is thread-safe. You can extend this thread-safety to outside of the API functions by using the Mutex that each LockedBuffer exposes. Don't use the mutex when calling a function that is part of the MemGuard API though, or the process will deadlock.
When terminating your application, care should be taken to securely cleanup everything.
// Start a listener that will wait for interrupt signals and catch them.
memguard.CatchInterrupt(func() {
// Over here put anything you want executing before program exit.
fmt.Println("Interrupt signal received. Exiting...")
})
// Defer a DestroyAll() in your main() function.
defer memguard.DestroyAll()
// Use memguard.SafeExit() instead of os.Exit().
memguard.SafeExit(1) // 1 is the exit code.
*/
package memguard
package memguard
import "errors"
// ErrDestroyed is returned when a function is called on a destroyed LockedBuffer.
var ErrDestroyed = errors.New("memguard.ErrDestroyed: buffer is destroyed")
// ErrImmutable is returned when a function that needs to modify a LockedBuffer
// is given a LockedBuffer that is immutable.
var ErrImmutable = errors.New("memguard.ErrImmutable: cannot modify immutable buffer")
// ErrInvalidLength is returned when a LockedBuffer of smaller than one byte is requested.
var ErrInvalidLength = errors.New("memguard.ErrInvalidLength: length of buffer must be greater than zero")
hash: 57bb613ba5be1489c88a0bb07374b8d7009413ac6216416e162490060e00b81a
updated: 2017-10-16T11:42:03.286781236+01:00
imports:
- name: golang.org/x/sys
version: 686000749eaec0b8855b8eef5336cf63899fe51d
subpackages:
- unix
- windows
testImports: []
package: github.com/awnumar/memguard
homepage: https://github.com/awnumar/memguard
license: Apache-2.0
owners:
- name: Awn Umar
email: awn@cryptolosophy.io
homepage: https://cryptolosophy.io
import:
- package: golang.org/x/sys
subpackages:
- unix
- windows
package memguard
import (
"crypto/rand"
"os"
"sync"
"unsafe"
"github.com/awnumar/memguard/memcall"
)
var (
// Ascertain and store the system memory page size.
pageSize = os.Getpagesize()
// Canary value that acts as an alarm in case of disallowed memory access.
canary = createCanary()
// Create a dedicated sync object for the CatchInterrupt function.
catchInterruptOnce sync.Once
// Array of all active containers, and associated mutex.
allLockedBuffers []*container
allLockedBuffersMutex = &sync.Mutex{}
)
// Create and allocate a canary value. Return to caller.
func createCanary() []byte {
// Canary length rounded to page size.
roundedLen := roundToPageSize(32)
// Therefore the total length is...
totalLen := (2 * pageSize) + roundedLen
// Allocate it.
memory := memcall.Alloc(totalLen)
// Make the guard pages inaccessible.
memcall.Protect(memory[:pageSize], false, false)
memcall.Protect(memory[pageSize+roundedLen:], false, false)
// Lock the pages that will hold the canary.
memcall.Lock(memory[pageSize : pageSize+roundedLen])
// Fill the memory with cryptographically-secure random bytes (the canary value).
c := getBytes(uintptr(unsafe.Pointer(&memory[pageSize+roundedLen-32])), 32)
fillRandBytes(c)
// Tell the kernel that the canary value should be immutable.
memcall.Protect(memory[pageSize:pageSize+roundedLen], true, false)
// Return a slice that describes the correct portion of memory.
return c
}
// Round a length to a multiple of the system page size.
func roundToPageSize(length int) int {
return (length + (pageSize - 1)) & (^(pageSize - 1))
}
// Get a slice that describes all memory related to a LockedBuffer.
func getAllMemory(b *container) []byte {
// Calculate the size of the entire container's memory.
roundedBufLen := roundToPageSize(len(b.buffer) + 32)
// Calculate the address of the start of the memory.
memAddr := uintptr(unsafe.Pointer(&b.buffer[0])) - uintptr((roundedBufLen-len(b.buffer))+pageSize)
// Calculate the size of the entire memory.
memLen := (pageSize * 2) + roundedBufLen
// Use this information to generate a slice and return it.
return getBytes(memAddr, memLen)
}
// Convert a pointer and length to a byte slice that describes that memory.
func getBytes(ptr uintptr, len int) []byte {
var sl = struct {
addr uintptr
len int
cap int
}{ptr, len, len}
return *(*[]byte)(unsafe.Pointer(&sl))
}
// Takes a byte slice and fills it with random data.
func fillRandBytes(b []byte) {
// Read len(b) bytes into the buffer.
if _, err := rand.Read(b); err != nil {
panic("memguard.csprng(): could not get random bytes")
}
}
// Wipes a byte slice with zeroes.
func wipeBytes(buf []byte) {
// Iterate over the slice...
for i := 0; i < len(buf); i++ {
// ... setting each element to zero.
buf[i] = byte(0)
}
}
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 68 100" enable-background="new 0 0 68 100" xml:space="preserve"><path d="M60.5,41.338V26.5C60.5,11.888,48.612,0,34,0S7.5,11.888,7.5,26.5v14.838L0,42v55l34,3l34-3V42L60.5,41.338z M15.5,40.633
V26.5C15.5,16.299,23.799,8,34,8s18.5,8.299,18.5,18.5v14.133L34,39L15.5,40.633z"></path></svg>
\ No newline at end of file
// +build openbsd
package memcall
import (
"fmt"
"golang.org/x/sys/unix"
)
// Lock is a wrapper for unix.Mlock(), with extra precautions.
func Lock(b []byte) {
// Call mlock.
if err := unix.Mlock(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Lock(): could not acquire lock on %p, limit reached? [Err: %s]", &b[0], err))
}
}
// Unlock is a wrapper for unix.Munlock().
func Unlock(b []byte) {
if err := unix.Munlock(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Unlock(): could not free lock on %p [Err: %s]", &b[0], err))
}
}
// Alloc allocates a byte slice of length n and returns it.
func Alloc(n int) []byte {
// Allocate the memory.
b, err := unix.Mmap(-1, 0, n, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_PRIVATE|unix.MAP_ANON)
if err != nil {
panic(fmt.Sprintf("memguard.memcall.Alloc(): could not allocate [Err: %s]", err))
}
// Return the allocated memory.
return b
}
// Free unallocates the byte slice specified.
func Free(b []byte) {
if err := unix.Munmap(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Free(): could not unallocate %p [Err: %s]", &b[0], err))
}
}
// Protect modifies the PROT_ flags for a specified byte slice.
func Protect(b []byte, read, write bool) {
// Ascertain protection value from arguments.
var prot int
if read && write {
prot = unix.PROT_READ | unix.PROT_WRITE
} else if read {
prot = unix.PROT_READ
} else if write {
prot = unix.PROT_WRITE
} else {
prot = unix.PROT_NONE
}
// Change the protection value of the byte slice.
if err := unix.Mprotect(b, prot); err != nil {
panic(fmt.Sprintf("memguard.memcall.Protect(): could not set %d on %p [Err: %s]", prot, &b[0], err))
}
}
// DisableCoreDumps disables core dumps on Unix systems.
func DisableCoreDumps() {
// Disable core dumps.
if err := unix.Setrlimit(unix.RLIMIT_CORE, &unix.Rlimit{Cur: 0, Max: 0}); err != nil {
panic(fmt.Sprintf("memguard.memcall.DisableCoreDumps(): could not set rlimit [Err: %s]", err))
}
}
// +build darwin
package memcall
import (
"fmt"
"golang.org/x/sys/unix"
)
// Lock is a wrapper for unix.Mlock(), with extra precautions.
func Lock(b []byte) {
if err := unix.Mlock(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Lock(): could not acquire lock on %p, limit reached? [Err: %s]", &b[0], err))
}
}
// Unlock is a wrapper for unix.Munlock().
func Unlock(b []byte) {
if err := unix.Munlock(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Unlock(): could not free lock on %p [Err: %s]", &b[0], err))
}
}
// Alloc allocates a byte slice of length n and returns it.
func Alloc(n int) []byte {
// Allocate the memory.
b, err := unix.Mmap(-1, 0, n, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_PRIVATE|unix.MAP_ANON)
if err != nil {
panic(fmt.Sprintf("memguard.memcall.Alloc(): could not allocate [Err: %s]", err))
}
// Return the allocated memory.
return b
}
// Free unallocates the byte slice specified.
func Free(b []byte) {
if err := unix.Munmap(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Free(): could not unallocate %p [Err: %s]", &b[0], err))
}
}
// Protect modifies the PROT_ flags for a specified byte slice.
func Protect(b []byte, read, write bool) {
// Ascertain protection value from arguments.
var prot int
if read && write {
prot = unix.PROT_READ | unix.PROT_WRITE
} else if read {
prot = unix.PROT_READ
} else if write {
prot = unix.PROT_WRITE
} else {
prot = unix.PROT_NONE
}
// Change the protection value of the byte slice.
if err := unix.Mprotect(b, prot); err != nil {
panic(fmt.Sprintf("memguard.memcall.Protect(): could not set %d on %p [Err: %s]", prot, &b[0], err))
}
}
// DisableCoreDumps disables core dumps on Unix systems.
func DisableCoreDumps() {
// Disable core dumps.
if err := unix.Setrlimit(unix.RLIMIT_CORE, &unix.Rlimit{Cur: 0, Max: 0}); err != nil {
panic(fmt.Sprintf("memguard.memcall.DisableCoreDumps(): could not set rlimit [Err: %s]", err))
}
}
// +build !windows,!darwin,!openbsd
package memcall
import (
"fmt"
"golang.org/x/sys/unix"
)
// Lock is a wrapper for unix.Mlock(), with extra precautions.
func Lock(b []byte) {
// Advise the kernel not to dump. Ignore failure.
unix.Madvise(b, unix.MADV_DONTDUMP)
// Call mlock.
if err := unix.Mlock(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Lock(): could not acquire lock on %p, limit reached? [Err: %s]", &b[0], err))
}
}
// Unlock is a wrapper for unix.Munlock().
func Unlock(b []byte) {
if err := unix.Munlock(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Unlock(): could not free lock on %p [Err: %s]", &b[0], err))
}
}
// Alloc allocates a byte slice of length n and returns it.
func Alloc(n int) []byte {
// Allocate the memory.
b, err := unix.Mmap(-1, 0, n, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_PRIVATE|unix.MAP_ANONYMOUS)
if err != nil {
panic(fmt.Sprintf("memguard.memcall.Alloc(): could not allocate [Err: %s]", err))
}
// Return the allocated memory.
return b
}
// Free unallocates the byte slice specified.
func Free(b []byte) {
if err := unix.Munmap(b); err != nil {
panic(fmt.Sprintf("memguard.memcall.Free(): could not unallocate %p [Err: %s]", &b[0], err))
}
}
// Protect modifies the PROT_ flags for a specified byte slice.
func Protect(b []byte, read, write bool) {
// Ascertain protection value from arguments.
var prot int
if read && write {
prot = unix.PROT_READ | unix.PROT_WRITE
} else if read {
prot = unix.PROT_READ
} else if write {
prot = unix.PROT_WRITE
} else {
prot = unix.PROT_NONE
}
// Change the protection value of the byte slice.
if err := unix.Mprotect(b, prot); err != nil {
panic(fmt.Sprintf("memguard.memcall.Protect(): could not set %d on %p [Err: %s]", prot, &b[0], err))
}
}
// DisableCoreDumps disables core dumps on Unix systems.
func DisableCoreDumps() {
// Disable core dumps.
if err := unix.Setrlimit(unix.RLIMIT_CORE, &unix.Rlimit{Cur: 0, Max: 0}); err != nil {
panic(fmt.Sprintf("memguard.memcall.DisableCoreDumps(): could not set rlimit [Err: %s]", err))
}
}
// +build windows
package memcall
import (
"fmt"
"unsafe"
"golang.org/x/sys/windows"
)
// Placeholder variable for when we need a valid pointer to zero bytes.
var _zero uintptr
// Lock is a wrapper for windows.VirtualLock()
func Lock(b []byte) {
if err := windows.VirtualLock(_getPtr(b), uintptr(len(b))); err != nil {
panic(fmt.Sprintf("memguard.memcall.Lock(): could not acquire lock on %p, limit reached? [Err: %s]", &b[0], err))
}
}
// Unlock is a wrapper for windows.VirtualUnlock()
func Unlock(b []byte) {
if err := windows.VirtualUnlock(_getPtr(b), uintptr(len(b))); err != nil {
panic(fmt.Sprintf("memguard.memcall.Unlock(): could not free lock on %p [Err: %s]", &b[0], err))
}
}
// Alloc allocates a byte slice of length n and returns it.
func Alloc(n int) []byte {
// Allocate the memory.
ptr, err := windows.VirtualAlloc(_zero, uintptr(n), 0x1000|0x2000, 0x4)
if err != nil {
panic(fmt.Sprintf("memguard.memcall.Alloc(): could not allocate [Err: %s]", err))
}
// Return the allocated memory.
return _getBytes(ptr, n, n)
}
// Free unallocates the byte slice specified.
func Free(b []byte) {
if err := windows.VirtualFree(_getPtr(b), uintptr(0), 0x8000); err != nil {
panic(fmt.Sprintf("memguard.memcall.Free(): could not unallocate %p [Err: %s]", &b[0], err))
}
}
// Protect modifies the Memory Protection Constants for a specified byte slice.
func Protect(b []byte, read, write bool) {
// Ascertain protection value from arguments.
var prot int
if write {
prot = 0x4 // PAGE_READWRITE
} else if read {
prot = 0x2 // PAGE_READ
} else {
prot = 0x1 // PAGE_NOACCESS
}
var oldProtect uint32
if err := windows.VirtualProtect(_getPtr(b), uintptr(len(b)), uint32(prot), &oldProtect); err != nil {
panic(fmt.Sprintf("memguard.memcall.Protect(): could not set %d on %p [Err: %s]", prot, &b[0], err))
}
}
// DisableCoreDumps is included for compatibility reasons. On windows it is a no-op function.
func DisableCoreDumps() {}
func _getPtr(b []byte) uintptr {
var _p0 unsafe.Pointer
if len(b) > 0 {
_p0 = unsafe.Pointer(&b[0])
} else {
_p0 = unsafe.Pointer(&_zero)
}
return uintptr(_p0)
}
func _getBytes(ptr uintptr, len int, cap int) []byte {
var sl = struct {
addr uintptr
len int
cap int
}{ptr, len, cap}
return *(*[]byte)(unsafe.Pointer(&sl))
}
This diff is collapsed.
Copyright (c) 2009 The Go Authors. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Additional IP Rights Grant (Patents)
"This implementation" means the copyrightable works distributed by
Google as part of the Go project.
Google hereby grants to You a perpetual, worldwide, non-exclusive,
no-charge, royalty-free, irrevocable (except as stated in this section)
patent license to make, have made, use, offer to sell, sell, import,
transfer and otherwise run, modify and propagate the contents of this
implementation of Go, where such license applies only to those patent
claims, both currently owned or controlled by Google and acquired in
the future, licensable by Google that are necessarily infringed by this
implementation of Go. This grant does not include claims that would be
infringed only as a consequence of further modification of this
implementation. If you or your agent or exclusive licensee institute or
order or agree to the institution of patent litigation against any
entity (including a cross-claim or counterclaim in a lawsuit) alleging
that this implementation of Go or any code incorporated within this
implementation of Go constitutes direct or contributory patent
infringement, or inducement of patent infringement, then any patent
rights granted to you under this License for this implementation of Go
shall terminate as of the date such litigation is filed.
# Building `sys/unix`
The sys/unix package provides access to the raw system call interface of the
underlying operating system. See: https://godoc.org/golang.org/x/sys/unix
Porting Go to a new architecture/OS combination or adding syscalls, types, or
constants to an existing architecture/OS pair requires some manual effort;
however, there are tools that automate much of the process.
## Build Systems
There are currently two ways we generate the necessary files. We are currently
migrating the build system to use containers so the builds are reproducible.
This is being done on an OS-by-OS basis. Please update this documentation as
components of the build system change.
### Old Build System (currently for `GOOS != "Linux" || GOARCH == "sparc64"`)
The old build system generates the Go files based on the C header files
present on your system. This means that files
for a given GOOS/GOARCH pair must be generated on a system with that OS and
architecture. This also means that the generated code can differ from system
to system, based on differences in the header files.
To avoid this, if you are using the old build system, only generate the Go
files on an installation with unmodified header files. It is also important to
keep track of which version of the OS the files were generated from (ex.
Darwin 14 vs Darwin 15). This makes it easier to track the progress of changes
and have each OS upgrade correspond to a single change.
To build the files for your current OS and architecture, make sure GOOS and
GOARCH are set correctly and run `mkall.sh`. This will generate the files for
your specific system. Running `mkall.sh -n` shows the commands that will be run.
Requirements: bash, perl, go
### New Build System (currently for `GOOS == "Linux" && GOARCH != "sparc64"`)
The new build system uses a Docker container to generate the go files directly
from source checkouts of the kernel and various system libraries. This means
that on any platform that supports Docker, all the files using the new build
system can be generated at once, and generated files will not change based on
what the person running the scripts has installed on their computer.
The OS specific files for the new build system are located in the `${GOOS}`
directory, and the build is coordinated by the `${GOOS}/mkall.go` program. When
the kernel or system library updates, modify the Dockerfile at
`${GOOS}/Dockerfile` to checkout the new release of the source.
To build all the files under the new build system, you must be on an amd64/Linux
system and have your GOOS and GOARCH set accordingly. Running `mkall.sh` will
then generate all of the files for all of the GOOS/GOARCH pairs in the new build
system. Running `mkall.sh -n` shows the commands that will be run.
Requirements: bash, perl, go, docker
## Component files
This section describes the various files used in the code generation process.
It also contains instructions on how to modify these files to add a new
architecture/OS or to add additional syscalls, types, or constants. Note that
if you are using the new build system, the scripts cannot be called normally.
They must be called from within the docker container.
### asm files
The hand-written assembly file at `asm_${GOOS}_${GOARCH}.s` implements system
call dispatch. There are three entry points:
```
func Syscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr)
func Syscall6(trap, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
func RawSyscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr)
```
The first and second are the standard ones; they differ only in how many
arguments can be passed to the kernel. The third is for low-level use by the
ForkExec wrapper. Unlike the first two, it does not call into the scheduler to
let it know that a system call is running.
When porting Go to an new architecture/OS, this file must be implemented for
each GOOS/GOARCH pair.
### mksysnum
Mksysnum is a script located at `${GOOS}/mksysnum.pl` (or `mksysnum_${GOOS}.pl`
for the old system). This script takes in a list of header files containing the
syscall number declarations and parses them to produce the corresponding list of
Go numeric constants. See `zsysnum_${GOOS}_${GOARCH}.go` for the generated
constants.
Adding new syscall numbers is mostly done by running the build on a sufficiently
new installation of the target OS (or updating the source checkouts for the
new build system). However, depending on the OS, you make need to update the
parsing in mksysnum.
### mksyscall.pl
The `syscall.go`, `syscall_${GOOS}.go`, `syscall_${GOOS}_${GOARCH}.go` are
hand-written Go files which implement system calls (for unix, the specific OS,
or the specific OS/Architecture pair respectively) that need special handling
and list `//sys` comments giving prototypes for ones that can be generated.
The mksyscall.pl script takes the `//sys` and `//sysnb` comments and converts
them into syscalls. This requires the name of the prototype in the comment to
match a syscall number in the `zsysnum_${GOOS}_${GOARCH}.go` file. The function
prototype can be exported (capitalized) or not.
Adding a new syscall often just requires adding a new `//sys` function prototype
with the desired arguments and a capitalized name so it is exported. However, if
you want the interface to the syscall to be different, often one will make an
unexported `//sys` prototype, an then write a custom wrapper in
`syscall_${GOOS}.go`.
### types files
For each OS, there is a hand-written Go file at `${GOOS}/types.go` (or
`types_${GOOS}.go` on the old system). This file includes standard C headers and
creates Go type aliases to the corresponding C types. The file is then fed
through godef to get the Go compatible definitions. Finally, the generated code
is fed though mkpost.go to format the code correctly and remove any hidden or
private identifiers. This cleaned-up code is written to
`ztypes_${GOOS}_${GOARCH}.go`.
The hardest part about preparing this file is figuring out which headers to
include and which symbols need to be `#define`d to get the actual data
structures that pass through to the kernel system calls. Some C libraries
preset alternate versions for binary compatibility and translate them on the
way in and out of system calls, but there is almost always a `#define` that can
get the real ones.
See `types_darwin.go` and `linux/types.go` for examples.
To add a new type, add in the necessary include statement at the top of the
file (if it is not already there) and add in a type alias line. Note that if
your type is significantly different on different architectures, you may need
some `#if/#elif` macros in your include statements.
### mkerrors.sh
This script is used to generate the system's various constants. This doesn't
just include the error numbers and error strings, but also the signal numbers
an a wide variety of miscellaneous constants. The constants come from the list
of include files in the `includes_${uname}` variable. A regex then picks out
the desired `#define` statements, and generates the corresponding Go constants.
The error numbers and strings are generated from `#include <errno.h>`, and the
signal numbers and strings are generated from `#include <signal.h>`. All of
these constants are written to `zerrors_${GOOS}_${GOARCH}.go` via a C program,
`_errors.c`, which prints out all the constants.
To add a constant, add the header that includes it to the appropriate variable.
Then, edit the regex (if necessary) to match the desired constant. Avoid making
the regex too broad to avoid matching unintended constants.
## Generated files
### `zerror_${GOOS}_${GOARCH}.go`
A file containing all of the system's generated error numbers, error strings,
signal numbers, and constants. Generated by `mkerrors.sh` (see above).
### `zsyscall_${GOOS}_${GOARCH}.go`
A file containing all the generated syscalls for a specific GOOS and GOARCH.
Generated by `mksyscall.pl` (see above).
### `zsysnum_${GOOS}_${GOARCH}.go`
A list of numeric constants for all the syscall number of the specific GOOS
and GOARCH. Generated by mksysnum (see above).
### `ztypes_${GOOS}_${GOARCH}.go`
A file containing Go types for passing into (or returning from) syscalls.
Generated by godefs and the types file (see above).
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System call support for 386, Darwin
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-28
JMP syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-40
JMP syscall·Syscall6(SB)
TEXT ·Syscall9(SB),NOSPLIT,$0-52
JMP syscall·Syscall9(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-28
JMP syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-40
JMP syscall·RawSyscall6(SB)
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System call support for AMD64, Darwin
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-56
JMP syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-80
JMP syscall·Syscall6(SB)
TEXT ·Syscall9(SB),NOSPLIT,$0-104
JMP syscall·Syscall9(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-56
JMP syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-80
JMP syscall·RawSyscall6(SB)
// Copyright 2015 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
// +build arm,darwin
#include "textflag.h"
//
// System call support for ARM, Darwin
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-28
B syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-40
B syscall·Syscall6(SB)
TEXT ·Syscall9(SB),NOSPLIT,$0-52
B syscall·Syscall9(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-28
B syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-40
B syscall·RawSyscall6(SB)
// Copyright 2015 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
// +build arm64,darwin
#include "textflag.h"
//
// System call support for AMD64, Darwin
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-56
B syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-80
B syscall·Syscall6(SB)
TEXT ·Syscall9(SB),NOSPLIT,$0-104
B syscall·Syscall9(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-56
B syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-80
B syscall·RawSyscall6(SB)
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System call support for AMD64, DragonFly
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-64
JMP syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-88
JMP syscall·Syscall6(SB)
TEXT ·Syscall9(SB),NOSPLIT,$0-112
JMP syscall·Syscall9(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-64
JMP syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-88
JMP syscall·RawSyscall6(SB)
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System call support for 386, FreeBSD
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-28
JMP syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-40
JMP syscall·Syscall6(SB)
TEXT ·Syscall9(SB),NOSPLIT,$0-52
JMP syscall·Syscall9(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-28
JMP syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-40
JMP syscall·RawSyscall6(SB)
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System call support for AMD64, FreeBSD
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-56
JMP syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-80
JMP syscall·Syscall6(SB)
TEXT ·Syscall9(SB),NOSPLIT,$0-104
JMP syscall·Syscall9(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-56
JMP syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-80
JMP syscall·RawSyscall6(SB)
// Copyright 2012 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System call support for ARM, FreeBSD
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-28
B syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-40
B syscall·Syscall6(SB)
TEXT ·Syscall9(SB),NOSPLIT,$0-52
B syscall·Syscall9(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-28
B syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-40
B syscall·RawSyscall6(SB)
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System calls for 386, Linux
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-28
JMP syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-40
JMP syscall·Syscall6(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-28
JMP syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-40
JMP syscall·RawSyscall6(SB)
TEXT ·socketcall(SB),NOSPLIT,$0-36
JMP syscall·socketcall(SB)
TEXT ·rawsocketcall(SB),NOSPLIT,$0-36
JMP syscall·rawsocketcall(SB)
TEXT ·seek(SB),NOSPLIT,$0-28
JMP syscall·seek(SB)
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System calls for AMD64, Linux
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-56
JMP syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-80
JMP syscall·Syscall6(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-56
JMP syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-80
JMP syscall·RawSyscall6(SB)
TEXT ·gettimeofday(SB),NOSPLIT,$0-16
JMP syscall·gettimeofday(SB)
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build !gccgo
#include "textflag.h"
//
// System calls for arm, Linux
//
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-28
B syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-40
B syscall·Syscall6(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-28
B syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-40
B syscall·RawSyscall6(SB)
TEXT ·seek(SB),NOSPLIT,$0-32
B syscall·seek(SB)
// Copyright 2015 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// +build linux
// +build arm64
// +build !gccgo
#include "textflag.h"
// Just jump to package syscall's implementation for all these functions.
// The runtime may know about them.
TEXT ·Syscall(SB),NOSPLIT,$0-56
B syscall·Syscall(SB)
TEXT ·Syscall6(SB),NOSPLIT,$0-80
B syscall·Syscall6(SB)
TEXT ·RawSyscall(SB),NOSPLIT,$0-56
B syscall·RawSyscall(SB)
TEXT ·RawSyscall6(SB),NOSPLIT,$0-80
B syscall·RawSyscall6(SB)