From c5df3c23b73489b4cfd296485833ec41f2366307 Mon Sep 17 00:00:00 2001 From: Kyle Mestery Date: Mon, 29 Aug 2022 08:47:47 -0500 Subject: [PATCH 1/2] security: Update README.md This adds more information into the `security/README.md` file detailing what exactly the OPI Security APIs are currently targeting, and the proposed architecture around the IPsec portion of the APIs. I also collapsed the security-spec.md file into the README.md file. Signed-off-by: Kyle Mestery --- security/README.md | 41 +++++++++++++++++++++++++++++++++++++++ security/security-spec.md | 38 ------------------------------------ 2 files changed, 41 insertions(+), 38 deletions(-) delete mode 100644 security/security-spec.md diff --git a/security/README.md b/security/README.md index 4111d5cf..3157e2d3 100644 --- a/security/README.md +++ b/security/README.md @@ -1,5 +1,46 @@ # OPI Security APIs +## Documentation for Reference + +* [strongSwan VICI Protocol](https://www.strongswan.org/apidoc/md_src_libcharon_plugins_vici_README.html) +* [vici API](https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md) +* [govici](https://github.com/strongswan/govici) + +## Terminology + +| Term | Definition | +|-------------------|--------------------------------------------------| +| IKE | Internet Key Exchange is the protocol used to setup security associations in the IPsec suite. | +| ESP | Encapsulating Security Payload provides origin authenticity through source authentication, data integrity through hash functions and confidentiality through encryption protection for IP packets. | + +## Objective + +To define an industry standard "OPI Security Interface" for DPUs and IPUs that +will enable vendors to use the protobuf files from the security API, and expose +those externally and work across a number of orchestration systems. The Storage +solution is one part of a higher-level architecture API defined for DPUs and +IPUs as shown in the following image: + +![OPI Common APIs and SHIM abstraction layer](../doc/images/API-GW-Layers.png/) + +This document focuses specifically on the **OPI Security API Service**, and +even more specifically. currently on the IPsec portion of that API. + +## Architecture + +The OPI Security APIs are currently focusing on implementing an IPsec API which +maps on top of the [strongSwan](https://www.strongswan.org) +[vici Plugin](https://docs.strongswan.org/docs/5.9/plugins/vici.html). For +more details on the vici API, you can look at the strongSwan documentation +found [here](https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md). + +The architecture is seen in the diagram below. + +![OPI IPsec Security Architecture](https://github.com/opiproject/opi-poc/blob/main/security/sec-architecture.drawio.png) + +The idea here is that DPU and IPU vendors will implement strongSwan plugins to +offload the tunnels into hardware. + ## OPI Security API Spec The [Security Spec](security-spec.md) is the best place for up to date information on the OPI diff --git a/security/security-spec.md b/security/security-spec.md deleted file mode 100644 index 7cf3ab12..00000000 --- a/security/security-spec.md +++ /dev/null @@ -1,38 +0,0 @@ -# OPI Security Interface - -Authors: - -* Kyle Mestery (@mestery) -* tbd... - -## Revision - -| Rev | Date | Author | Change Description | -|:----:|:--------------:|:-------------------:|-----------------------------------| -| v0.1 | 07/28/2022 | Kyle Mestery | Initial Draft | - -## Documentation for Reference - -* [strongSwan VICI Protocol](https://www.strongswan.org/apidoc/md_src_libcharon_plugins_vici_README.html) -* [govici](https://github.com/strongswan/govici) - -## Terminology - -| Term | Definition | -|-------------------|--------------------------------------------------| -| IKE | Internet Key Exchange is the protocol used to setup security associations in the IPsec suite. | -| ESP | Encapsulating Security Payload provides origin authenticity through source authentication, data integrity through hash functions and confidentiality through encryption protection for IP packets. | - -## Objective - -To define an industry standard "OPI Security Interface" for DPUs and IPUs that -will enable vendors to use the protobuf files from the security API, and expose -those externally and work across a number of orchestration systems. The Storage -solution is one part of a higher-level architecture API defined for DPUs and -IPUs as shown in the following image: - -![OPI Common APIs and SHIM abstraction layer](../doc/images/API-GW-Layers.png/) - -This document focuses specifically on the **OPI Security API Service**. - -Auto generated [OPI Security API specification](proto/autogen.md) From 369f0ca6b3e018e0ad59a5057af49bd4e367fba9 Mon Sep 17 00:00:00 2001 From: Kyle Mestery Date: Mon, 29 Aug 2022 09:11:49 -0500 Subject: [PATCH 2/2] Address comments from Simon Signed-off-by: Kyle Mestery --- security/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/security/README.md b/security/README.md index 3157e2d3..dde9d9b5 100644 --- a/security/README.md +++ b/security/README.md @@ -3,7 +3,7 @@ ## Documentation for Reference * [strongSwan VICI Protocol](https://www.strongswan.org/apidoc/md_src_libcharon_plugins_vici_README.html) -* [vici API](https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md) +* [vici protocol](https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md) * [govici](https://github.com/strongswan/govici) ## Terminology @@ -31,7 +31,7 @@ even more specifically. currently on the IPsec portion of that API. The OPI Security APIs are currently focusing on implementing an IPsec API which maps on top of the [strongSwan](https://www.strongswan.org) [vici Plugin](https://docs.strongswan.org/docs/5.9/plugins/vici.html). For -more details on the vici API, you can look at the strongSwan documentation +more details on the vici protocol, you can look at the strongSwan documentation found [here](https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md). The architecture is seen in the diagram below.