From nobody Thu Aug 01 22:00:25 2024 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4WZjZL1HtBz5RXKV; Thu, 01 Aug 2024 22:00:26 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4WZjZL0qHcz4WMs; Thu, 1 Aug 2024 22:00:26 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1722549626; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=L3gcV/OjzMiG4XGjYpHxglZrHn0xy7ta6z+AVfqyAoA=; b=pnWSu9OEGpReWPYSXo94Xe7AOqoI8x9mKEsxbRe1MNsjG+fPmgvl4obwdGeRVv+cUQc5pU 32gR3RTM65fYe/UB2H5IBU0G6wvC371+doFDu/08BL+DYybn4xK3Wpk9d0D2HPEZKOcKic Q8KyjqdTO3hN20UcV8G6vASm6V3eFC51zwrefsKnqo6nw1xy3EtTtlE4vcSxnIXoBaaVEr ksS4lNml52JUX/Ccc3P944Sm43YvnKWc5N4rV0zSzLV1iwQp/oiM/sd6XOdIWf6MYQLH3b 1eT7Fdp6D6plY426aAV7Js4T5rxxx1XjIvl0qzfKa5oxv7QHjAslxd/L4QDVAw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1722549626; a=rsa-sha256; cv=none; b=DoIVtQHHhAreeZ1VpxVlqEtkV+oN4yoQkGhLiLJ6QHUeXgHsjxFMh46tk7RBZ2DRQ8AhIA wnOh/dw0P/GoeRG+FWYCWtMvQKHyVcrgeQMttiTPdXnu3l5QN3AtX7icYjlgR6l3MO7Pjr Zv7TOZHP0MVc1kHfK2W9ATs5haXk7qnikLO4EQ2Ea7hmDJcehHQHr53tLNVubnV9g77/2J tfS2gglpUlk632ERCHWntS2y1+QtFLmXlkR+MRF9zlHJ6OeRLMrHoEnYNqznuGdNGQbe/v 9r7+pEPMV9RUH1KVwJsQLVKoYzdmBM6wgmOhwR85XGK9DMXMHLGwBQgNjV9YWA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1722549626; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=L3gcV/OjzMiG4XGjYpHxglZrHn0xy7ta6z+AVfqyAoA=; b=PUopnrY972OgpKClonhAWurzF6u8DBZ28x/xqoxTEc2einhINhpTxvCeu2u15SlPUwtfo2 8aNaY2er7tJjEgiY35SEqFuAsEhU0sb7SXbx7Cp/oiU48h3YuFMQLR9Go5chpwrXKj3NZX snQrl22wKrxpzIQLjkOJEFvePFTm+e+TXlJktPsVw/ctevTVeXXc0XW4UsK+stqBNYNNAm FlawGaYyf0YPEMs4BJEc112aMWBJGlKl4C1anvR7lEbrE2IvdCC0IPNAeq+iUFdLHaOmNa iRriOGl+2iIrVgYzllaELpOO9ChI6f7cYWi126eU5QFoOJAuRLmrqbcK6xsFNQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4WZjZL0QX2z12Q3; Thu, 1 Aug 2024 22:00:26 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 471M0PYa085608; Thu, 1 Aug 2024 22:00:25 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 471M0P7R085605; Thu, 1 Aug 2024 22:00:25 GMT (envelope-from git) Date: Thu, 1 Aug 2024 22:00:25 GMT Message-Id: <202408012200.471M0P7R085605@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: "Simon J. Gerraty" Subject: git: b77f618568f2 - main - Add examples to veriexec(8) List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: sjg X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: b77f618568f252da3a6c69e8aff25f6b1bada1fd Auto-Submitted: auto-generated The branch main has been updated by sjg: URL: https://cgit.FreeBSD.org/src/commit/?id=b77f618568f252da3a6c69e8aff25f6b1bada1fd commit b77f618568f252da3a6c69e8aff25f6b1bada1fd Author: Simon J. Gerraty AuthorDate: 2024-08-01 21:59:52 +0000 Commit: Simon J. Gerraty CommitDate: 2024-08-01 21:59:52 +0000 Add examples to veriexec(8) Add missing flags to veriexec(8) as well as some examples to help explain usage. Also add veriexec.4 Sponsored by: Juniper Networks, Inc. Reviewed by: imp Differential Revision: https://reviews.freebsd.org/D46207 --- sbin/veriexec/veriexec.8 | 84 ++++++++++++++++++++++++++++++++++++----- share/man/man4/Makefile | 1 + share/man/man4/veriexec.4 | 96 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 172 insertions(+), 9 deletions(-) diff --git a/sbin/veriexec/veriexec.8 b/sbin/veriexec/veriexec.8 index 2e476f327b14..3c85957357f5 100644 --- a/sbin/veriexec/veriexec.8 +++ b/sbin/veriexec/veriexec.8 @@ -1,7 +1,7 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2023, Juniper Networks, Inc. +.\" Copyright (c) 2018-2024, Juniper Networks, Inc. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -24,7 +24,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd August 8, 2023 +.Dd August 1, 2024 .Dt VERIEXEC 8 .Os .Sh NAME @@ -97,7 +97,7 @@ The possible states are: .Bl -tag -width enforce .It Ar loaded -set automatically when first +set automatically when the first .Pa manifest has been loaded. .It Ar active @@ -137,10 +137,11 @@ The manifest contains a mapping of relative pathnames to fingerprints with optional flags. For example: .Bd -literal -offset indent -sbin/veriexec sha256=f22136...c0ff71 no_ptrace +sbin/veriexec sha256=f22136...c0ff71 no_ptrace trusted usr/bin/python sha256=5944d9...876525 indirect sbin/somedaemon sha256=77fc2f...63f5687 label=mod1/val1,mod2/val2 .Ed +.Pp The supported flags are: .Bl -tag -width indirect .It Ql indirect @@ -149,16 +150,31 @@ but can be used as an interpreter for example via: .Bd -literal -offset indent #!/usr/bin/python .Ed +.It Ql no_fips +If the system has a notion of running in FIPS mode, +a file marked with this flag will not be allowed to +exec. .It Ql no_ptrace do not allow running executable under a debugger. Useful for any application critical to the security state of system. +.It Ql trusted +this flag is required for a process to use +.Xr veriexec 4 +to interact with +.Xr mac_veriexec 4 . +Generally only +.Nm +should need this flag. +Implies +.Ql no_ptrace . + .El .Pp The .Ql label argument allows associating a .Xr maclabel 7 -with the executable. +with a file. Neither .Nm nor @@ -167,10 +183,60 @@ nor pay any attention to the content of the label they are provided for the use of other .Xr mac 4 -modules. +modules or indeed other applications. +.Sh EXAMPLES +Load the manifest for a +.Xr tarfs 5 +package mounted on +.Pa /mnt +and be strict about enforcing certificate validity: +.Bd -literal -offset indent +# veriexec -S -C /mnt /mnt/manifest + +.Ed +.Nm +will look for a detatched signature that it recognizes, such as +.Pa manifest.asc +(OpenPGP) or +.Pa manifest.*sig +(X.509). +In the case of an X.509 signature we also need a matching certificate chain +.Pa manifest.*certs . +In either case there needs to be a suitable trust anchor in the trust store. +.Pp +We can now activate: +.Bd -literal -offset indent +# veriexec -z active + +.Ed +Any user can check if +.Xr mac_veriexec 4 +is +.Ql active : +.Bd -literal -offset indent +$ veriexec -i active + +.Ed +Any user can check that +.Pa /mnt/bin/app +is verified: +.Bd -literal -offset indent +$ veriexec -x /mnt/bin/app + +.Ed +If it is not, we will get an Authentiaction error, +but unless +.Xr mac_veriexec 4 +is enforcing we would still be able to run it. +.Sh NOTES +It is only safe to set +.Xr mac_veriexec 4 +to +.Ql enforce +state, if sufficient manifests have been loaded +to cover all the applications that might need to be run. .Sh HISTORY The Verified Exec system first appeared in .Nx . -This utility derives from the one found in Junos. -The key difference is the requirement that manifest files -be digitally signed. +This utility derives from the one found in Junos, +which requires that manifest files be digitally signed. diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index b4a8e484b137..4e685cac3ecf 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1054,6 +1054,7 @@ MAN+= \ uslcom.4 \ uvisor.4 \ uvscom.4 \ + veriexec.4 \ zyd.4 MLINKS+=otus.4 if_otus.4 diff --git a/share/man/man4/veriexec.4 b/share/man/man4/veriexec.4 new file mode 100644 index 000000000000..14e4aeae0d10 --- /dev/null +++ b/share/man/man4/veriexec.4 @@ -0,0 +1,96 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024, Juniper Networks, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 1, 2024 +.Dt VERIEXEC 4 +.Os +.Sh NAME +.Nm veriexec +.Nd the veriexec device +.Sh SYNOPSIS +.In dev/veriexec/veriexec_ioctl.h +.Sh DESCRIPTION +The +.Nm +device is used by +.Xr veriexec 8 +to query and modify the state of +.Xr mac_veriexec 4 . +.Pp +Once +.Xr mac_veriexec 4 +is active, only a process which is marked as +.Ql trusted +(normally only +.Xr veriexec 8 ) +is able to more than the +.Dv VERIEXEC_GETSTATE +ioctl. +.Sh IOCTLS +The supported ioctls are described below. +.Bl -tag +.It Dv VERIEXEC_SIGNED_LOAD Vt struct verified_exec_params +Pass file information to +.Xr mac_veriexec 4 . +.Bd -literal +struct verified_exec_params { + unsigned char flags; + char fp_type[VERIEXEC_FPTYPELEN]; /* type of fingerprint */ + char file[MAXPATHLEN]; + unsigned char fingerprint[MAXFINGERPRINTLEN]; +}; +.Ed +.It Dv VERIEXEC_LABEL_LOAD Vt struct verified_exec_label_params +Pass file information and a label to +.Xr mac_veriexec 4 . +.Bd -literal +struct verified_exec_label_params { + struct verified_exec_params params; + char label[MAXLABELLEN]; +}; +.Ed +.It Dv VERIEXEC_ACTIVE +.It Dv VERIEXEC_DEBUG_OFF +.It Dv VERIEXEC_DEBUG_ON Vt int level +.It Dv VERIEXEC_ENFORCE +.It Dv VERIEXEC_GETSTATE +.It Dv VERIEXEC_GETVERSION +.It Dv VERIEXEC_LOCK +.It Dv VERIEXEC_VERIFIED_FILE Vt int fd +Rarely needed. +Tells +.Xr mac_veriexec 4 +that the file associated with +.Va fd +is verified. +.El +.Sh HISTORY +A +.Nm +device first appeared in +.Nx . +It was added to +.Fx 13.1 .