From patchwork Sat May 13 11:51:52 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kees Cook X-Patchwork-Id: 9725183 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id BA80F60325 for ; Sat, 13 May 2017 11:53:54 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A82AD288DD for ; Sat, 13 May 2017 11:53:54 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9CD4A288E2; Sat, 13 May 2017 11:53:54 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.3 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI, RCVD_IN_SORBS_SPAM, T_DKIM_INVALID autolearn=unavailable version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id AE734288DD for ; Sat, 13 May 2017 11:53:53 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932206AbdEMLxe (ORCPT ); Sat, 13 May 2017 07:53:34 -0400 Received: from mail-pg0-f44.google.com ([74.125.83.44]:32916 "EHLO mail-pg0-f44.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753764AbdEMLwK (ORCPT ); Sat, 13 May 2017 07:52:10 -0400 Received: by mail-pg0-f44.google.com with SMTP id u187so41118456pgb.0 for ; Sat, 13 May 2017 04:52:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=B0i6WnD3F/L2mZuBJr48cpJR00Kv+/Rxpz1QfpFhVF0=; b=imIpLOvhomqzhbTylWBn5TlwP9m6aUjSW/yrEZU1A60Gx5xmvwIiJllnJaoU3xEhfz bCTaBIYuYxsQN1AXzv7fCFr0A4gFIWI6d5vIl1WLaOrENoczKfROIpPwUqOgj3nDQ12E 3ebfRvuqG5I6QtwYWgGOJkG75EpypLJ4N5PNI= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=B0i6WnD3F/L2mZuBJr48cpJR00Kv+/Rxpz1QfpFhVF0=; b=gs6C+BZuu/jqidfE3VRo81MwGnbD9SwR7diV43CUgghc9wfZKc1Bdkz0R7SPBU1Vn7 y1cL6MftX8FuWl2MJH+17jLir7KdLu/iQyBY2mz+kuQG0aaHuJz/x0w3s3peReZVnqWs goF/uqvaK+uw+NB2fJFZPoTKrd57RxluzF7UpY8lTR1PCXXzXEcj+kLUAvAiT1K2K5Qg CD/OINt8ve7KSpK1IRsriWAYPErlGwB8zvh4mFD8KjlWqDl0LfSXEOnDE4jDOzvkkjzC DvCT33iFU5NSI3vKsv3IrEC70eM3QeWSHS7qt32X/CqnVgbtQOBQ4OV4vU+jRckK5Sw3 B2oA== X-Gm-Message-State: AODbwcADgiPLwaABg8juCl7DYZ4pNKJEGSq1T5nHAXu7L5JbisK4k7UI 1oJ1JEZBxGL7K1Tu X-Received: by 10.99.115.17 with SMTP id o17mr9054478pgc.146.1494676329607; Sat, 13 May 2017 04:52:09 -0700 (PDT) Received: from www.outflux.net (173-164-112-133-Oregon.hfc.comcastbusiness.net. [173.164.112.133]) by smtp.gmail.com with ESMTPSA id v45sm11089273pgn.56.2017.05.13.04.52.04 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 13 May 2017 04:52:06 -0700 (PDT) From: Kees Cook To: Jonathan Corbet Cc: Kees Cook , David Howells , John Johansen , Tetsuo Handa , Paul Moore , Mimi Zohar , Casey Schaufler , James Morris , Tyler Hicks , David Safford , linux-doc@vger.kernel.org, linux-security-module@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 16/17] doc: ReSTify keys-request-key.txt Date: Sat, 13 May 2017 04:51:52 -0700 Message-Id: <1494676313-144890-17-git-send-email-keescook@chromium.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1494676313-144890-1-git-send-email-keescook@chromium.org> References: <1494676313-144890-1-git-send-email-keescook@chromium.org> Sender: owner-linux-security-module@vger.kernel.org Precedence: bulk List-ID: X-Virus-Scanned: ClamAV using ClamSMTP Adjusts for ReST markup and moves under keys security devel index. Cc: David Howells Signed-off-by: Kees Cook --- Documentation/filesystems/nfs/idmapper.txt | 2 +- Documentation/networking/dns_resolver.txt | 2 +- Documentation/security/00-INDEX | 2 - Documentation/security/keys/index.rst | 1 + .../{keys-request-key.txt => keys/request-key.rst} | 69 +++++++++++----------- security/keys/request_key.c | 2 +- security/keys/request_key_auth.c | 2 +- 7 files changed, 38 insertions(+), 42 deletions(-) rename Documentation/security/{keys-request-key.txt => keys/request-key.rst} (78%) diff --git a/Documentation/filesystems/nfs/idmapper.txt b/Documentation/filesystems/nfs/idmapper.txt index fe03d10bb79a..b86831acd583 100644 --- a/Documentation/filesystems/nfs/idmapper.txt +++ b/Documentation/filesystems/nfs/idmapper.txt @@ -55,7 +55,7 @@ request-key will find the first matching line and corresponding program. In this case, /some/other/program will handle all uid lookups and /usr/sbin/nfs.idmap will handle gid, user, and group lookups. -See for more information +See for more information about the request-key function. diff --git a/Documentation/networking/dns_resolver.txt b/Documentation/networking/dns_resolver.txt index d86adcdae420..eaa8f9a6fd5d 100644 --- a/Documentation/networking/dns_resolver.txt +++ b/Documentation/networking/dns_resolver.txt @@ -143,7 +143,7 @@ the key will be discarded and recreated when the data it holds has expired. dns_query() returns a copy of the value attached to the key, or an error if that is indicated instead. -See for further +See for further information about request-key function. diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX index 08a6e7a195ef..c8dbbc227326 100644 --- a/Documentation/security/00-INDEX +++ b/Documentation/security/00-INDEX @@ -1,6 +1,4 @@ 00-INDEX - this file. -keys-request-key.txt - - description of the kernel key request service. keys-trusted-encrypted.txt - info on the Trusted and Encrypted keys in the kernel key ring service. diff --git a/Documentation/security/keys/index.rst b/Documentation/security/keys/index.rst index d34f663354bb..d7ddbc1c2502 100644 --- a/Documentation/security/keys/index.rst +++ b/Documentation/security/keys/index.rst @@ -7,3 +7,4 @@ Kernel Keys core ecryptfs + request-key diff --git a/Documentation/security/keys-request-key.txt b/Documentation/security/keys/request-key.rst similarity index 78% rename from Documentation/security/keys-request-key.txt rename to Documentation/security/keys/request-key.rst index 51987bfecfed..5cdcee28479e 100644 --- a/Documentation/security/keys-request-key.txt +++ b/Documentation/security/keys/request-key.rst @@ -1,19 +1,19 @@ - =================== - KEY REQUEST SERVICE - =================== +=================== +Key Request Service +=================== The key request service is part of the key retention service (refer to Documentation/security/keys.txt). This document explains more fully how the requesting algorithm works. The process starts by either the kernel requesting a service by calling -request_key*(): +``request_key*()``:: struct key *request_key(const struct key_type *type, const char *description, const char *callout_info); -or: +or:: struct key *request_key_with_auxdata(const struct key_type *type, const char *description, @@ -21,14 +21,14 @@ or: size_t callout_len, void *aux); -or: +or:: struct key *request_key_async(const struct key_type *type, const char *description, const char *callout_info, size_t callout_len); -or: +or:: struct key *request_key_async_with_auxdata(const struct key_type *type, const char *description, @@ -36,7 +36,7 @@ or: size_t callout_len, void *aux); -Or by userspace invoking the request_key system call: +Or by userspace invoking the request_key system call:: key_serial_t request_key(const char *type, const char *description, @@ -67,38 +67,37 @@ own upcall mechanisms. If they do, then those should be substituted for the forking and execution of /sbin/request-key. -=========== -THE PROCESS +The Process =========== A request proceeds in the following manner: - (1) Process A calls request_key() [the userspace syscall calls the kernel + 1) Process A calls request_key() [the userspace syscall calls the kernel interface]. - (2) request_key() searches the process's subscribed keyrings to see if there's + 2) request_key() searches the process's subscribed keyrings to see if there's a suitable key there. If there is, it returns the key. If there isn't, and callout_info is not set, an error is returned. Otherwise the process proceeds to the next step. - (3) request_key() sees that A doesn't have the desired key yet, so it creates + 3) request_key() sees that A doesn't have the desired key yet, so it creates two things: - (a) An uninstantiated key U of requested type and description. + a) An uninstantiated key U of requested type and description. - (b) An authorisation key V that refers to key U and notes that process A + b) An authorisation key V that refers to key U and notes that process A is the context in which key U should be instantiated and secured, and from which associated key requests may be satisfied. - (4) request_key() then forks and executes /sbin/request-key with a new session + 4) request_key() then forks and executes /sbin/request-key with a new session keyring that contains a link to auth key V. - (5) /sbin/request-key assumes the authority associated with key U. + 5) /sbin/request-key assumes the authority associated with key U. - (6) /sbin/request-key execs an appropriate program to perform the actual + 6) /sbin/request-key execs an appropriate program to perform the actual instantiation. - (7) The program may want to access another key from A's context (say a + 7) The program may want to access another key from A's context (say a Kerberos TGT key). It just requests the appropriate key, and the keyring search notes that the session keyring has auth key V in its bottom level. @@ -110,10 +109,10 @@ A request proceeds in the following manner: instantiate key U, using key W as a reference (perhaps it contacts a Kerberos server using the TGT) and then instantiates key U. - (9) Upon instantiating key U, auth key V is automatically revoked so that it + 9) Upon instantiating key U, auth key V is automatically revoked so that it may not be used again. -(10) The program then exits 0 and request_key() deletes key V and returns key + 10) The program then exits 0 and request_key() deletes key V and returns key U to the caller. This also extends further. If key W (step 7 above) didn't exist, key W would @@ -127,8 +126,7 @@ This is because process A's keyrings can't simply be attached to of them, and (b) it requires the same UID/GID/Groups all the way through. -==================================== -NEGATIVE INSTANTIATION AND REJECTION +Negative Instantiation And Rejection ==================================== Rather than instantiating a key, it is possible for the possessor of an @@ -145,23 +143,22 @@ signal, the key under construction will be automatically negatively instantiated for a short amount of time. -==================== -THE SEARCH ALGORITHM +The Search Algorithm ==================== A search of any particular keyring proceeds in the following fashion: - (1) When the key management code searches for a key (keyring_search_aux) it + 1) When the key management code searches for a key (keyring_search_aux) it firstly calls key_permission(SEARCH) on the keyring it's starting with, if this denies permission, it doesn't search further. - (2) It considers all the non-keyring keys within that keyring and, if any key + 2) It considers all the non-keyring keys within that keyring and, if any key matches the criteria specified, calls key_permission(SEARCH) on it to see if the key is allowed to be found. If it is, that key is returned; if not, the search continues, and the error code is retained if of higher priority than the one currently set. - (3) It then considers all the keyring-type keys in the keyring it's currently + 3) It then considers all the keyring-type keys in the keyring it's currently searching. It calls key_permission(SEARCH) on each keyring, and if this grants permission, it recurses, executing steps (2) and (3) on that keyring. @@ -173,20 +170,20 @@ returned. When search_process_keyrings() is invoked, it performs the following searches until one succeeds: - (1) If extant, the process's thread keyring is searched. + 1) If extant, the process's thread keyring is searched. - (2) If extant, the process's process keyring is searched. + 2) If extant, the process's process keyring is searched. - (3) The process's session keyring is searched. + 3) The process's session keyring is searched. - (4) If the process has assumed the authority associated with a request_key() + 4) If the process has assumed the authority associated with a request_key() authorisation key then: - (a) If extant, the calling process's thread keyring is searched. + a) If extant, the calling process's thread keyring is searched. - (b) If extant, the calling process's process keyring is searched. + b) If extant, the calling process's process keyring is searched. - (c) The calling process's session keyring is searched. + c) The calling process's session keyring is searched. The moment one succeeds, all pending errors are discarded and the found key is returned. @@ -194,7 +191,7 @@ returned. Only if all these fail does the whole thing fail with the highest priority error. Note that several errors may have come from LSM. -The error priority is: +The error priority is:: EKEYREVOKED > EKEYEXPIRED > ENOKEY diff --git a/security/keys/request_key.c b/security/keys/request_key.c index 9822e500d50d..63e63a42db3c 100644 --- a/security/keys/request_key.c +++ b/security/keys/request_key.c @@ -8,7 +8,7 @@ * as published by the Free Software Foundation; either version * 2 of the License, or (at your option) any later version. * - * See Documentation/security/keys-request-key.txt + * See Documentation/security/keys/request-key.rst */ #include diff --git a/security/keys/request_key_auth.c b/security/keys/request_key_auth.c index 0f062156dfb2..afe9d22ab361 100644 --- a/security/keys/request_key_auth.c +++ b/security/keys/request_key_auth.c @@ -8,7 +8,7 @@ * as published by the Free Software Foundation; either version * 2 of the License, or (at your option) any later version. * - * See Documentation/security/keys-request-key.txt + * See Documentation/security/keys/request-key.rst */ #include