[PATCH] CRED: Document the credential API's (ab)use of const pointers

[David Howells <dhowells@redhat.com>]

Document the credential API's (ab)use of const pointers.  Various pointers to
credentials, such as those in the task_struct, are declared const.  The purpose
of this is to compile-time discouragement of altering credentials through those
pointers.  Once a set of credentials has been made public through one of these
pointers, it may not be modified, except under special circumstances:

  (1) Its reference count may incremented and decremented.

  (2) The keyrings to which it points may be modified, but not replaced.

The only safe way to modify anything else is to create a replacement and commit
using the functions described in Documentation/credentials.txt.

Signed-off-by: David Howells <dhowells@redhat.com>
---

 Documentation/credentials.txt |   19 +++++++++++++++++++
 include/linux/cred.h          |   12 +++++++++++-
 kernel/cred.c                 |    2 +-
 3 files changed, 31 insertions(+), 2 deletions(-)


diff --git a/Documentation/credentials.txt b/Documentation/credentials.txt
index d1f1391..df03169 100644
--- a/Documentation/credentials.txt
+++ b/Documentation/credentials.txt
@@ -14,6 +14,7 @@ Contents:
 
  (*) Task credentials.
 
+     - Immutable credentials.
      - Accessing task credentials.
      - Accessing another task's credentials.
      - Altering credentials.
@@ -309,6 +310,24 @@ attachment to process-specific keyrings in the requesting process as the
 instantiating process may need to create them.
 
 
+IMMUTABLE CREDENTIALS
+---------------------
+
+Once a set of credentials has been made public (by calling commit_creds() for
+example), it must be considered immutable, barring two exceptions:
+
+ (1) The reference count may be altered.
+
+ (2) Whilst the keyring subscriptions of a set of credentials may not be
+     changed, the keyrings subscribed to may have their contents altered.
+
+To catch accidental credential alteration at compile time, struct task_struct
+has _const_ pointers to its credential sets, as does struct file.  Furthermore,
+certain functions such as get_cred() and put_cred() operate on const pointers,
+thus rendering casts unnecessary, but require to temporarily ditch the const
+qualification to be able to alter the reference count.
+
+
 ACCESSING TASK CREDENTIALS
 --------------------------
 
diff --git a/include/linux/cred.h b/include/linux/cred.h
index b156ed4..1f8d8d0 100644
--- a/include/linux/cred.h
+++ b/include/linux/cred.h
@@ -1,4 +1,4 @@
-/* Credentials management
+/* Credentials management - see Documentation/credentials.txt
  *
  * Copyright (C) 2008 Red Hat, Inc. All Rights Reserved.
  * Written by David Howells (dhowells@redhat.com)
@@ -175,6 +175,12 @@ static inline struct cred *get_new_cred(struct cred *cred)
  *
  * Get a reference on the specified set of credentials.  The caller must
  * release the reference.
+ *
+ * This is used to deal with a committed set of credentials.  Although the
+ * pointer is const, this will temporarily discard the const and increment the
+ * usage count.  The purpose of this is to attempt to catch at compile time the
+ * accidental alteration of a set of credentials that should be considered
+ * immutable.
  */
 static inline const struct cred *get_cred(const struct cred *cred)
 {
@@ -187,6 +193,10 @@ static inline const struct cred *get_cred(const struct cred *cred)
  *
  * Release a reference to a set of credentials, deleting them when the last ref
  * is released.
+ *
+ * This takes a const pointer to a set of credentials because the credentials
+ * on task_struct are attached by const pointers to prevent accidental
+ * alteration of otherwise immutable credential sets.
  */
 static inline void put_cred(const struct cred *_cred)
 {
diff --git a/kernel/cred.c b/kernel/cred.c
index decd080..9006c75 100644
--- a/kernel/cred.c
+++ b/kernel/cred.c
@@ -1,4 +1,4 @@
-/* Task credentials management
+/* Task credentials management - see Documentation/credentials.txt
  *
  * Copyright (C) 2008 Red Hat, Inc. All Rights Reserved.
  * Written by David Howells (dhowells@redhat.com)