Added some documentation and improved security API

4 files changed, 40 insertions, 10 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7272b10..6b7be43 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,6 +15,16 @@ You generally only need to submit a CLA once, so if you've already submitted one
 (even if it was for a different project), you probably don't need to do it
 again.
 
+## Reporting an Issue
+
+Any bugs or problems found in fscrypt should be reported though the 
+[Github Issue Tracker](https://github.com/google/fscrypt/issues/new). When
+reporting an issue, be sure to give as much information about the problem as
+possible. If reporting an issue around the fscrypt command-line tool, post the
+relevant output from fscrypt, running with the `--verbose` flag. For the
+pam_fscrypt module, use the `debug` flag with the module and post the relevant
+parts of the syslog (at ``).
+
 ## Code reviews
 
 All submissions, including submissions by project members, require review. We
diff --git a/README.md b/README.md
index 4355239..cb1a1e3 100644
--- a/README.md
+++ b/README.md
@@ -545,8 +545,8 @@ file for more information about singing the CLA and submitting a pull request.
 ## Troubleshooting
 
 In general, if you are encountering issues with fscrypt,
-[open an issue](https://github.com/google/fscrypt/issues/new). We will try our
-best to help.
+[open an issue](https://github.com/google/fscrypt/issues/new), following the
+guidelines in `CONTRIBUTING.md`. We will try our best to help.
 
 #### I changed my login passphrase, now all my directories are inaccessible
 
diff --git a/pam/pam.go b/pam/pam.go
index 804171d..3049efb 100644
--- a/pam/pam.go
+++ b/pam/pam.go
@@ -32,12 +32,15 @@ import (
 	"errors"
 	"fmt"
 	"unsafe"
+
+	"github.com/google/fscrypt/security"
 )
 
 // Handle wraps the C pam_handle_t type. This is used from within modules.
 type Handle struct {
 	handle *C.pam_handle_t
 	status C.int
+	privs  *security.Privileges
 }
 
 // NewHandle creates a Handle from a raw pointer.
@@ -105,19 +108,28 @@ func (h *Handle) GetItem(i Item) (unsafe.Pointer, error) {
 	return data, h.err()
 }
 
-// GetIDs retrieves the UID and GID of the corresponding PAM_USER.
-func (h *Handle) GetIDs() (uid int, gid int, err error) {
+// DropThreadPrivileges sets the effective privileges to that of the PAM user
+func (h *Handle) DropThreadPrivileges() error {
 	var pamUsername *C.char
+	var err error
+
 	h.status = C.pam_get_user(h.handle, &pamUsername, nil)
 	if err = h.err(); err != nil {
-		return 0, 0, err
+		return err
 	}
-
 	pwnam := C.getpwnam(pamUsername)
 	if pwnam == nil {
-		return 0, 0, fmt.Errorf("unknown user %q", C.GoString(pamUsername))
+		return fmt.Errorf("unknown user %q", C.GoString(pamUsername))
 	}
-	return int(pwnam.pw_uid), int(pwnam.pw_gid), nil
+
+	h.privs, err = security.DropThreadPrivileges(int(pwnam.pw_uid), int(pwnam.pw_gid))
+	return err
+}
+
+// RaiseThreadPrivileges restores the original privileges that were running the
+// PAM module (this is usually root).
+func (h *Handle) RaiseThreadPrivileges() error {
+	return security.RaiseThreadPrivileges(h.privs)
 }
 
 func (h *Handle) err() error {
diff --git a/security/keyring.go b/security/keyring.go
index f75b189..28225b0 100644
--- a/security/keyring.go
+++ b/security/keyring.go
@@ -151,11 +151,19 @@ func getUserKeyringID() (int, error) {
 func keyringLink(keyID int, keyringID int) error {
 	_, err := unix.KeyctlInt(unix.KEYCTL_LINK, keyID, keyringID, 0, 0)
 	log.Printf("KeyctlLink(%d, %d) = %v", keyID, keyringID, err)
-	return errors.Wrap(ErrKeyringLink, err.Error())
+
+	if err != nil {
+		return errors.Wrap(ErrKeyringLink, err.Error())
+	}
+	return err
 }
 
 func keyringUnlink(keyID int, keyringID int) error {
 	_, err := unix.KeyctlInt(unix.KEYCTL_UNLINK, keyID, keyringID, 0, 0)
 	log.Printf("KeyctlUnlink(%d, %d) = %v", keyID, keyringID, err)
-	return errors.Wrap(ErrKeyringUnlink, err.Error())
+
+	if err != nil {
+		return errors.Wrap(ErrKeyringUnlink, err.Error())
+	}
+	return err
 }