From patchwork Tue Dec 5 17:00:07 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Github ODP bot X-Patchwork-Id: 120714 Delivered-To: patch@linaro.org Received: by 10.140.22.227 with SMTP id 90csp5990617qgn; Tue, 5 Dec 2017 09:01:14 -0800 (PST) X-Google-Smtp-Source: AGs4zMZKDrMCF4lB4mcIG7KjZFP5C+fRY5uKSIfwPDlJpaxX9TaWy+9yoF0jUVo+RSU5pPWPfHnS X-Received: by 10.176.90.14 with SMTP id l14mr4587643uad.180.1512493274266; Tue, 05 Dec 2017 09:01:14 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1512493274; cv=none; d=google.com; s=arc-20160816; b=TMgthu494osqiEMT05T7Fsgckf9ZAQxRqx3xNUBcmRKCv43VOl7h2n6VGcCU1Cz/t6 9PKBXfDrT+GOaI5LfZpufpERNS5h44yjIIj6i8AbvwJhUgNAy4ekKayMoMUx9WwYpNrf og8wvO0LFFBXeJAWoMROmfs/Q9ZI4Iu02czy1hrBiTRi8KdLHzvuA3fpP/FzpKornlKT W7nF3EzmBSukhcET3ZTqYGUS4aZtwh0Q7NnoIq6mg1mlWk0eAReD7pVAj9QPshJul0WM F7/gitf7H7NZICIy0X3XToWs5Sg/69SB5nRoPgCddb9j2lAO9OqojU1bbJ+q0dgpJajZ SJ0g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:github-pr-num :references:in-reply-to:message-id:date:to:from:delivered-to :arc-authentication-results; bh=Fmlg3ERdO5nbcpLXnutgbq/j9i3QhYwH5mYD74j1kXY=; b=kQC022wnQ/9bP04nYY3JLCr7VY563kmxHPdWbjxqxnAJV36Gau4y80GtNSzADC1Ajj eOMPvYnmhleY5knOVnTEB0WhoN363oj6eYgSjZTlJ2/gpjcIO2stHfetWWA0thfsMTvC rn0mim3KO9QdoeeUd2No6DUYxoe70LmfULjfrAkXpIYr2UGoto2sZnVY4iLen/Wt11Gi WkYdBJQyWyJTdLJjV/0qtA/BovcmMEJP66APLzW9Vi9O9xFchhWr60kE/+9/bz8yYx2V WrBspntBnmfZhU+N+ikNZiaKBdjfpcKWCP22AYc4ALAHE/r0Br9kJRtLKVVRCYQ23nqL wN7A== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=yandex.ru Return-Path: Received: from lists.linaro.org (ec2-54-197-127-237.compute-1.amazonaws.com. [54.197.127.237]) by mx.google.com with ESMTP id a189si374097vke.382.2017.12.05.09.01.14; Tue, 05 Dec 2017 09:01:14 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) client-ip=54.197.127.237; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=yandex.ru Received: by lists.linaro.org (Postfix, from userid 109) id E077160810; Tue, 5 Dec 2017 17:01:13 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00,FREEMAIL_FROM, RCVD_IN_DNSWL_LOW,RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 359026074A; Tue, 5 Dec 2017 17:00:29 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id C33726065D; Tue, 5 Dec 2017 17:00:17 +0000 (UTC) Received: from forward105j.mail.yandex.net (forward105j.mail.yandex.net [5.45.198.248]) by lists.linaro.org (Postfix) with ESMTPS id 149CA6038D for ; Tue, 5 Dec 2017 17:00:11 +0000 (UTC) Received: from mxback9g.mail.yandex.net (mxback9g.mail.yandex.net [IPv6:2a02:6b8:0:1472:2741:0:8b7:170]) by forward105j.mail.yandex.net (Yandex) with ESMTP id DBF81182D5A for ; Tue, 5 Dec 2017 20:00:09 +0300 (MSK) Received: from smtp4o.mail.yandex.net (smtp4o.mail.yandex.net [2a02:6b8:0:1a2d::28]) by mxback9g.mail.yandex.net (nwsmtp/Yandex) with ESMTP id YbyVa0wugX-09ieKW00; Tue, 05 Dec 2017 20:00:09 +0300 Received: by smtp4o.mail.yandex.net (nwsmtp/Yandex) with ESMTPSA id lqMd7Egaet-09GavBOL; Tue, 05 Dec 2017 20:00:09 +0300 (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (Client certificate not present) From: Github ODP bot To: lng-odp@lists.linaro.org Date: Tue, 5 Dec 2017 20:00:07 +0300 Message-Id: <1512493207-12168-2-git-send-email-odpbot@yandex.ru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1512493207-12168-1-git-send-email-odpbot@yandex.ru> References: <1512493207-12168-1-git-send-email-odpbot@yandex.ru> Github-pr-num: 320 Subject: [lng-odp] [PATCH API-NEXT v2 1/1] doc: userguide: ipsec state machine changes X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" From: Bill Fischofer Replace the FSMs used to describe SA state transitions and IPsec operations with a Message Sequence Diagram (MSC) that shows the same information in an easier to follow form. Update User Guide to reflect these changes as well. Signed-off-by: Bill Fischofer --- /** Email created from pull request 320 (Bill-Fischofer-Linaro:ipsec-doc2) ** https://github.com/Linaro/odp/pull/320 ** Patch: https://github.com/Linaro/odp/pull/320.patch ** Base sha: cf7d38c194f1a9183a524790511de8bfd74a36a9 ** Merge commit sha: 45cab02eabc9950a097a7214082d3cd412ccae73 **/ doc/images/.gitignore | 2 +- doc/images/ipsec_fsm.gv | 32 -------------- doc/images/ipsec_sa_states.msc | 76 ++++++++++++++++++++++++++++++++++ doc/users-guide/Makefile.am | 4 +- doc/users-guide/users-guide-ipsec.adoc | 9 ++-- 5 files changed, 84 insertions(+), 39 deletions(-) delete mode 100644 doc/images/ipsec_fsm.gv create mode 100644 doc/images/ipsec_sa_states.msc diff --git a/doc/images/.gitignore b/doc/images/.gitignore index 0aa34793f..9bcc44f58 100644 --- a/doc/images/.gitignore +++ b/doc/images/.gitignore @@ -1,5 +1,5 @@ resource_management.svg -ipsec_fsm.svg +ipsec_sa_states.svg pktio_fsm.svg timer_fsm.svg timeout_fsm.svg diff --git a/doc/images/ipsec_fsm.gv b/doc/images/ipsec_fsm.gv deleted file mode 100644 index 1e78c8b85..000000000 --- a/doc/images/ipsec_fsm.gv +++ /dev/null @@ -1,32 +0,0 @@ -digraph ipsec_state_machine { - rankdir=LR; - size="12,12"; - node [fontsize=28]; - edge [fontsize=28]; - node [shape=doublecircle]; Unconfigured Configured SA_Ready SA_Expired; - node [shape=circle]; - Unconfigured -> Configured [label="odp_ipsec_config()" - constraint=false]; - Configured -> SA_Ready [label="odp_ipsec_sa_create()"]; - SA_Ready -> Disable_Pending [label="odp_ipsec_sa_disable()"]; - Disable_Pending -> Disable_Check [label="odp_queue_deq()"]; - Disable_Pending -> Disable_Check [label="odp_schedule()"]; - SA_Disabled -> Configured [label="odp_ipsec_sa_destroy()" - constraint=false]; - SA_Ready -> Processing [label="odp_ipsec_in_enq()"]; - SA_Ready -> Processing [label="odp_ipsec_out_enq()"]; - Processing -> Op_Complete [label="odp_queue_deq()"]; - Processing -> Op_Complete [label="odp_schedule()"]; - Op_Complete -> SA_Expired [label="hard limit reached" constraint=false]; - SA_Ready -> SA_Ready [label="odp_ipsec_in()"]; - SA_Ready -> SA_Ready [label="odp_ipsec_out()"]; - SA_Ready -> SA_Ready [label="odp_ipsec_out_inline()"]; - SA_Ready -> SA_Expired [label="hard limit reached"]; - Op_Complete -> SA_Ready [label="odp_ipsec_result()"] - Op_Complete -> SA_Ready [label="odp_ipsec_status()"] - Disable_Check -> SA_Disabled [label="odp_ipsec_status()" - constraint=false]; - Disable_Check -> Disable_Pending [label="odp_ipsec_result()" - constraint=false]; - SA_Expired -> Disable_Pending [label="odp_ipsec_sa_disable()"]; -} diff --git a/doc/images/ipsec_sa_states.msc b/doc/images/ipsec_sa_states.msc new file mode 100644 index 000000000..77de7c2e9 --- /dev/null +++ b/doc/images/ipsec_sa_states.msc @@ -0,0 +1,76 @@ +msc { + + a [label = "Application"], + o [label = "ODP"], + p [label = "Platform"]; + + --- [label = "IPsec configuration, done once"]; + a->o [label = "odp_ipsec_config()"]; + o->p [label = "Config IPsec"]; + o->a [label = "OK"]; + + |||; + --- [label = "IPsec SA creation, per SA"]; + |||; + + a->o [label = "odp_ipsec_sa_create()"]; + o->p [label = "SA Create"]; + o->a [label = "OK"]; + + |||; + --- [label = "IPsec operations, per SA"]; + |||; + + a->o [label = "odp_ipsec_in()"]; + o->p [label = "IPsec Decrypt"]; + p->a [label = "Done"]; + + a->o [label = "odp_ipsec_out()"]; + o->p [label = "IPsec Encrypt"]; + p->a [label = "Done"]; + + a->o [label = "odp_ipsec_out_inline()"]; + o->p [label = "IPsec Encrypt Inline"]; + p->o [label = "OK"]; + o->a [label = "OK"]; + + a->o [label = "odp_ipsec_in_enq()"]; + o->p [label = "Initiate IPsec operation"]; + a->o [label = "odp_ipsec_out_enq()"]; + o->p [label = "Initiate IPsec operation"]; + + |||; + --- [label = "Time passes"]; + |||; + + p->o [label = "IPsec op complete"]; + a->o [label = "odp_schedule()"]; + o->p [label = "Get Event"]; + p->a [label = "ODP_EVENT_PACKET subtype ODP_EVENT_PACKET_IPSEC"]; + a->o [label = "odp_ipsec_result()"]; + o->a [label = "OK"]; + + |||; + --- [label = "App done with SA, per SA"]; + |||; + + a->o [label = "odp_ipsec_sa_disable()"]; + o->p [label = "Disable/Delete SA"]; + o->a [label = "OK"]; + p->o [label = "Done"]; + + |||; + --- [label = "Time passes"]; + |||; + + a->o [label = "odp_schedule()"]; + o->p [label = "Get Event"]; + p->a [label = "ODP_EVENT_IPSEC_STATUS"]; + a->o [label = "odp_ipsec_status"]; + o->a [label = "ODP_IPSEC_STATUS_SA_DISABLED"]; + + a->o [label = "odp_ipsec_sa_destroy()"]; + o->a [label = "OK"]; + + +} \ No newline at end of file diff --git a/doc/users-guide/Makefile.am b/doc/users-guide/Makefile.am index 54f87bb63..27add5e8c 100644 --- a/doc/users-guide/Makefile.am +++ b/doc/users-guide/Makefile.am @@ -11,7 +11,7 @@ SRC = users-guide.adoc \ TARGET = users-guide.html IMAGES = $(IMAGES_DIR)/overview.svg \ $(IMAGES_DIR)/atomic_queue.svg \ - $(IMAGES_DIR)/ipsec_fsm.svg \ + $(IMAGES_DIR)/ipsec_sa_states.svg \ $(IMAGES_DIR)/odp_components.svg \ $(IMAGES_DIR)/ODP-Logo-HQ.svg \ $(IMAGES_DIR)/odp_rx_processing.svg \ @@ -48,7 +48,7 @@ IMAGES += $(IMAGES_DIR)/resource_management.svg endif IMAGES_SRCS = \ - $(IMAGES_DIR)/ipsec_fsm.gv \ + $(IMAGES_DIR)/ipsec_sa_states.gv \ $(IMAGES_DIR)/pktio_fsm.gv \ $(IMAGES_DIR)/resource_management.msc \ $(IMAGES_DIR)/timeout_fsm.gv \ diff --git a/doc/users-guide/users-guide-ipsec.adoc b/doc/users-guide/users-guide-ipsec.adoc index d560df9c4..ac4eae85d 100644 --- a/doc/users-guide/users-guide-ipsec.adoc +++ b/doc/users-guide/users-guide-ipsec.adoc @@ -244,12 +244,13 @@ IPsec operations may produce. This can be changed dynamically by the As can be seen, SAs have a large degree of configurability. ==== SA Lifecycle Management -In discussing the lifecycle of an SA, it is useful to refer to the following -state diagram: +In discussing the lifecycle of an SA and the operations it supports, it is +useful to refer to the following sequence diagram for IPsec configuration, SA +management, and IPsec operations: -image::ipsec_fsm.svg[align="center"] +image:ipsec_sa_states.svg[align="center"] -After creation, IPsec services are active for this Security Association. The +After creation, IPsec services are active for this Security Association. The specific APIs that can be used on this SA depends on the IPsec operating mode that has been configured.