Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757733AbcLOLlE (ORCPT ); Thu, 15 Dec 2016 06:41:04 -0500 Received: from mail-wm0-f67.google.com ([74.125.82.67]:34071 "EHLO mail-wm0-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755581AbcLOLlB (ORCPT ); Thu, 15 Dec 2016 06:41:01 -0500 Cc: mtk.manpages@gmail.com, linux-man , linux-security-module , lkml To: "Serge E. Hallyn" , Casey Schaufler , James Morris , Kees Cook , Andy Lutomirski , John Stultz , Jann Horn , "Eric W. Biederman" From: "Michael Kerrisk (man-pages)" Subject: RFC: capabilities(7): notes for kernel developers Message-ID: Date: Thu, 15 Dec 2016 12:40:56 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.4.0 MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2496 Lines: 56 Hello all, Because the topic every now then comes up "which capability should I associate with the new feature that I'm adding to the kernel?", I propose to add the text below to the capabilities(7) man page [1] with some recommendations on how to go about choosing. I would be happy to get feedback, suggestions for improvement and so on. Cheers, Michael [1] http://man7.org/linux/man-pages/man7/capabilities.7.html Notes to kernel developers When adding a new kernel feature that should be governed by a capability, consider the following points. * The goal of capabilities is divide the power of superuser into small pieces, such that if a program that has capabilities is compromised, its power to do damage to the system would be much less than a similar set-user-ID-root program. * You have the choice of either creating a new capability for your new feature, or associating the feature with one of the existing capabilities. Because the size of capability sets is currently limited to 64 bits, the latter option is preferable, unless there are compelling reasons to take the former option. * To determine which existing capability might best be associated with your new feature, review the list of capabilities above in order to find a "silo" into which your new feature best fits. * Don't choose CAP_SYS_ADMIN if you can possibly avoid it! A vast proportion of existing capability checks are associated with this capability, to the point where it can plausibly be called "the new root". Don't make the problem worse. The only new features that should be associated with CAP_SYS_ADMIN are ones that closely match existing uses in that silo. * If you have determined that it really is necessary to create a new capability for your feature, avoid making (and naming) it as a "single-use" capability. Thus, for example, the addition of the highly specific CAP_WAKE_ALARM was probably a mistake. Instead, try to identify and name your new capability as a broader silo into which other related future use cases might fit. -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/