From nobody Wed Apr 15 12:57:23 2026 Received: from mx0b-0031df01.pphosted.com (mx0b-0031df01.pphosted.com [205.220.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 3305E3C5DCD for ; Fri, 10 Apr 2026 13:40:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=205.220.180.131 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1775828445; cv=none; b=olLg44IygKbw5nNXojUIxqtCwUyLcfS1vVVDSH0QWRXgpqH4qUZO9WG5xspKd8C0feybaygaXHopV+hQsoYnz6ZpJjAM27fgQaiouby08Lp1TlndvM5U5LAJBpJFNAWJRCBbOQ+Q1FZb+OhsUwJCaMEEfLzgpF7D6FBPpuJi2n8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1775828445; c=relaxed/simple; bh=ZzD48c6YNqTNTxvog2KhjcUYavGruY/dRo31R1J745I=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=Co2GZ4JWZy2blNjmnHsx05zsDeOqXDoZAzZ0gh84Sqy4zutpu9/Rb0K6rWpx176R8FPwd8xos+bkA2u24XA/ABszjaYvJDlAXCl9ttjJshAfQjedKL3iv5ETLIVPRnnVwAUTOcJJHQRwSPcMgAub6OBRJuiGj+8an4S6D9xP2Rg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=oss.qualcomm.com; spf=pass smtp.mailfrom=oss.qualcomm.com; dkim=pass (2048-bit key) header.d=qualcomm.com header.i=@qualcomm.com header.b=GISwSpW9; dkim=pass (2048-bit key) header.d=oss.qualcomm.com header.i=@oss.qualcomm.com header.b=G/yC+bFh; arc=none smtp.client-ip=205.220.180.131 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=oss.qualcomm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=oss.qualcomm.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=qualcomm.com header.i=@qualcomm.com header.b="GISwSpW9"; dkim=pass (2048-bit key) header.d=oss.qualcomm.com header.i=@oss.qualcomm.com header.b="G/yC+bFh" Received: from pps.filterd (m0279869.ppops.net [127.0.0.1]) by mx0a-0031df01.pphosted.com (8.18.1.11/8.18.1.11) with ESMTP id 63A92wVc115045 for ; Fri, 10 Apr 2026 13:40:42 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=qualcomm.com; h= cc:content-transfer-encoding:date:from:in-reply-to:message-id :mime-version:references:subject:to; s=qcppdkim1; bh=4/G7uDRt/NN 5uhqO8B7jr/VAfO0+XnKeOAa+4ruW6IA=; b=GISwSpW9PL/WB+EIKDmDd5ONuKn Oz2E254irHMF71/LzvvEz3+ZhGBZmNcSUC0ywboTcfQC1yQGkCB0BcZp1M80OlQz K+W4ds/tueKzDQbPt4Y5GY7EXFythgbht49+MLaucVo2CuLPVrn5IL0rqV4l3osa 2G/h1BRtKFuLSx79Ifwr1BaQ/pkuTi8hMVgiY8YwAPnRv+ZWzQ+pRgGt1Kquz4f8 jKWqZA9n8l+j6ie8egkI6R5fet9eLFmaYs4/fPSwjt/aXl+7yVRfh4KKL8nzd9X5 Qd2fHES4XslHPKNs/EiYlxMZb4tfRiEDM6VoAdJCI2/zMMHzyZxS9CoWhTw== Received: from mail-dl1-f70.google.com (mail-dl1-f70.google.com [74.125.82.70]) by mx0a-0031df01.pphosted.com (PPS) with ESMTPS id 4dee8xc1q5-1 (version=TLSv1.3 cipher=TLS_AES_128_GCM_SHA256 bits=128 verify=NOT) for ; Fri, 10 Apr 2026 13:40:41 +0000 (GMT) Received: by mail-dl1-f70.google.com with SMTP id a92af1059eb24-12bf9974587so1027947c88.0 for ; Fri, 10 Apr 2026 06:40:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oss.qualcomm.com; s=google; t=1775828441; x=1776433241; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=4/G7uDRt/NN5uhqO8B7jr/VAfO0+XnKeOAa+4ruW6IA=; b=G/yC+bFhpy2alp4Kz1DU/eWAhCK+Ff/NX8ksFMSz9yz7UOYN3jYCdJT9tqlmtNoZTC wD5chhp64+KLvA7u4bHh1pqQWDJIemSw3wHp1sBX3RPNNs/wMDsn/wsUt/RFxuHLrua3 6Qsbd7O4ciflOqc35dIRoSUWb55JE6tv1c0N8imZVRG78ZtZf0m2DrGTroLOCzyNPB69 pHuCZ4CQVKH0pXGd7+8wGK9ZtBNF8YkwISOhiWa/1UZ4uu9+XzSDrAwRdDPf9Q+YI6FU H51HBI7Rq1JWQyrcX7c1EKr7NRtZ740miIrzTWwCif93dQHrjMjJ2H/zuD+ys9Z91jDp eq5w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1775828441; x=1776433241; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=4/G7uDRt/NN5uhqO8B7jr/VAfO0+XnKeOAa+4ruW6IA=; b=DNjKfx74QUauMbzG4wWm3Q8my7Zl0XDeN8yRcUlsBSNHsT5LZf0fj1tr6I4BEzLF0Q rwFaTQ4RBw5pJC+Q190VoyAquUwaNQ6kIXq3bcoFSUz5bxEreG1gQDJSET9oJjTlzHhR Uq76Fa5tgD6/dg9iEvTaEVZusgtPd6R7T1TdgExDvNPCQCcmNDaLzpvPuhTLOuyq8p6o rTk8HyBbKgOoqDzdjaK1/GI+AZ4q4rMTqGm782ZHkRYtLluaao9Xow3lJd/GEmw0sdms ysv2EzpqjyKDR/yqYwtgIKQptVsDXpBFmAFZT1teIKYpmQxPAKJqE3+J0uwcfMNsRfbv K0Zg== X-Gm-Message-State: AOJu0YwUKLINISnxkrwqYVS9Uzm3eYB9YAvyBjgetl7JekN27Pz5PMOu btRbwmQ4TwGPKqsByiHXaCTc3f1xooHci5T4yuRxNBgWWCo+ffVoCo+C1gPjbAnncc+DMsmGfG4 9oe9aA0umoCyP7mviZJXrHKIIkhPI5k8Il+qznfJAOcrTeRRRnuJYli4q7983wT4OXJk= X-Gm-Gg: AeBDiesXUcxiXlLT9kfTv/tEsxORAuPkPYvXW8POycUY4eiG+j+gek0lJzJdMdRSCUT 6n+xBqcvGvbkRDny2hfMYN4O3a2BM7kANkqlQDFfnHhTTfDk+VT4lXdwwShYeWUpe/n2M2UMEtG /15w3KSVB2H4Rn5VJNZ6Cr5JeYEfJGXiMtsuSaQTygRsxt4a6Brck7EN+xlPrScRfodCdmZZ5zW 0x9KwK0ULxv8jhYS4HouP8emNmiARV6nTWlITsNvwfVFmWmFckpDTtVXatuZ76yJIwGnSnf89Ei pEfXMsecfT7qTp3iacJV+j/qhqjXY7eOWrkAPo/W3YDgi3DJZFfZ3GzkW0XpFymDA8RcOJ5GFLJ bdQS8SugzTgUtHwpE/1BExoVmmHtv5czOI9X6TrPT12Zgs3tRoRJWuaxpSEH0e/4fr5QkFthxCK smHkEO X-Received: by 2002:a05:7022:790:b0:11b:b179:6e17 with SMTP id a92af1059eb24-12c34f07ce4mr1827744c88.34.1775828440751; Fri, 10 Apr 2026 06:40:40 -0700 (PDT) X-Received: by 2002:a05:7022:790:b0:11b:b179:6e17 with SMTP id a92af1059eb24-12c34f07ce4mr1827703c88.34.1775828439906; Fri, 10 Apr 2026 06:40:39 -0700 (PDT) Received: from u20-san1p10573.qualcomm.com (i-global254.qualcomm.com. [199.106.103.254]) by smtp.gmail.com with ESMTPSA id 5a478bee46e88-2d561bde70csm5172631eec.15.2026.04.10.06.40.39 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 10 Apr 2026 06:40:39 -0700 (PDT) From: Linlin Zhang To: linux-block@vger.kernel.org, ebiggers@kernel.org, mpatocka@redhat.com, gmazyland@gmail.com Cc: linux-kernel@vger.kernel.org, adrianvovk@gmail.com, dm-devel@lists.linux.dev, quic_mdalam@quicinc.com, israelr@nvidia.com, hch@infradead.org, axboe@kernel.dk Subject: [PATCH v2 3/3] dm: add documentation for dm-inlinecrypt target Date: Fri, 10 Apr 2026 06:40:31 -0700 Message-Id: <20260410134031.2880675-4-linlin.zhang@oss.qualcomm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20260410134031.2880675-1-linlin.zhang@oss.qualcomm.com> References: <20260410134031.2880675-1-linlin.zhang@oss.qualcomm.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Proofpoint-Spam-Details-Enc: AW1haW4tMjYwNDEwMDEyOCBTYWx0ZWRfX2kBsckzlNclg p/0BaYDbciOUmew8yVe194a8q2+nDI9zfOl2yGsHEFXUCJil+qDTCWHpibDmqBkjnY7IAB4O7pf Fh+r/BJm/uzuXa7wWCbrcpLjJ4kQJLEBDQsLXINfdw2deESobKwQ/tqtwn4tBYNUXS2h/7wme1l cyuwI7qVIVPzVvmnNM6MM14QoDMrNd2Bhbl/RC9dpC6QkZfPaj0b7oqQrpqxIMGbvabWzV6gOSg w3NHw2beYwgVRK/YLy8UGNtLEtBYZO4a91NuY566QzxTF6s+B7luK168IsS6YyZ4Dpb8YEs5lSu Bx6k/vF7IZwTa6PZgjxpQuPWGH7NSf1JmomR8CdIaQHBWlGFROo7LOnDH+m5+BPDkMpU39RIrrF 3CksZUV0t/btDkik5nAA1u7ZUKBdz/p21XpoXUtXByMgVFrk8qrjAC/O4aHweKLyCrd5KPqlj0P n1gUDztAS0klnK2RJ1w== X-Proofpoint-GUID: Rb8Xs9oCqHqQewn-oYAiAPuul4m5yAf2 X-Proofpoint-ORIG-GUID: Rb8Xs9oCqHqQewn-oYAiAPuul4m5yAf2 X-Authority-Analysis: v=2.4 cv=O7YJeh9W c=1 sm=1 tr=0 ts=69d8fdd9 cx=c_pps a=SvEPeNj+VMjHSW//kvnxuw==:117 a=JYp8KDb2vCoCEuGobkYCKw==:17 a=A5OVakUREuEA:10 a=s4-Qcg_JpJYA:10 a=VkNPw1HP01LnGYTKEx00:22 a=u7WPNUs3qKkmUXheDGA7:22 a=_glEPmIy2e8OvE2BGh3C:22 a=VwQbUJbxAAAA:8 a=p0WdMEafAAAA:8 a=EUspDBNiAAAA:8 a=r5tAstHzX-DRmjCks68A:9 a=Kq8ClHjjuc5pcCNDwlU0:22 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1143,Hydra:6.1.51,FMLib:17.12.100.49 definitions=2026-04-10_04,2026-04-09_02,2025-10-01_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 bulkscore=0 spamscore=0 phishscore=0 priorityscore=1501 adultscore=0 impostorscore=0 malwarescore=0 suspectscore=0 lowpriorityscore=0 clxscore=1015 classifier=typeunknown authscore=0 authtc= authcc= route=outbound adjust=0 reason=mlx scancount=1 engine=8.22.0-2604010000 definitions=main-2604100128 Content-Type: text/plain; charset="utf-8" This adds the admin-guide documentation for dm-inlinecrypt. dm-inlinecrypt.rst is the guide to using dm-inlinecrypt. Signed-off-by: Linlin Zhang --- .../device-mapper/dm-inlinecrypt.rst | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 Documentation/admin-guide/device-mapper/dm-inlinecrypt.= rst diff --git a/Documentation/admin-guide/device-mapper/dm-inlinecrypt.rst b/D= ocumentation/admin-guide/device-mapper/dm-inlinecrypt.rst new file mode 100644 index 000000000000..c302ba73fc38 --- /dev/null +++ b/Documentation/admin-guide/device-mapper/dm-inlinecrypt.rst @@ -0,0 +1,122 @@ +=3D=3D=3D=3D=3D=3D=3D=3D +dm-inlinecrypt +=3D=3D=3D=3D=3D=3D=3D=3D + +Device-Mapper's "inlinecrypt" target provides transparent encryption of bl= ock devices +using the inline encryption hardware. + +For a more detailed description of inline encryption, see: +https://docs.kernel.org/block/inline-encryption.html + +Parameters:: + + \ + [<#opt_params> ] + + + Encryption cipher type. + + The cipher specifications format is:: + + cipher + + Examples:: + + aes-xts-plain64 + + The cipher type is correspond one-to-one with encryption modes. For + instance, the corresponding crypto mode of aes-xts-plain64 is + BLK_ENCRYPTION_MODE_AES_256_XTS. + + + Key used for encryption. It is encoded either as a hexadecimal number + or it can be passed as prefixed with single colon + character (':') for keys residing in kernel keyring service. + You can only use key sizes that are valid for the selected cipher. + Note that the size in bytes of a valid key must be in bellow range. + + [BLK_CRYPTO_KEY_TYPE_RAW, BLK_CRYPTO_KEY_TYPE_HW_WRAPPED] + + + The kernel keyring key is identified by string in following format: + ::. + + + The encryption key size in bytes. The kernel key payload size must mat= ch + the value passed in . + + + Either 'logon', or 'trusted' kernel key type. + + + The kernel keyring key description inlinecrypt target should look for + when loading key of . + + + The IV offset is a sector count that is added to the sector number + before creating the IV. + + + This is the device that is going to be used as backend and contains the + encrypted data. You can specify it as a path like /dev/xxx or a device + number :. + + + Starting sector within the device where the encrypted data begins. + +<#opt_params> + Number of optional parameters. If there are no optional parameters, + the optional parameters section can be skipped or #opt_params can be z= ero. + Otherwise #opt_params is the number of following arguments. + + Example of optional parameters section: + allow_discards sector_size:4096 iv_large_sectors + +allow_discards + Block discard requests (a.k.a. TRIM) are passed through the inlinecrypt + device. The default is to ignore discard requests. + + WARNING: Assess the specific security risks carefully before enabling = this + option. For example, allowing discards on encrypted devices may lead = to + the leak of information about the ciphertext device (filesystem type, + used space etc.) if the discarded blocks can be located easily on the + device later. + +sector_size: + Use as the encryption unit instead of 512 bytes sectors. + This option can be in range 512 - 4096 bytes and must be power of two. + Virtual device will announce this size as a minimal IO and logical sec= tor. + +iv_large_sectors + IV generators will use sector number counted in units + instead of default 512 bytes sectors. + + For example, if is 4096 bytes, plain64 IV for the second + sector will be 8 (without flag) and 1 if iv_large_sectors is present. + The must be multiple of (in 512 bytes units) + if this flag is specified. + +Example scripts +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +LUKS (Linux Unified Key Setup) is now the preferred way to set up disk +encryption with dm-inlinecrypt using the 'cryptsetup' utility, see +https://gitlab.com/cryptsetup/cryptsetup + +:: + + #!/bin/sh + # Create a inlinecrypt device using dmsetup + dmsetup create inlinecrypt1 --table "0 `blockdev --getsz $1` inlinecrypt = aes-xts-plain64 babebabebabebabebabebabebabebabebabebabebabebabebabebabebab= ebabe 0 $1 0" + +:: + + #!/bin/sh + # Create a inlinecrypt device using dmsetup when encryption key is stored= in keyring service + dmsetup create inlinecrypt2 --table "0 `blockdev --getsz $1` inlinecrypt = aes-xts-plain64 :64:logon:fde:dminlinecrypt_test_key 0 $1 0" + +:: + + #!/bin/sh + # Create a inlinecrypt device using cryptsetup and LUKS header with defau= lt cipher + cryptsetup luksFormat $1 + cryptsetup luksOpen $1 inlinecrypt1 --=20 2.34.1