From 3bb483b2c34d59194e8a8be94bcc5b697e5175be Mon Sep 17 00:00:00 2001 From: Nuvindu Date: Fri, 1 Dec 2023 09:23:22 +0530 Subject: [PATCH 1/5] [Automated] Update the native jar versions --- ballerina/Ballerina.toml | 6 +++--- ballerina/Dependencies.toml | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/ballerina/Ballerina.toml b/ballerina/Ballerina.toml index b6306cd..719296c 100644 --- a/ballerina/Ballerina.toml +++ b/ballerina/Ballerina.toml @@ -1,7 +1,7 @@ [package] org = "ballerina" name = "soap" -version = "0.9.0" +version = "0.9.1" authors = ["Ballerina"] export=["soap", "soap.soap11", "soap.soap12"] keywords = ["soap"] @@ -19,8 +19,8 @@ graalvmCompatible = true [[platform.java17.dependency]] groupId = "io.ballerina.stdlib" artifactId = "soap-native" -version = "0.9.0" -path = "../native/build/libs/soap-native-0.9.0.jar" +version = "0.9.1" +path = "../native/build/libs/soap-native-0.9.1-SNAPSHOT.jar" [[platform.java17.dependency]] groupId = "org.apache.wss4j" diff --git a/ballerina/Dependencies.toml b/ballerina/Dependencies.toml index 1ed4692..fc5e90a 100644 --- a/ballerina/Dependencies.toml +++ b/ballerina/Dependencies.toml @@ -64,7 +64,7 @@ dependencies = [ [[package]] org = "ballerina" name = "http" -version = "2.10.1" +version = "2.10.4" dependencies = [ {org = "ballerina", name = "auth"}, {org = "ballerina", name = "cache"}, @@ -269,7 +269,7 @@ dependencies = [ [[package]] org = "ballerina" name = "soap" -version = "0.9.0" +version = "0.9.1" dependencies = [ {org = "ballerina", name = "crypto"}, {org = "ballerina", name = "http"}, From 8f530eed8aec035e09cf99c2e2dbbf888ce004c0 Mon Sep 17 00:00:00 2001 From: Nuvindu Date: Fri, 1 Dec 2023 10:31:45 +0530 Subject: [PATCH 2/5] Improve documentation files of the package --- README.md | 99 +++++++++++++++++------------- ballerina/Module.md | 45 +++++++------- ballerina/Package.md | 55 +++++++++-------- ballerina/modules/soap11/Module.md | 53 ++++++++-------- ballerina/modules/soap12/Module.md | 53 ++++++++-------- 5 files changed, 162 insertions(+), 143 deletions(-) diff --git a/README.md b/README.md index 7d4d0d3..17424dd 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -Ballerina SOAP Library -=================== +# Ballerina SOAP Library [![Build](https://github.com/ballerina-platform/module-ballerina-soap/actions/workflows/build-timestamped-master.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-soap/actions/workflows/build-timestamped-master.yml) [![codecov](https://codecov.io/gh/ballerina-platform/module-ballerina-soap/branch/master/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerina-soap) @@ -106,40 +105,40 @@ These policies empower SOAP clients to enhance the security of their web service #### Inbound Security Configurations -- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. - - Fields: - - `int` timeToLive : The time to get expired +- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. + - Fields: + - `int` timeToLive : The time to get expired - `UsernameTokenConfig`: Represents the record for Username Token policy. - - Fields: - - `string` username : The name of the user - - `string` password : The password of the user - - `PasswordType` passwordType : The password type of the username token + - Fields: + - `string` username : The name of the user + - `string` password : The password of the user + - `PasswordType` passwordType : The password type of the username token - `SymmetricBindingConfig`: Represents the record for Symmetric Binding policy. - - Fields: - - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope - - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope - - `string` x509Token : The path or token of the X509 certificate + - Fields: + - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope + - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope + - `string` x509Token : The path or token of the X509 certificate - `AsymmetricBindingConfig`: Represents the record for Username Token with Asymmetric Binding policy. - - Fields: - - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope - - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body - - `string` x509Token : field description + - Fields: + - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope + - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body + - `string` x509Token : field description #### Outbound Security Configurations - `OutboundSecurityConfig`: Represents the record for outbound security configurations to verify and decrypt SOAP envelopes. - - Fields: - - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope - - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope - - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body + - Fields: + - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope + - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope + - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body ### Apply Security Policies @@ -228,54 +227,70 @@ This repository contains only the source code of the package. ### Set up the prerequisites 1. Download and install Java SE Development Kit (JDK) version 17 (from one of the following locations). - * [Oracle](https://www.oracle.com/java/technologies/downloads/) + - [Oracle](https://www.oracle.com/java/technologies/downloads/) - * [OpenJDK](https://adoptium.net/) + - [OpenJDK](https://adoptium.net/) > **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK. 2. Export your Github Personal access token with the read package permissions as follows. - export packageUser= - export packagePAT= + ```bash + export packageUser= + export packagePAT= + ``` ### Build the source Execute the commands below to build from source. 1. To build the library: - ``` + + ```bash ./gradlew clean build ``` 2. To run the integration tests: - ``` + + ```bash ./gradlew clean test ``` + 3. To build the module without the tests: - ``` + + ```bash ./gradlew clean build -x test ``` + 4. To debug module implementation: - ``` + + ```bash ./gradlew clean build -Pdebug= ./gradlew clean test -Pdebug= ``` + 5. To debug the module with Ballerina language: - ``` + + ```bash ./gradlew clean build -PbalJavaDebug= ./gradlew clean test -PbalJavaDebug= ``` + 6. Publish ZIP artifact to the local `.m2` repository: - ``` + + ```bash ./gradlew clean build publishToMavenLocal ``` + 7. Publish the generated artifacts to the local Ballerina central repository: - ``` + + ```bash ./gradlew clean build -PpublishToLocalCentral=true ``` + 8. Publish the generated artifacts to the Ballerina central repository: - ``` + + ```bash ./gradlew clean build -PpublishToCentral=true ``` @@ -291,7 +306,7 @@ All contributors are encouraged to read the [Ballerina Code of Conduct](https:// ## Useful links -* Chat live with us via our [Discord server](https://discord.gg/ballerinalang). -* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag. -* For more information go to the [`soap` library](https://lib.ballerina.io/ballerina/soap/latest). -* For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/swan-lake/learn/by-example/). +- Chat live with us via our [Discord server](https://discord.gg/ballerinalang). +- Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag. +- For more information go to the [`soap` library](https://lib.ballerina.io/ballerina/soap/latest). +- For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/swan-lake/learn/by-example/). diff --git a/ballerina/Module.md b/ballerina/Module.md index 8bd2916..849bb4d 100644 --- a/ballerina/Module.md +++ b/ballerina/Module.md @@ -1,4 +1,4 @@ -## Overview +# Overview This module offers a set of APIs that facilitate the transmission of XML requests to a SOAP backend. It excels in managing security policies within SOAP requests, ensuring the transmission of secured SOAP envelopes. Moreover, it possesses the capability to efficiently extract data from security-applied SOAP responses. @@ -70,6 +70,7 @@ public function main() returns error? { check soapClient->sendOnly(envelope, "http://tempuri.org/Add"); } ``` + ## Security The SOAP client module introduces a robust framework for configuring security measures in SOAP communication. Security is a critical concern when exchanging data via web services, and this module offers comprehensive options to fortify SOAP requests and responses. @@ -96,40 +97,40 @@ These policies empower SOAP clients to enhance the security of their web service #### Inbound Security Configurations -- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. - - Fields: - - `int` timeToLive : The time to get expired +- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. + - Fields: + - `int` timeToLive : The time to get expired - `UsernameTokenConfig`: Represents the record for Username Token policy. - - Fields: + - Fields: - `string` username : The name of the user - `string` password : The password of the user - `PasswordType` passwordType : The password type of the username token - `SymmetricBindingConfig`: Represents the record for Symmetric Binding policy. - - Fields: - - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope - - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope - - `string` x509Token : The path or token of the X509 certificate + - Fields: + - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope + - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope + - `string` x509Token : The path or token of the X509 certificate - `AsymmetricBindingConfig`: Represents the record for Username Token with Asymmetric Binding policy. - - Fields: - - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope - - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body - - `string` x509Token : field description + - Fields: + - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope + - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body + - `string` x509Token : field description #### Outbound Security Configurations - `OutboundSecurityConfig`: Represents the record for outbound security configurations to verify and decrypt SOAP envelopes. - - Fields: - - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope - - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope - - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body + - Fields: + - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope + - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope + - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body ### Apply Security Policies diff --git a/ballerina/Package.md b/ballerina/Package.md index 7eba60f..80e9bec 100644 --- a/ballerina/Package.md +++ b/ballerina/Package.md @@ -1,4 +1,4 @@ -## Package overview +# Package overview This module offers a set of APIs that facilitate the transmission of XML requests to a SOAP backend. It excels in managing security policies within SOAP requests, ensuring the transmission of secured SOAP envelopes. Moreover, it possesses the capability to efficiently extract data from security-applied SOAP responses. @@ -47,7 +47,7 @@ public function main() returns error? { `; - xml|mime:Entity[] response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); + xml response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); } ``` @@ -70,6 +70,7 @@ public function main() returns error? { check soapClient->sendOnly(envelope, "http://tempuri.org/Add"); } ``` + ## Security The SOAP client module introduces a robust framework for configuring security measures in SOAP communication. Security is a critical concern when exchanging data via web services, and this module offers comprehensive options to fortify SOAP requests and responses. @@ -96,46 +97,46 @@ These policies empower SOAP clients to enhance the security of their web service #### Inbound Security Configurations -- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. - - Fields: - - `int` timeToLive : The time to get expired +- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. + - Fields: + - `int` timeToLive : The time to get expired - `UsernameTokenConfig`: Represents the record for Username Token policy. - - Fields: - - `string` username : The name of the user - - `string` password : The password of the user - - `PasswordType` passwordType : The password type of the username token + - Fields: + - `string` username : The name of the user + - `string` password : The password of the user + - `PasswordType` passwordType : The password type of the username token - `SymmetricBindingConfig`: Represents the record for Symmetric Binding policy. - - Fields: - - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope - - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope - - `string` x509Token : The path or token of the X509 certificate + - Fields: + - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope + - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope + - `string` x509Token : The path or token of the X509 certificate - `AsymmetricBindingConfig`: Represents the record for Username Token with Asymmetric Binding policy. - - Fields: - - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope - - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body - - `string` x509Token : field description + - Fields: + - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope + - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body + - `string` x509Token : field description #### Outbound Security Configurations - `OutboundSecurityConfig`: Represents the record for outbound security configurations to verify and decrypt SOAP envelopes. - - Fields: - - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope - - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope - - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body + - Fields: + - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope + - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope + - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body ### Apply Security Policies #### SOAP 1.1 Client: UsernameToken and TranportBinding Policy -``` +```ballerina import ballerina/crypto; import ballerina/mime; import ballerina/soap; diff --git a/ballerina/modules/soap11/Module.md b/ballerina/modules/soap11/Module.md index 22ffc54..9cfbd41 100644 --- a/ballerina/modules/soap11/Module.md +++ b/ballerina/modules/soap11/Module.md @@ -1,4 +1,4 @@ -## Overview +# Overview This module offers a set of APIs that facilitate the transmission of XML requests to a SOAP 1.1 backend. It excels in managing security policies within SOAP requests, ensuring the transmission of secured SOAP envelopes. Moreover, it possesses the capability to efficiently extract data from security-applied SOAP responses. @@ -39,7 +39,7 @@ public function main() returns error? { `; - xml|mime:Entity[] response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); + xml response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); } ``` @@ -62,6 +62,7 @@ public function main() returns error? { check soapClient->sendOnly(envelope, "http://tempuri.org/Add"); } ``` + ## Security The SOAP client module introduces a robust framework for configuring security measures in SOAP communication. Security is a critical concern when exchanging data via web services, and this module offers comprehensive options to fortify SOAP requests and responses. @@ -88,40 +89,40 @@ These policies empower SOAP clients to enhance the security of their web service #### Inbound Security Configurations -- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. - - Fields: - - `int` timeToLive : The time to get expired +- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. + - Fields: + - `int` timeToLive : The time to get expired - `UsernameTokenConfig`: Represents the record for Username Token policy. - - Fields: - - `string` username : The name of the user - - `string` password : The password of the user - - `PasswordType` passwordType : The password type of the username token + - Fields: + - `string` username : The name of the user + - `string` password : The password of the user + - `PasswordType` passwordType : The password type of the username token - `SymmetricBindingConfig`: Represents the record for Symmetric Binding policy. - - Fields: - - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope - - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope - - `string` x509Token : The path or token of the X509 certificate + - Fields: + - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope + - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope + - `string` x509Token : The path or token of the X509 certificate - `AsymmetricBindingConfig`: Represents the record for Username Token with Asymmetric Binding policy. - - Fields: - - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope - - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body - - `string` x509Token : field description + - Fields: + - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope + - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body + - `string` x509Token : field description #### Outbound Security Configurations - `OutboundSecurityConfig`: Represents the record for outbound security configurations to verify and decrypt SOAP envelopes. - - Fields: - - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope - - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope - - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body + - Fields: + - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope + - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope + - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body ### Apply Security Policies diff --git a/ballerina/modules/soap12/Module.md b/ballerina/modules/soap12/Module.md index e3b4388..b48be89 100644 --- a/ballerina/modules/soap12/Module.md +++ b/ballerina/modules/soap12/Module.md @@ -1,4 +1,4 @@ -## Overview +# Overview This module offers a set of APIs that facilitate the transmission of XML requests to a SOAP 1.2 backend. It excels in managing security policies within SOAP requests, ensuring the transmission of secured SOAP envelopes. Moreover, it possesses the capability to efficiently extract data from security-applied SOAP responses. @@ -39,7 +39,7 @@ public function main() returns error? { `; - xml|mime:Entity[] response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); + xml response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); } ``` @@ -62,6 +62,7 @@ public function main() returns error? { check soapClient->sendOnly(envelope, "http://tempuri.org/Add"); } ``` + ## Security The SOAP client module introduces a robust framework for configuring security measures in SOAP communication. Security is a critical concern when exchanging data via web services, and this module offers comprehensive options to fortify SOAP requests and responses. @@ -88,40 +89,40 @@ These policies empower SOAP clients to enhance the security of their web service #### Inbound Security Configurations -- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. - - Fields: - - `int` timeToLive : The time to get expired +- `TimestampTokenConfig`: Represents the record for Timestamp Token policy. + - Fields: + - `int` timeToLive : The time to get expired - `UsernameTokenConfig`: Represents the record for Username Token policy. - - Fields: - - `string` username : The name of the user - - `string` password : The password of the user - - `PasswordType` passwordType : The password type of the username token + - Fields: + - `string` username : The name of the user + - `string` password : The password of the user + - `PasswordType` passwordType : The password type of the username token - `SymmetricBindingConfig`: Represents the record for Symmetric Binding policy. - - Fields: - - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope - - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope - - `string` x509Token : The path or token of the X509 certificate + - Fields: + - `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope + - `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope + - `string` x509Token : The path or token of the X509 certificate - `AsymmetricBindingConfig`: Represents the record for Username Token with Asymmetric Binding policy. - - Fields: - - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope - - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope - - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body - - `string` x509Token : field description + - Fields: + - `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope + - `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + - `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body + - `string` x509Token : field description #### Outbound Security Configurations - `OutboundSecurityConfig`: Represents the record for outbound security configurations to verify and decrypt SOAP envelopes. - - Fields: - - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope - - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope - - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope - - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body + - Fields: + - `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope + - `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope + - `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope + - `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body ### Apply Security Policies From f53d7b70babd582a6f3d5cba5273c73e50bd888b Mon Sep 17 00:00:00 2001 From: Nuvindu Date: Fri, 1 Dec 2023 10:33:06 +0530 Subject: [PATCH 3/5] Fix assigning types for variables in test cases --- ballerina/modules/soap12/tests/soap12_client_test.bal | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ballerina/modules/soap12/tests/soap12_client_test.bal b/ballerina/modules/soap12/tests/soap12_client_test.bal index 331848f..057f1b8 100644 --- a/ballerina/modules/soap12/tests/soap12_client_test.bal +++ b/ballerina/modules/soap12/tests/soap12_client_test.bal @@ -517,7 +517,7 @@ function testSoapReceiveWithSymmetricBindingAndOutboundConfig() returns error? { } ); xml body = xml `23`; - xml|mime:Entity[] response = check soapClient->sendReceive(body, "http://tempuri.org/Add", path = "/getSamePayload"); + xml response = check soapClient->sendReceive(body, "http://tempuri.org/Add", path = "/getSamePayload"); return soap:assertSymmetricBinding(response.toString(), string `23`); } @@ -543,7 +543,7 @@ function testSendReceiveWithAsymmetricBindingAndOutboundConfig() returns error? ); xml body = xml `23`; - xml|mime:Entity[] response = check soapClient->sendReceive(body, "http://tempuri.org/Add", path = "/getSecuredPayload"); + xml response = check soapClient->sendReceive(body, "http://tempuri.org/Add", path = "/getSecuredPayload"); return soap:assertSymmetricBinding(response.toString(), string `23`); } From 93e1340b9f8d9f8403e4a4cf268060e31700fa01 Mon Sep 17 00:00:00 2001 From: Nuvindu Date: Fri, 1 Dec 2023 10:33:23 +0530 Subject: [PATCH 4/5] Improve the Ballerina SOAP specification --- docs/spec/spec.md | 398 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 354 insertions(+), 44 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index e7469af..d888bb6 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -1,17 +1,18 @@ -# Specification: Ballerina Soap Library +# Specification: Ballerina SOAP Library _Owners_: @shafreenAnfar @MadhukaHarith92 _Reviewers_: @shafreenAnfar _Created_: 2023/06/07 -_Updated_: 2023/08/14 +_Updated_: 2023/12/01 _Edition_: Swan Lake ## Introduction -This is the specification for the Soap standard library of [Ballerina language](https://ballerina.io/), which provides APIs to send an ordinary XML request to a SOAP backend by specifying the necessary details to construct a SOAP envelope. -The Soap library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag. +This is the specification for the SOAP standard library of [Ballerina language](https://ballerina.io/), which provides APIs to send an ordinary XML request to a SOAP backend by specifying the necessary details to construct a SOAP envelope. -If you have any feedback or suggestions about the library, start a discussion via a [GitHub issue](https://github.com/ballerina-platform/ballerina-standard-library/issues) or in the [Discord server](https://discord.gg/ballerinalang). Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under `/docs/proposals`. Proposals under discussion can be found with the label `type/proposal` in GitHub. +The SOAP library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag. + +If you have any feedback or suggestions about the library, start a discussion via a [GitHub issue](https://github.com/ballerina-platform/ballerina-library/issues) or in the [Discord server](https://discord.gg/ballerinalang). Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under `/docs/proposals`. Proposals under discussion can be found with the label `type/proposal` in GitHub. The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug. @@ -19,86 +20,395 @@ The conforming implementation of the specification is released and included in t 1. [Overview](#1-overview) 2. [Components](#2-components) - * 2.1 [Client](#21-client) - * 2.1.1 [Initializing the Client](#211-initializing-the-client) - * 2.1.2 [SendReceive](#211-sendreceive) - * 2.1.3 [SendOnly](#213-sendonly) -3. [Supported SOAP Versions](#3-supported-soap-versions) + * 2.1 [Client](#21-client) + * 2.2 [Supported APIs](#22-supported-apis) + * 2.2.1 [Send & Receive](#221-send--receive) + * 2.2.2 [Send Only](#222-send-only) + * 2.2.3 [Examples](#223-examples) + * 2.2.3.1 [`sendReceive()` with SOAP 1.1](#2231-sendreceive-with-soap-11) + * 2.2.3.2 [`sendReceive()` with SOAP 1.2](#2232-sendreceive-with-soap-12) + * 2.2.3.3 [`sendOnly()` with SOAP 1.1](#2233-sendonly-with-soap-11) + * 2.2.3.4 [`sendOnly()` with SOAP 1.2](#2234-sendonly-with-soap-12) + * 2.3 [Response Types](#23-response-types) + * 2.3.1 [`xml`](#231-xml) + * 2.3.2 [`mime:Entity[]`](#232-mimeentity) + * 2.3.3 [Examples](#233-examples) +3. [Security](#3-security) + * 3.1 [Policies](#31-policies) + * 3.2 [Security Policy Configuration Types](#32-security-policy-configuration-types) + * 3.2.1 [Inbound Security Configurations](#321-inbound-security-configurations) + * 3.2.2 [Outbound Security Configurations](#322-outbound-security-configurations) + * 3.3 [Configure Security Policies](#33-configure-security-policies) + * [UsernameToken and TranportBinding Policy with SOAP 1.1 Client](#331-usernametoken-and-tranportbinding-policy-with-soap-11-client) + * [Asymmetric Binding and Outbound Security Configuration with SOAP 1.2 Client](#332-asymmetric-binding-and-outbound-security-configuration-with-soap-12-client) ## 1. Overview -This specification elaborates on the functions available in the Soap library. + +This specification elaborates on the functions available in the SOAP library. The soap module abstracts out the details of the creation of a SOAP envelope, headers, and the body in a SOAP message. ## 2. Components -This section describes the components of the Ballerina SOAP package. To use the Ballerina SOAP package, a user must import the Ballerina SOAP package first. + +This section describes the components of the Ballerina SOAP package. To use the Ballerina SOAP package, a user must import one of the following sub modules of the Ballerina SOAP package first. + +* Importing SOAP 1.1 Module + + ```ballerina + import ballerina/soap.soap11; + ``` + +* Importing SOAP 1.2 Module + + ```ballerina + import ballerina/soap.soap12; + ``` + +## 2.1 Client + +The `Client` is used to connect to and interact with SOAP endpoints. + +> **_NOTE:_** +The SOAP module supports SOAP 1.1 and 1.2 versions. Users can specify the SOAP version when importing the SOAP package. In the SOAP package there are sub modules as `soap11` and `soap12` to support SOAP 1.1 and SOAP 1.2 in that order. + +### 2.1.1 SOAP 1.1 Client + ```ballerina -import ballerina/soap; +import ballerina/soap.soap11; + +soap11:Client soapClient = check new ("http://www.dneonline.com/calculator.asmx?WSDL"); +``` + +### 2.1.2 SOAP 1.2 Client + +```ballerina +import ballerina/soap.soap12; + +soap12:Client soapClient = check new ("http://www.dneonline.com/calculator.asmx?WSDL"); ``` -### 2.1 Client +## 2.2 Supported APIs -The SOAP client can be used to connect to a SOAP service and retrieve data. +This section outlines the APIs supported by the Ballerina SOAP library, providing an overview of their functionalities. -#### 2.1.1 Initializing the Client +### 2.2.1 Send & Receive -The `soap:Client` `init` method requires a valid URL and optional configuration to initialize the client. +The `sendReceive()` API provides a mechanism to send SOAP requests to a specified endpoint and receive a relevant response. This is a synchronous operation where the client sends a SOAP request and waits for the service to process the request and return a response. This API is suitable for scenarios where the client requires both sending a request and receiving the associated response to proceed with further actions. -#### 2.1.2 SendReceive +### 2.2.2 Send Only -The `sendReceive` function sends SOAP request and expects a response. +The `sendOnly()` API is designed for scenarios where the client needs to send a SOAP request but does not require or expect a response from the service. Here, it follows the "fire and forget" approach, where the client sends a SOAP request to the service without waiting for or processing any response. This API is useful when the client is only interested in triggering a specific action on the service side without needing the result. + +The SOAP 1.1 specification requires the inclusion of the `action` parameter as a mandatory component within its APIs. In contrast, SOAP 1.2 relaxes this requirement, making the action parameter optional. + +### 2.2.3 Examples + +Following examples provideds practical use cases for both `sendReceive()` and `sendOnly()` APIs. + +#### 2.2.3.1 `sendReceive()` with SOAP 1.1 + +```ballerina +import ballerina/soap.soap11; + +public function main() returns error? { + soap11:Client soapClient = check new ("http://www.dneonline.com/calculator.asmx?WSDL"); + + xml envelope = xml ` + + + 2 + 3 + + + `; + xml response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); +} +``` + +#### 2.2.3.2 `sendReceive()` with SOAP 1.2 ```ballerina import ballerina/io; -import ballerina/soap; -import ballerina/mime; +import ballerina/soap.soap12; public function main () returns error? { + soap12:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl"); - soap:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl"); + xml envelope = xml ` + + + 18006785432 + 0 + + + `; + xml response = check soapClient->sendReceive(envelope); + io:println(response); +} +``` - xml body = xml ` - 18006785432 - 0 - `; +#### 2.2.3.3 `sendOnly()` with SOAP 1.1 - xml|mime:Entity[] response = check soapClient->sendReceive(body); - io:println(response); +```ballerina +import ballerina/soap.soap11; + +public function main() returns error? { + soap11:Client soapClient = check new ("http://www.dneonline.com/calculator.asmx?WSDL"); + + xml envelope = xml ` + + + 2 + 3 + + + `; + check soapClient->sendOnly(envelope, "http://tempuri.org/Add"); +} +``` + +#### 2.2.3.4 `sendOnly()` with SOAP 1.2 + +```ballerina +import ballerina/io; +import ballerina/soap.soap12; + +public function main () returns error? { + soap12:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl"); + + xml body = xml ` + + + 18006785432 + 0 + + + `; + check soapClient->sendOnly(body); } ``` -#### 2.1.3 SendOnly +## 2.3 Response Types + +Responses of the SOAP APIs supports either `xml` or `mime:Entity[]` types. Since these APIs supports type inference, either type can be assign to the variables as a single type instead of a union type of `xml` and `mime:Entity[]`. -The `sendOnly` function fires and forgets requests. It sends the request without the possibility of any response from the service (even an error). +### 2.3.1 `xml` + +The `xml` type is the common return type for SOAP responses. When a SOAP request is made using either the `sendReceive()` API, the response is typically in `xml` format. The `xml` type captures this response, allowing users to work with and manipulate the `xml` data received from the SOAP service. + +### 2.3.2 `mime:Entity[]` + +The `mime:Entity[]` type represents the return type for SOAP endpoints that support multimedia types in responses. In scenarios where SOAP services return multimedia content, such as images or files, the response is represented as an array of MIME entities (`mime:Entity[]`). This allows users to handle and process multimedia data received from SOAP services. + +### 2.3.3 Examples + +The following examples provides details on handling SOAP responses with different types (xml and mime:Entity[]). + +#### 2.3.3.1 Send & Receive with `xml` Response ```ballerina import ballerina/io; -import ballerina/soap; -import ballerina/mime; +import ballerina/soap.soap12; public function main () returns error? { + soap12:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl"); - soap:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl"); + xml envelope = xml ` + + + 18006785432 + 0 + + + `; + xml response = check soapClient->sendReceive(envelope); + io:println(response); +} +``` - xml body = xml ` - 18006785432 - 0 - `; +#### 2.3.3.2 Send & Receive with `mime:Entity[]` Response - check soapClient->sendOnly(body); +```ballerina +import ballerina/io; +import ballerina/soap.mime; +import ballerina/soap.soap12; + +public function main () returns error? { + soap12:Client soapClient = check new ("http://soap-endpoint-url"); + xml body = xml ` + + + 2 + 3 + + + `; + + mime:Entity[] mtomMessage = []; + mime:Entity envelope = new; + check envelope.setContentType("application/xop+xml"); + envelope.setContentId(""); + envelope.setBody(body); + mtomMessage.push(envelope); + + mime:Entity bytesPart = new; + string readContent = check io:fileReadString(FILE_PATH); + bytesPart.setFileAsEntityBody(FILE_PATH); + string|byte[]|io:ReadableByteChannel|mime:EncodeError bytes = mime:base64Encode(readContent.toBytes()); + if bytes !is byte[] { + return error("Encoded characters are not in the correct format"); + } + bytesPart.setBody(bytes); + check bytesPart.setContentType("image/jpeg"); + bytesPart.setContentId(""); + mtomMessage.push(bytesPart); + + mime:Entity[] response = check soapClient->sendReceive(mtomMessage, "http://tempuri.org/Add"); } ``` -## 3. Supported SOAP Versions +## 3. Security + +The SOAP client module introduces a robust framework for configuring security measures in SOAP communication. Security is a critical concern when exchanging data via web services, and this module offers comprehensive options to fortify SOAP requests and responses. + +There are two primary security configurations available for SOAP clients: + +* `inboundSecurity`: This configuration is applied to the SOAP envelope when a request is made. It includes various ws security policies such as Username Token, Timestamp Token, X509 Token, Symmetric Binding, Asymmetric Binding, and Transport Binding, either individually or in combination with each other. + +* `outboundSecurity`: This configuration is applied to the SOAP envelope when a response is received. Its purpose is to decrypt the data within the envelope and verify the digital signature for security validation. + +### 3.1 Policies + +This library currently supports the following WS Security policies: -The soap module supports SOAP 1.1 and 1.2 versions. By default, the soap client is configured to work with SOAP 1.1. Users can overwrite this to support SOAP 1.2 by passing `soapVersion` -parameter during client initialization. +* **Username Token**: Provides authentication through username and password credentials. +* **Timestamp Token**: Enhances message integrity by incorporating timestamp information. +* **X509 Token**: Allows the use of X.509 certificates for secure communication. +* **Symmetric Binding**: Enables symmetric key-based security mechanisms. +* **Asymmetric Binding**: Facilitates the use of asymmetric cryptography for enhanced security. + +These policies empower SOAP clients to enhance the security of their web service communications by selecting and implementing the appropriate security mechanisms to safeguard their SOAP envelopes. + +### 3.2 Security Policy Configuration Types + +This subsection introduces the configuration types for inbound and outbound security, providing detailed information on each type. + +#### 3.2.1 Inbound Security Configurations + +* `TimestampTokenConfig`: Represents the record for Timestamp Token policy. + * Fields: + * `int` timeToLive : The time to get expired + +* `UsernameTokenConfig`: Represents the record for Username Token policy. + * Fields: + * `string` username : The name of the user + * `string` password : The password of the user + * `PasswordType` passwordType : The password type of the username token + +* `SymmetricBindingConfig`: Represents the record for Symmetric Binding policy. + * Fields: + * `crypto:PrivateKey` symmetricKey : The key to sign and encrypt the SOAP envelope + * `crypto:PublicKey` servicePublicKey : The key to encrypt the symmetric key + * `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + * `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP envelope + * `string` x509Token : The path or token of the X509 certificate + +* `AsymmetricBindingConfig`: Represents the record for Username Token with Asymmetric Binding policy. + * Fields: + * `crypto:PrivateKey` signatureKey : The private key to sign the SOAP envelope + * `crypto:PublicKey` encryptionKey : The public key to encrypt the SOAP body + * `SignatureAlgorithm` signatureAlgorithm : The algorithm to sign the SOAP envelope + * `EncryptionAlgorithm` encryptionAlgorithm : The algorithm to encrypt the SOAP body + * `string` x509Token : field description + +#### 3.2.2 Outbound Security Configurations + +* `OutboundSecurityConfig`: Represents the record for outbound security configurations to verify and decrypt SOAP envelopes. + * Fields: + * `crypto:PublicKey` verificationKey : The public key to verify the signature of the SOAP envelope + * `crypto:PrivateKey`|`crypto:PublicKey` decryptionKey : The private key to decrypt the SOAP envelope + * `SignatureAlgorithm` signatureAlgorithm : The algorithm to verify the SOAP envelope + * `EncryptionAlgorithm` decryptionAlgorithm : The algorithm to decrypt the SOAP body + +### 3.3 Configure Security Policies + +The following examples shows on configuring security policies for SOAP clients, covering scenarios like Username Token with Transport Binding and Asymmetric Binding with SOAP 1.2 clients. + +#### 3.3.1 UsernameToken and TranportBinding Policy with SOAP 1.1 Client ```ballerina +import ballerina/crypto; import ballerina/soap; - -public function main () returns error? { +import ballerina/soap.soap11; + +public function main() returns error? { + soap11:Client soapClient = check new ("https://www.secured-soap-endpoint.com", + { + inboundSecurity: [ + { + username: "username", + password: "password", + passwordType: soap:TEXT + }, + TRANSPORT_BINDING + ] + }); + + xml envelope = xml ` + + + 2 + 3 + + + `; + xml response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); +} +``` + +#### 3.3.2 Asymmetric Binding and Outbound Security Configuration with SOAP 1.2 Client + +```ballerina +import ballerina/crypto; +import ballerina/soap; +import ballerina/soap.soap12; + +public function main() returns error? { + configurable crypto:PrivateKey clientPrivateKey = ?; + configurable crypto:PublicKey clientPublicKey = ?; + configurable ​crypto:PublicKey serverPublicKey = ?; - soap:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl", soapVersion = SOAP12); + soap12:Client soapClient = check new ("https://www.secured-soap-endpoint.com", + { + inboundSecurity: { + signatureAlgorithm: soap:RSA_SHA256, + encryptionAlgorithm: soap:RSA_ECB, + signatureKey: clientPrivateKey, + encryptionKey: serverPublicKey, + }, + outboundSecurity: { + verificationKey: serverPublicKey, + signatureAlgorithm: soap:RSA_SHA256, + decryptionKey: clientPrivateKey, + decryptionAlgorithm: soap:RSA_ECB + } + }); + xml envelope = xml ` + + + 2 + 3 + + + `; + xml response = check soapClient->sendReceive(envelope, "http://tempuri.org/Add"); } ``` From 0582c3eb0e040ac6129a04c88fb6b873ee97c791 Mon Sep 17 00:00:00 2001 From: Nuvindu Date: Wed, 6 Dec 2023 14:30:16 +0530 Subject: [PATCH 5/5] Apply suggestions from the review --- docs/spec/spec.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index d888bb6..90c4d4b 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -1,18 +1,18 @@ # Specification: Ballerina SOAP Library -_Owners_: @shafreenAnfar @MadhukaHarith92 -_Reviewers_: @shafreenAnfar -_Created_: 2023/06/07 -_Updated_: 2023/12/01 +_Owners_: @shafreenAnfar @MadhukaHarith92 @Nuvindu \ +_Reviewers_: @shafreenAnfar \ +_Created_: 2023/06/07 \ +_Updated_: 2023/12/01 \ _Edition_: Swan Lake ## Introduction -This is the specification for the SOAP standard library of [Ballerina language](https://ballerina.io/), which provides APIs to send an ordinary XML request to a SOAP backend by specifying the necessary details to construct a SOAP envelope. +This is the specification for the SOAP package of [Ballerina language](https://ballerina.io/), which provides APIs to send an ordinary XML request to a SOAP backend by specifying the necessary details to construct a SOAP envelope. -The SOAP library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag. +The SOAP package specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag. -If you have any feedback or suggestions about the library, start a discussion via a [GitHub issue](https://github.com/ballerina-platform/ballerina-library/issues) or in the [Discord server](https://discord.gg/ballerinalang). Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under `/docs/proposals`. Proposals under discussion can be found with the label `type/proposal` in GitHub. +If you have any feedback or suggestions about the package, start a discussion via a [GitHub issue](https://github.com/ballerina-platform/ballerina-library/issues) or in the [Discord server](https://discord.gg/ballerinalang). Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under `/docs/proposals`. Proposals under discussion can be found with the label `type/proposal` in GitHub. The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug. @@ -44,7 +44,7 @@ The conforming implementation of the specification is released and included in t ## 1. Overview -This specification elaborates on the functions available in the SOAP library. +This specification elaborates on the functions available in the SOAP package. The soap module abstracts out the details of the creation of a SOAP envelope, headers, and the body in a SOAP message. @@ -89,7 +89,7 @@ soap12:Client soapClient = check new ("http://www.dneonline.com/calculator.asmx? ## 2.2 Supported APIs -This section outlines the APIs supported by the Ballerina SOAP library, providing an overview of their functionalities. +This section outlines the APIs supported by the Ballerina SOAP package, providing an overview of their functionalities. ### 2.2.1 Send & Receive @@ -285,7 +285,7 @@ There are two primary security configurations available for SOAP clients: ### 3.1 Policies -This library currently supports the following WS Security policies: +This package currently supports the following WS Security policies: * **Username Token**: Provides authentication through username and password credentials. * **Timestamp Token**: Enhances message integrity by incorporating timestamp information.