From patchwork Wed Dec 13 01:00:13 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: 121695 Delivered-To: patch@linaro.org Received: by 10.140.22.227 with SMTP id 90csp4836494qgn; Tue, 12 Dec 2017 17:00:54 -0800 (PST) X-Google-Smtp-Source: ACJfBouTEzSyuKj9NIUkMYsX8KCWSyeL//uLZjh6gUjCS1VLYb1Ir027I6GM030UQGP+dbihp9d+ X-Received: by 10.55.175.135 with SMTP id y129mr4135548qke.128.1513126854478; Tue, 12 Dec 2017 17:00:54 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1513126854; cv=none; d=google.com; s=arc-20160816; b=vRsa9jMReH2XsrNJVPITLIwPTjFKf7M3DBYNpVAFfUaSIZamG0lctdK2qOskumG9dT B1f2AeZq/ybkY9vfk7jk7LW0AfY9Qyy2Cw3MNjjmxpaS5Mvabzmz142OshGrmyupSSwV 8pa5eswJxWCPb3E9kS7nbvtlR6ZT43lEs8M6qCj2TKfHjW4rkFAiFvOxIysUi67QslT3 baf1OXiGyolCvM+QWS/mE9iHR7q0UxkS1SGcKGGRMkJHOUnqtdvhrBQ5C4tSpKTCkLvN tCuOyXVLrDKd3i8xt1bk8gtaHeaITIQxKhRYSmcjMEmtCcthL89SL5K/G/xS1No/6nkY m56Q== 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=gzYaadr3ZoReqdD2dgBM8RMciqe+tIKgyu7GMnSacAw=; b=b7Mss9O1ik+pMlTDrNQBP/6Gq6z2seDZadNNOaFAhJ1MAccPCVI/UQKt02CiWKMHhj HZyGoAlmcmiJYlxozwW4URBCG0ql5hm4k/HpLchf6HgpFPyuaqZce8xusr0weNBaJqKW 2zCCtjybKYoDbkGMtYTxe/Dmny/Gr9aH6J0R+NkkJKh8HGwwpDfTc+fsTjO6cxmWKjUo EafrgnOvEHrFvibRZXzAiHtGTsQor94gIKKDkkf2oF06K9It1F7Rt6qD4Hmp73iLxfNe EhUIKjXqkTAJlZr0DdOb0wt4nPjPRJGPwKqD4rIg+bJ/YtWOAZkhDMztXkRwQQjsKr69 zyvA== 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 185si25358qkd.118.2017.12.12.17.00.54; Tue, 12 Dec 2017 17:00:54 -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 2AB1D60922; Wed, 13 Dec 2017 01:00:54 +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 042A2608EE; Wed, 13 Dec 2017 01:00:24 +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 96A51608A4; Wed, 13 Dec 2017 01:00:19 +0000 (UTC) Received: from forward106j.mail.yandex.net (forward106j.mail.yandex.net [5.45.198.249]) by lists.linaro.org (Postfix) with ESMTPS id E95AE60880 for ; Wed, 13 Dec 2017 01:00:16 +0000 (UTC) Received: from mxback8j.mail.yandex.net (mxback8j.mail.yandex.net [IPv6:2a02:6b8:0:1619::111]) by forward106j.mail.yandex.net (Yandex) with ESMTP id 1803B180189F for ; Wed, 13 Dec 2017 04:00:15 +0300 (MSK) Received: from smtp3o.mail.yandex.net (smtp3o.mail.yandex.net [2a02:6b8:0:1a2d::27]) by mxback8j.mail.yandex.net (nwsmtp/Yandex) with ESMTP id l8lhKbyvpZ-0EsCleWA; Wed, 13 Dec 2017 04:00:15 +0300 Received: by smtp3o.mail.yandex.net (nwsmtp/Yandex) with ESMTPSA id CwomK72Xu7-0EeWKdnm; Wed, 13 Dec 2017 04:00:14 +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: Wed, 13 Dec 2017 04:00:13 +0300 Message-Id: <1513126813-30689-2-git-send-email-odpbot@yandex.ru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1513126813-30689-1-git-send-email-odpbot@yandex.ru> References: <1513126813-30689-1-git-send-email-odpbot@yandex.ru> Github-pr-num: 320 Subject: [lng-odp] [PATCH API-NEXT v4 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: d96a8207591fbcaac25b79286d7d72a537354c1f ** Merge commit sha: 958cf8c2adebe816b2e186ee4906b8538cb8f061 **/ 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..7030877e3 --- /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"]; + o->a [label = "OK"]; + p->o [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..b2ebd4d4f 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.msc \ $(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.