From patchwork Mon Jun 10 12:08:34 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sumit Garg X-Patchwork-Id: 166315 Delivered-To: patches@linaro.org Received: by 2002:a92:4782:0:0:0:0:0 with SMTP id e2csp949563ilk; Mon, 10 Jun 2019 05:09:09 -0700 (PDT) X-Received: by 2002:a17:90a:ac11:: with SMTP id o17mr21302338pjq.134.1560168549197; Mon, 10 Jun 2019 05:09:09 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1560168549; cv=none; d=google.com; s=arc-20160816; b=uDoxxfG3VfN6jgjy08zfpqU/rpAky9291uYw5N7JREkShNMPr6R7MV3Fx7OL8R9rCV FyekiBLElAD+9+05YPSxTg8tc2HIzNQKtoQbOf1LXl1R5ExuiguOk9ahiywmfNTDoKK4 tHqh/ywBJ9v4VgSUKFQMzDmBy07l2cOVxVafzEQeKSsdKTpcdeF5Qn2GXVdY9uUsOV2J 1aIzMKp7mHttJEOHDnDJdl9h3Xii0p1HTEEpXH2SWbhzg7NYlsddcojq1xGdDHzAQ1HT V7mM7eJkzYl8TYB4/T/G8EA4EvWTb6du0PC8GYpQ07dFDL/Ey6z5wGWD5VqRz6CWOmAi n0MA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=BG6KAi08hN8hMpB1R8APRtbarxqkieDJBwiiKnKxNvA=; b=ygjMwkNqSbMW9O/CLxVrBqAxVDG1tEoFBUustcPOUSnVqUJCDR0ZoZ+PB6O0SG9A8Z GmIpJBso5g7iGIswDf1PzXSMfLGqWKg7bnb11msh4epdsfHDW/sm8kLhbBjqZsQMMoNv c1rxf304lT3B+X7+mgb2wiTd3n6rKe7Z/mTKw8LKMCEXVBTnyxU5ls6f+fYPrecZQ4+X wnr9XHyYMeEKLyHP0ZI31dtBkGYFbdLSNjfsi4sgDJaNIr2vq4EVKA0VQSbCxv8gXnDW C6/zDsw5mefY0iRo43Bw1zgMi2OtB66c75sSNWA9dlx/CKM0RwdedRdEpAqWrF5pMotz bgkQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=kYDRbSCH; spf=pass (google.com: domain of sumit.garg@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=sumit.garg@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65]) by mx.google.com with SMTPS id s193sor9593872pfs.6.2019.06.10.05.09.08 for (Google Transport Security); Mon, 10 Jun 2019 05:09:09 -0700 (PDT) Received-SPF: pass (google.com: domain of sumit.garg@linaro.org designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=kYDRbSCH; spf=pass (google.com: domain of sumit.garg@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=sumit.garg@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=BG6KAi08hN8hMpB1R8APRtbarxqkieDJBwiiKnKxNvA=; b=kYDRbSCHbSss6GpqeBvmBH8fxCn1gWNRC3Lnqv4v4Nz1xKqbXYdLmNaMwXGhbJoYvd RCryAIms2JTVgLaIAbq///1Lk3uoLGdWEL9w4M3GmMd3uH0sx/7QV3DHb2vlK0Ep3gwr 9g93Ly+isKqBsfjXQxG+aTsxUln7j1YPS6IH6WlTJLzHxC5aNXK9zMfITxhFPb82zzLt +yje/p6hdTEFShAL5GlDRFDcffqiQyd5ria0hzidX7pgNDBsIlfIacjs/1aRwkNlp/zW dDhqcHVG8w/E/aRbBob3rxHvEqiwEhMBGQEo4OQFfyYXfnU/8/z8EAYpnWF4eQo3bgXR MUag== 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; bh=BG6KAi08hN8hMpB1R8APRtbarxqkieDJBwiiKnKxNvA=; b=ctJcrPrMIfz1MbsilZLSrLaQnj/JWTDb57KT6cQASyvHvhtTOFZCb+sXc2LADGV0dy e1IT/dZSYFM1K0cc31QZvlXC8zjfG7X5lE8PFfknQEr95tyAVBMayn9ye8tlH0vFIBdq mtjHzrkfd9zM+RkrhdX3WFTKO4r01HjcXGRoW0hWOt3VWf6t49KqkntK5NsGELMFw3rA kaVxIGF7HU7p6eF3YfwhsQS/qNlum7naO/qzdf8eL2ULWJFE5A8vrvaW+eDhYVqkfBfE XosqcbltO+U7kLFXPeCO2u5CghlnqaNqmYC1eLtlvYBmVJXiIJY2vkeXDOBzasWxiuV5 aVwA== X-Gm-Message-State: APjAAAUWCGxmP+GHMpm/63NXXBtDRq5Pm69LhC1ep4tGM8GEuxElNeOU 0xxh44JJqZ9RKndELnfk1zFd6fxs5ti+1w== X-Google-Smtp-Source: APXvYqwF/tnH3YruVjw9+vzpV0Z2/HKFi34ElLBeSTpC2gYQ5tb7P0Bm1OTLNlWVR+mD2TZIP+AjYw== X-Received: by 2002:aa7:8013:: with SMTP id j19mr12090662pfi.212.1560168548697; Mon, 10 Jun 2019 05:09:08 -0700 (PDT) Return-Path: Received: from localhost.localdomain ([117.196.234.139]) by smtp.gmail.com with ESMTPSA id f7sm2452961pfd.43.2019.06.10.05.09.06 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 10 Jun 2019 05:09:08 -0700 (PDT) From: Sumit Garg To: daniel.thompson@linaro.org Cc: patches@linaro.org, Sumit Garg Subject: [PATCH 6/7] doc: keys: Document usage of TEE based Trusted Keys Date: Mon, 10 Jun 2019 17:38:34 +0530 Message-Id: <1560168515-32714-7-git-send-email-sumit.garg@linaro.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1560168515-32714-1-git-send-email-sumit.garg@linaro.org> References: <1560168515-32714-1-git-send-email-sumit.garg@linaro.org> Provide documentation for usage of TEE based Trusted Keys via existing user-space "keyctl" utility. Also, document various use-cases. Signed-off-by: Sumit Garg --- Documentation/security/keys/tee-trusted.rst | 93 +++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 Documentation/security/keys/tee-trusted.rst -- 2.7.4 diff --git a/Documentation/security/keys/tee-trusted.rst b/Documentation/security/keys/tee-trusted.rst new file mode 100644 index 0000000..ef03745 --- /dev/null +++ b/Documentation/security/keys/tee-trusted.rst @@ -0,0 +1,93 @@ +====================== +TEE based Trusted Keys +====================== + +TEE based Trusted Keys provides an alternative approach for providing Trusted +Keys in case TPM chip isn't present. + +Trusted Keys use a TEE service/device both to generate and to seal the keys. +Keys are sealed under a hardware unique key in the TEE, and only unsealed by +the TEE. + +For more information about TEE, refer to ``Documentation/tee.txt``. + +Usage:: + + keyctl add trusted name "new keylen" ring + keyctl add trusted name "load hex_blob" ring + keyctl print keyid + +"keyctl print" returns an ascii hex copy of the sealed key, which is in format +specific to TEE device implementation. The key length for new keys are always +in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). + +Examples of trusted key and its usage as 'master' key for encrypted key usage: + +More details about encrypted keys can be found here: +``Documentation/security/keys/trusted-encrypted.rst`` + +Create and save a trusted key named "kmk" of length 32 bytes:: + + $ keyctl add trusted kmk "new 32" @u + 754414669 + + $ keyctl show + Session Keyring + 827385718 --alswrv 0 65534 keyring: _uid_ses.0 + 274124851 --alswrv 0 65534 \_ keyring: _uid.0 + 754414669 --als-rv 0 0 \_ trusted: kmk + + $ keyctl print 754414669 + 15676790697861b422175596ae001c2f505cea2c6f3ebbc5fb08eeb1f343a07e + + $ keyctl pipe 754414669 > kmk.blob + +Load a trusted key from the saved blob:: + + $ keyctl add trusted kmk "load `cat kmk.blob`" @u + 491638700 + + $ keyctl print 491638700 + 15676790697861b422175596ae001c2f505cea2c6f3ebbc5fb08eeb1f343a07e + +The initial consumer of trusted keys is EVM, which at boot time needs a high +quality symmetric key for HMAC protection of file metadata. The use of a +TEE based trusted key provides security that the EVM key has not been +compromised by a user level problem and tied to particular hardware. + +Create and save an encrypted key "evm" using the above trusted key "kmk": + +option 1: omitting 'format':: + + $ keyctl add encrypted evm "new trusted:kmk 32" @u + 608915065 + +option 2: explicitly defining 'format' as 'default':: + + $ keyctl add encrypted evm "new default trusted:kmk 32" @u + 608915065 + + $ keyctl print 608915065 + default trusted:kmk 32 f380ac588a925f488d5be007cf23e4c900b8b652ab62241c8 + ed54906189b6659d139d619d4b51752a2645537b11fd44673f13154a65b3f595d5fb2131 + 2fe45529ea0407c644ea4026f2a1a75661f2c9b66 + + $ keyctl pipe 608915065 > evm.blob + +Load an encrypted key "evm" from saved blob:: + + $ keyctl add encrypted evm "load `cat evm.blob`" @u + 831684262 + + $ keyctl print 831684262 + default trusted:kmk 32 f380ac588a925f488d5be007cf23e4c900b8b652ab62241c8 + ed54906189b6659d139d619d4b51752a2645537b11fd44673f13154a65b3f595d5fb2131 + 2fe45529ea0407c644ea4026f2a1a75661f2c9b66 + +Other uses for trusted and encrypted keys, such as for disk and file encryption +are anticipated. In particular the 'ecryptfs' encrypted keys format can be used +to mount an eCryptfs filesystem. More details about the usage can be found in +the file ``Documentation/security/keys/ecryptfs.rst``. + +Another format 'enc32' can be used to support encrypted keys with payload size +of 32 bytes.