From patchwork Mon Aug 29 11:47:57 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sargun Dhillon X-Patchwork-Id: 9303701 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 DB5F0607F0 for ; Mon, 29 Aug 2016 11:48:03 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id CC8592878B for ; Mon, 29 Aug 2016 11:48:03 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C181C28823; Mon, 29 Aug 2016 11:48:03 +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.8 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI,T_DKIM_INVALID autolearn=ham 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 5657D2878B for ; Mon, 29 Aug 2016 11:48:03 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932983AbcH2LsC (ORCPT ); Mon, 29 Aug 2016 07:48:02 -0400 Received: from mail-it0-f49.google.com ([209.85.214.49]:36776 "EHLO mail-it0-f49.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933000AbcH2LsA (ORCPT ); Mon, 29 Aug 2016 07:48:00 -0400 Received: by mail-it0-f49.google.com with SMTP id e63so97761460ith.1 for ; Mon, 29 Aug 2016 04:47:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sargun.me; s=google; h=date:from:to:cc:subject:message-id:mime-version:content-disposition :user-agent; bh=Mx3x+jp3OatqMf+dtrZZWiTWlQ4vNpUaB/GDt3unDSo=; b=KqymezqZfOUvwgIOVCfpv71geHIH65CUQTHxjB0cWzAgj+Di6HDSPewSHd3vSQpVm9 /hIHFObg4W7o1+Y4hbOZpfosMruaRW/iu1ADuPAGZoGL+eYscsApkEZ/+qDlJ2xUfdyp 88AnyPHbXc7/fD7kjoMydpyFrafF7PJ4PjC/c= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:user-agent; bh=Mx3x+jp3OatqMf+dtrZZWiTWlQ4vNpUaB/GDt3unDSo=; b=NXkyNAjs7zqvzCparSlt8luBoIoEm40pzkw5fEZ/Y+tn0u2i0EXLwgjq81MoWZoS83 h8SpMNYeqSNHojQuEgBRUILGGusfR5nD/t6iYqEuRaekFvIhtQ1XJheiqiDghFbvWY8W MjJX/pTfw0cfTkfW87hC5H7vc3/Ru8lRbn5cWg2zVkPPT6/BzC7En7JKVOsCnYFWZGv6 EbwvDM2oBVF4DoBYuz960IwSsFRLum3wKx2jTuPHwhhmirHh10pGSUJot5xPDB0lSXc6 yn2EID9GgRxPHSOY6+lMTboNMn04qzSByc1UrjzjeB/l2gJkC+13hNpkvKTAsyRK3bHk U3Zg== X-Gm-Message-State: AE9vXwM6ttBoO4e/WXlceUR2AhS0RkRxq824HVi4DXVlflLZZMCw9BGy3aW8N1sXf6lLbA== X-Received: by 10.36.77.85 with SMTP id l82mr15119216itb.77.1472471279149; Mon, 29 Aug 2016 04:47:59 -0700 (PDT) Received: from ircssh.c.rugged-nimbus-611.internal (55.145.251.23.bc.googleusercontent.com. [23.251.145.55]) by smtp.gmail.com with ESMTPSA id n67sm6010369itb.1.2016.08.29.04.47.58 (version=TLS1_2 cipher=AES128-SHA bits=128/128); Mon, 29 Aug 2016 04:47:59 -0700 (PDT) Date: Mon, 29 Aug 2016 04:47:57 -0700 From: Sargun Dhillon To: netdev@vger.kernel.org Cc: cgroups@vger.kernel.org, linux-security-module@vger.kernel.org, daniel@iogearbox.net, ast@fb.com Subject: [net-next RFC v2 9/9] doc: Add LSM / BPF Checmate docs Message-ID: <20160829114756.GA20918@ircssh.c.rugged-nimbus-611.internal> MIME-Version: 1.0 Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) Sender: owner-linux-security-module@vger.kernel.org Precedence: bulk List-ID: X-Virus-Scanned: ClamAV using ClamSMTP This adds documentation on how to operate, and develop against the Checmate LSM and Cgroup controller. Signed-off-by: Sargun Dhillon --- Documentation/security/Checmate.txt | 54 +++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 Documentation/security/Checmate.txt diff --git a/Documentation/security/Checmate.txt b/Documentation/security/Checmate.txt new file mode 100644 index 0000000..d409785 --- /dev/null +++ b/Documentation/security/Checmate.txt @@ -0,0 +1,54 @@ +--- What is Checmate? --- + +Checmate is a flexible programmable, extensible minor LSM that's coupled with +cgroups and BPF. It is designed to enforce container-specific policies. By +default, it does not enforce any policies. It is selectable at build time +with CONFIG_SECURITY_CHECMATE, and it is controlled through the unified cgroups +controller hierarchy. + +# How to use Checmate +In order to use Checmate, you have to enable the controller on the cgroup2 +hierarchy. In order to prevent a centralized configuration daemon from mounting +Checmate on the V1 hierarchy you may want to add 'cgroup_no_v1=checmate' to your +boot command line. + +Enabling the controller: + mount -t cgroup2 none $MOUNT_POINT + cd $MOUNT_POINT + echo +checmate > cgroup.subtree_control + +Once you do this, immediate children of this node on the hierarchy will have a +number of control files that begin with 'checmate.'. Each of these is mapped +to an LSM hook by the same name. If you read the file, it will return the +number of filters attached to that given hook. Details of the hooks can be +found in lsm_hooks.h. + +All tasks which are members of a cgroup will have no only the checmate filters +at that level enforced, but all levels above as well. If there is a need +to exempt a specific sub-cgroup, a program can use current_task_under_cgroup +along with a bpf map. + +## Adding filters: +If you would like to add a filter, you must compile a BPF_PROG_TYPE_CHECMATE BPF +program. You can then write the '%d\n' formatted version of the BPF program +file descriptor to the relevant control file. + +## Removing filters: +If you would like to remove a specific filter, you can write the negative file +descriptor of the BPF program to the control file (a la '-%d\n'). If you would +like to do this, then it is recommended that you pin your programs. + +If you would like to remove all filters from a specific hook, simply write '0' +to the control file. During normal operation, you shouldn't have the bpf syscall +return '0' for a given program, please take proper precautions to work around +this. + +# Caveats +## Hook Limit: +Each hook is limited to having MAX_CHECMATE_INSTANCES (32) hooks per level +in the hierarchy. The write call will return ENOSPC if you hit this condition. + +## CGroup v2 interaction with CGroup v1: +Because the cgroups subsystem is in transition, using the net_prio or the +net_classid v1 cgroups will render Checmate inoperable on all network +hooks that inspect sockets. \ No newline at end of file