From patchwork Tue Sep 25 14:40:12 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jens Wiklander X-Patchwork-Id: 147472 Delivered-To: patches@linaro.org Received: by 2002:a2e:8595:0:0:0:0:0 with SMTP id b21-v6csp812590lji; Tue, 25 Sep 2018 07:40:43 -0700 (PDT) X-Received: by 2002:a19:eadb:: with SMTP id y88-v6mr1138603lfi.1.1537886443263; Tue, 25 Sep 2018 07:40:43 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1537886443; cv=none; d=google.com; s=arc-20160816; b=LHQOgtZk13U8sY3rF8dNO2VEcjU+P9MEE7G/bAAfzs5lW+DWt/gjIWbbMpZrkw0q1q 25dxQNisqffs2VOYmIe7HZ1f8TexPYPPVIy2fZsTtYYvprssfjo13gWFloRNgLk71vC/ +DVZ+o9rLJA6kFquZGq64/IsQ2d48etPOYd91MqRxwZvAIo2rBoc7gYKvqd6FO5mysQc iszHD64LuWnECGiK8SRL7NLa+XtaCruq3suGVfHt3vqgFHgTBhw98MRjpeQRGsK2zMOW xkhvBT0yhtZursQ/jl0Zu3lOs05jeSHXilVLtg4ePwcqkXnqqrNyI8t3BKv8hYIZKfEK lxmA== 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=lgCdUmBufLy6+xjFvNL7oyDbBWl5csz7nRRV9iomFaE=; b=OpSjQSa+eTzPbGRcvQ5jVUxHELU4qkT+hvbi1xb/wR/lC49x4UMvRAfkn4kRyPIOYd MkJfuTblnee/zzI4wazJMR0gDA0v3YF3LNDRUGaZ2EEbVxeF99FkT/xK1MprQ8czgNS0 Iiy/BGSTRn94vYMOla2lMRM5EkpThFwO4S3E1KUDZF0AreOF4MRtC8ikWkBwGbtH3kkh bw8jFcMuwoOrqsY+qanet0bu7DbvNre46Ghskvkzsb6wfrA9Nz1lWsAEzIkSWJSBCFrx fOIo/ZMelpTZebVEQCzEjh7j8gO+Xi1MNKpyJwzPyTZn0e0x/tQbuYhMPmEV22qRbZ82 1vCA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=b7EH3smm; spf=pass (google.com: domain of jens.wiklander@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=jens.wiklander@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 y65-v6sor1605829lje.34.2018.09.25.07.40.43 for (Google Transport Security); Tue, 25 Sep 2018 07:40:43 -0700 (PDT) Received-SPF: pass (google.com: domain of jens.wiklander@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=b7EH3smm; spf=pass (google.com: domain of jens.wiklander@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=jens.wiklander@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=lgCdUmBufLy6+xjFvNL7oyDbBWl5csz7nRRV9iomFaE=; b=b7EH3smmX7CTYq9fpSaUt7e9w+y5+ziuSYldtQCg17UoxjfEQSdet+8DoENDyLSwAA 8kQBQYfkm2Tqg6r5gCbTSK3pewVny7HugOv1oNU49w7vRoKd7f1F71E24gr4vD5mMTt3 mZOhUd2R6zR4fEwpmQmjknhdeZoujTWpLyIHY= 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=lgCdUmBufLy6+xjFvNL7oyDbBWl5csz7nRRV9iomFaE=; b=jzCO+DV19nMvTF0Xo9xIRZZeImNQMPcX8LWucEOxDobLClwg6M81+/dJV7w1q9YgFT tyae4KCxSg2Gba1mGYWVqW3+eXIYdkxPSNkEHSBBwVKgmzZ6/KtatVkI9zIV0fL5zzAV BMEcpZ1fxU39t+wlAnYOWopEnt+DG7K9nKLFmWTDNSFxICGeY7LPdnkBN36w1esaH2+9 RiVB3RB84jW5h9ddGe3Bkn3ZQg7RrFQuoSCeKa4cOmu1oQWAvjVnS2L81WDxafTJd+Cu /59l6/R85FHEilidTtGbkK8SG4LSQYzwM+6fNUZtMOO5Thf8wrQlPHT8S2K1FFgosbHw Gxsg== X-Gm-Message-State: ABuFfohN+ZoA/Kvgtp+lBnGC6TJ9UuI8QZ990pkoRPJdFYEjhlsHqqVn OP9PO5B+bly1XPyZvNEumIFPE1u+ X-Google-Smtp-Source: ACcGV62lyK1HucAfPKD2jKKMihgrCICAqh8hiehZdijVjsT6fOz0OrEYmtp9t28bj8CAJgcnJhjiDA== X-Received: by 2002:a2e:52c4:: with SMTP id n65-v6mr1262758lje.54.1537886442647; Tue, 25 Sep 2018 07:40:42 -0700 (PDT) Return-Path: Received: from jax.urgonet (h-84-105.A175.priv.bahnhof.se. [79.136.84.105]) by smtp.gmail.com with ESMTPSA id g14-v6sm14483lja.96.2018.09.25.07.40.41 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 25 Sep 2018 07:40:41 -0700 (PDT) From: Jens Wiklander To: u-boot@lists.denx.de Cc: Simon Glass , Igor Opaniuk , Tom Rini , Jaehoon Chung , Pierre Aubert , Albert Aribaud , Peter Griffin , Michal Simek , Jens Wiklander Subject: [PATCH v4 08/19] Documentation: tee uclass and op-tee driver Date: Tue, 25 Sep 2018 16:40:12 +0200 Message-Id: <20180925144023.24555-9-jens.wiklander@linaro.org> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20180925144023.24555-1-jens.wiklander@linaro.org> References: <20180925144023.24555-1-jens.wiklander@linaro.org> Reviewed-by: Simon Glass Signed-off-by: Jens Wiklander --- doc/README.tee | 112 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 doc/README.tee -- 2.17.1 diff --git a/doc/README.tee b/doc/README.tee new file mode 100644 index 000000000000..79e7996a6f5f --- /dev/null +++ b/doc/README.tee @@ -0,0 +1,112 @@ +============= +TEE uclass +============= + +This document describes the TEE uclass in U-Boot + +A TEE (Trusted Execution Environment) is a trusted OS running in some +secure environment, for example, TrustZone on ARM CPUs, or a separate +secure co-processor etc. A TEE driver handles the details needed to +communicate with the TEE. + +This uclass deals with: + +- Registration of TEE drivers + +- Managing shared memory between U-Boot and the TEE + +- Providing a generic API to the TEE + +The TEE interface +================= + +include/tee.h defines the generic interface to a TEE. + +A client finds the TEE device via tee_find_device(). Other important functions +when interfacing with a TEE are: + +- tee_shm_alloc(), tee_shm_register() and tee_shm_free() to manage shared + memory objects often needed when communicating with the TEE. + +- tee_get_version() lets the client know which the capabilities of the TEE + device. + +- tee_open_session() opens a session to a Trusted Application + +- tee_invoke_func() invokes a function in a Trusted Application + +- tee_close_session() closes a session to a Trusted Application + +Much of the communication between clients and the TEE is opaque to the +driver. The main job for the driver is to receive requests from the +clients, forward them to the TEE and send back the results. + +OP-TEE driver +============= + +The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM +TrustZone based OP-TEE solution that is supported. + +Lowest level of communication with OP-TEE builds on ARM SMC Calling +Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface +[3] used internally by the driver. Stacked on top of that is OP-TEE Message +Protocol [4]. + +OP-TEE SMC interface provides the basic functions required by SMCCC and some +additional functions specific for OP-TEE. The most interesting functions are: + +- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information + which is then returned by TEE_IOC_VERSION + +- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used + to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a + separate secure co-processor. + +- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol + +- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory + range to used for shared memory between Linux and OP-TEE. + +The GlobalPlatform TEE Client API [5] is implemented on top of the generic +TEE API. + +Picture of the relationship between the different components in the +OP-TEE architecture: + + U-Boot Secure world + ~~~~~~ ~~~~~~~~~~~~ + +------------+ +-------------+ + | Client | | Trusted | + | | | Application | + +------------+ +-------------+ + /\ /\ + || || + \/ \/ + +------------+ +-------------+ + | TEE | | TEE Internal| + | uclass | | API | + +------------+ +-------------+ + | OP-TEE | | OP-TEE | + | driver | | Trusted OS | + +------------+-----------+-------------+ + | OP-TEE MSG | + | SMCCC (OPTEE_SMC_CALL_*) | + +--------------------------------------+ + +RPC (Remote Procedure Call) are requests from secure world to the driver. +An RPC is identified by a special range of SMCCC return values from +OPTEE_SMC_CALL_WITH_ARG. + +References +========== + +[1] https://github.com/OP-TEE/optee_os + +[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html + +[3] drivers/tee/optee/optee_smc.h + +[4] drivers/tee/optee/optee_msg.h + +[5] http://www.globalplatform.org/specificationsdevice.asp look for + "TEE Client API Specification v1.0" and click download.