From patchwork Mon Nov 16 21:01:37 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 11910857 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-12.3 required=3.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED,DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FORGED_FROMDOMAIN, FREEMAIL_FROM,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5D587C63777 for ; Mon, 16 Nov 2020 21:03:10 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id C15FE2224F for ; Mon, 16 Nov 2020 21:03:09 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="TKwV9k+F" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org C15FE2224F Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id AA4756B0036; Mon, 16 Nov 2020 16:03:08 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id A53066B005C; Mon, 16 Nov 2020 16:03:08 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 8F71B6B005D; Mon, 16 Nov 2020 16:03:08 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0069.hostedemail.com [216.40.44.69]) by kanga.kvack.org (Postfix) with ESMTP id 620C86B0036 for ; Mon, 16 Nov 2020 16:03:08 -0500 (EST) Received: from smtpin13.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay04.hostedemail.com (Postfix) with ESMTP id 069C11EE6 for ; Mon, 16 Nov 2020 21:03:08 +0000 (UTC) X-FDA: 77491506456.13.chain32_050f3372732c Received: from filter.hostedemail.com (10.5.16.251.rfc1918.com [10.5.16.251]) by smtpin13.hostedemail.com (Postfix) with ESMTP id D115118140B67 for ; Mon, 16 Nov 2020 21:03:07 +0000 (UTC) X-HE-Tag: chain32_050f3372732c X-Filterd-Recvd-Size: 10156 Received: from mail-wm1-f65.google.com (mail-wm1-f65.google.com [209.85.128.65]) by imf23.hostedemail.com (Postfix) with ESMTP for ; Mon, 16 Nov 2020 21:03:07 +0000 (UTC) Received: by mail-wm1-f65.google.com with SMTP id m125so645299wmm.3 for ; Mon, 16 Nov 2020 13:03:06 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=kIBok6LhmX2oON2re8xwKd0vvOgtGJnjM3IpLHusadw=; b=TKwV9k+FZKUd2LAwXA+k72FWcs+EPrCRoALmGFbD1zvuHvxTQ+SSqk553M+WEdyPNp UmdIZ88Rz6NEybpakhEMzRK+Ex8y/oxuPDgYrUWPK8ORLJ4vfIj5IMSnSW1s/xpgxPhu l/9tL8fSIFraFFAnx1wLnxtKybQO2iFuutx+KxjMJJBHWrHfivKaN7s/aBUVJ5dCQo5a XpeLRtYnvT99t9llbCTi70/dwIH2b0v8T76uTZLzqhr1a/fXg20tXBKmLtyGtfyq9TAO ZlYZGmGgiO/ido1nqu2l+9NLu7Tpe8zdX+RBqaX6CjR6AzsxcijUPQQdvL1Hcr5GFp7O iNOA== 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:mime-version:content-transfer-encoding; bh=kIBok6LhmX2oON2re8xwKd0vvOgtGJnjM3IpLHusadw=; b=IQsQQpcBPKeg2VPOQhysbFuUhpIBj947f7dl8B4DZeFtmcP6Yq0Ybjbe2c578eeMFH laH2TROWvQxy7qeNxtfEQfWnkUE1ifFbc1Z+GmuOMV362PIZINSyPUulddYQN6zn5zjz 6wddtLrg8I4MC8gFAIaT2rwM/aZp5DXUUOvKgveutt99zvqVl6/eoNaGcsjr6v4ohmMA NoghrwQZCrFl/lClQM+lN0zpk6Wm1McZrt+0hD6iSXBgePPilZiXsO5A9Loyju6QN3jM W18OUN0eF1R33/4cQ/zYjqXZBgEDWFv10Fb+jkEULkERCCJsqDQ1Vr6tRkfnGkALdE/9 0gKg== X-Gm-Message-State: AOAM532ahl5IXh5KAaSVLQHxND2eL0GUd4Rd4PXUenemaop1pUS3Hz4j AOUmO9WFUmAI4pUoa06U6RY= X-Google-Smtp-Source: ABdhPJzOHhNlIpkSPa99BnwvG5LvoWEVPEOt0VC2sDFCF+lKYb8sZV+/i98RGOfuFhg4vt+8hd5CTg== X-Received: by 2002:a1c:c2c3:: with SMTP id s186mr813200wmf.160.1605560585749; Mon, 16 Nov 2020 13:03:05 -0800 (PST) Received: from localhost.localdomain ([170.253.51.130]) by smtp.gmail.com with ESMTPSA id p4sm24660325wrm.51.2020.11.16.13.03.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 16 Nov 2020 13:03:05 -0800 (PST) From: Alejandro Colomar To: rppt@kernel.org, mtk.manpages@gmail.com Cc: Mike Rapoport , akpm@linux-foundation.org, arnd@arndb.de, bp@alien8.de, catalin.marinas@arm.com, cl@linux.com, colomar.6.4.3@gmail.com, dan.j.williams@intel.com, dave.hansen@linux.intel.com, david@redhat.com, elena.reshetova@intel.com, hpa@zytor.com, idan.yaniv@ibm.com, jejb@linux.ibm.com, kirill@shutemov.name, linux-api@vger.kernel.org, linux-arch@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-man@vger.kernel.org, linux-mm@kvack.org, linux-nvdimm@lists.01.org, linux-riscv@lists.infradead.org, luto@kernel.org, mark.rutland@arm.com, mingo@redhat.com, palmer@dabbelt.com, paul.walmsley@sifive.com, peterz@infradead.org, shuah@kernel.org, tglx@linutronix.de, tycho@tycho.ws, viro@zeniv.linux.org.uk, will@kernel.org, willy@infradead.org, x86@kernel.org, Alejandro Colomar Subject: [PATCH v2] memfd_secret.2: New page describing memfd_secret() system call Date: Mon, 16 Nov 2020 22:01:37 +0100 Message-Id: <20201116210136.12390-1-alx.manpages@gmail.com> X-Mailer: git-send-email 2.29.2 In-Reply-To: <20201005073242.GA4251@kernel.org> References: <20201005073242.GA4251@kernel.org> MIME-Version: 1.0 X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: From: Mike Rapoport Signed-off-by: Mike Rapoport Cowritten-by: Alejandro Colomar Acked-by: Alejandro Colomar Signed-off-by: Alejandro Colomar --- Hi Mike, I added that note about not having a wrapper, fixed a few minor formatting and wording issues, and sorted ERRORS alphabetically. Cheers, Alex man2/memfd_secret.2 | 178 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 man2/memfd_secret.2 diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2 new file mode 100644 index 000000000..4e617aa0e --- /dev/null +++ b/man2/memfd_secret.2 @@ -0,0 +1,178 @@ +.\" Copyright (c) 2020, IBM Corporation. +.\" Written by Mike Rapoport +.\" +.\" Based on memfd_create(2) man page +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 David Herrmann +.\" +.\" %%%LICENSE_START(GPLv2+) +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH MEMFD_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual" +.SH NAME +memfd_secret \- create an anonymous file to map secret memory regions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int memfd_secret(unsigned long " flags ");" +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.BR memfd_secret () +creates an anonymous file and returns a file descriptor that refers to it. +The file can only be memory-mapped; +the memory in such mapping +will have stronger protection than usual memory mapped files, +and so it can be used to store application secrets. +Unlike a regular file, a file created with +.BR memfd_secret () +lives in RAM and has a volatile backing storage. +Once all references to the file are dropped, it is automatically released. +The initial size of the file is set to 0. +Following the call, the file size should be set using +.BR ftruncate (2). +.PP +The memory areas obtained with +.BR mmap (2) +from the file descriptor are exclusive to the owning context. +These areas are removed from the kernel page tables +and only the page table of the process holding the file descriptor +maps the corresponding physical memory. +.PP +The following values may be bitwise ORed in +.IR flags +to control the behavior of +.BR memfd_secret (2): +.TP +.BR FD_CLOEXEC +Set the close-on-exec flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.PP +.TP +.BR SECRETMEM_UNCACHED +In addition to excluding memory areas from the kernel page tables, +mark the memory mappings uncached in the page table of the owning process. +Such mappings can be used to prevent speculative loads +and cache-based side channels. +This mode of +.BR memfd_secret () +is not supported on all architectures. +.PP +See also NOTES below. +.PP +As its return value, +.BR memfd_secret () +returns a new file descriptor that can be used to refer to an anonymous file. +This file descriptor is opened for both reading and writing +.RB ( O_RDWR ) +and +.B O_LARGEFILE +is set for the file descriptor. +.PP +With respect to +.BR fork (2) +and +.BR execve (2), +the usual semantics apply for the file descriptor created by +.BR memfd_secret (). +A copy of the file descriptor is inherited by the child produced by +.BR fork (2) +and refers to the same file. +The file descriptor is preserved across +.BR execve (2), +unless the close-on-exec flag has been set. +.PP +The memory regions backed with +.BR memfd_secret () +are locked in the same way as +.BR mlock (2), +however the implementation will not try to +populate the whole range during the +.BR mmap () +call. +The amount of memory allowed for memory mappings +of the file descriptor obeys the same rules as +.BR mlock (2) +and cannot exceed +.BR RLIMIT_MEMLOCK . +.SH RETURN VALUE +On success, +.BR memfd_secret () +returns a new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I flags +included unknown bits. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B EMFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +There was insufficient memory to create a new anonymous file. +.TP +.B ENOSYS +.BR memfd_secret () +is not implemented on this architecture. +.SH VERSIONS +The +.BR memfd_secret (2) +system call first appeared in Linux 5.X; +.SH CONFORMING TO +The +.BR memfd_secret (2) +system call is Linux-specific. +.SH NOTES +The +.BR memfd_secret (2) +system call provides an ability to hide information +from the operating system. +Normally Linux userspace mappings are protected from other users, +but they are visible to privileged code. +The mappings created using +.BR memfd_secret () +are hidden from the kernel as well. +.PP +If an architecture supports +.BR SECRETMEM_UNCACHED , +the mappings also have protection from speculative execution vulnerabilties, +at the expense of increased memory access latency. +Care should be taken when using +.B SECRETMEM_UNCACHED +to avoid degrading application performance. +.PP +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.SH SEE ALSO +.BR fcntl (2), +.BR ftruncate (2), +.BR mlock (2), +.BR mmap (2), +.BR setrlimit (2)