Merge branch 'master' into doug-sts-gov2

Author: Doug-AWS

README.rst

@@ -7,18 +7,21 @@
    This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
    either express or implied. See the License for the specific language governing permissions and
    limitations under the License.
+
 Welcome
 =======
 This is the repository for code examples used in the public 
-`AWS documentation <https://docs.aws.amazon.com>`_. The examples use the AWS SDKs for the supported programming languages. For more information, see `Tools to Build on 
-AWS <https://aws.amazon.com/getting-started/tools-sdks/>`_.
+`AWS documentation <https://docs.aws.amazon.com>`_. The examples use the AWS SDKs for the supported
+programming languages. For more information, see
+`Tools to Build on AWS <https://aws.amazon.com/getting-started/tools-sdks/>`_.
 
 Finding code examples
 =====================
 
-The code examples are organized by programming language. For example, all of the code examples for the V1 version of the
-`AWS SDK for Java Developer Guide <https://www.github.com/awsdocs/aws-java-developer-guide>`_ are
-kept in the `java <java>`_ directory (the V2 versions are in the `java2 <java2>`_ directory).
+The code examples are organized by programming language. For example, all of the code examples for
+the latest version of the `AWS SDK for Java 2.x Developer Guide <https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide>`_
+are kept in the `javav2 <javav2>`_ directory (the version 1.x examples are in the `java <java>`_
+directory).
 
 You can also try using the preview of our `use case index of examples <code-index.md>`_ (and let us
 know what you think about it).
@@ -42,11 +45,11 @@ request <https://github.com/awsdocs/aws-doc-sdk-examples/issues/new?assignees=&l
 The AWS documentation team wants to produce code examples that cover broader scenarios and use 
 cases, versus simple code snippets that cover only individual API calls.
 
-From time to time, the AWS documentation team will select some of these proposals to begin working on.
-To view their decisions, see the `code examples roadmap <https://github.com/awsdocs/aws-doc-sdk-examples/projects/2>`_. 
-If you feel strongly about wanting to accelerate the timeline of a particular proposal or expand or focus the scope of a 
-particular proposal, be sure to +1 the related issue, add comments to it, or both,
-and the team will consider it. 
+From time to time, the AWS documentation team will select some of these proposals to begin working
+on. To view their decisions, see the `code examples roadmap <https://github.com/awsdocs/aws-doc-sdk-examples/projects/2>`_. 
+If you feel strongly about wanting to accelerate the timeline of a particular proposal or expand
+or focus the scope of a particular proposal, be sure to +1 the related issue, add comments to it,
+or both, and the team will consider it. 
 
 The AWS documentation team typically moves accepted proposals in the roadmp from the **Wish List** 
 stage to the **Backlog** stage, then to **In Progress**, and finally to **Recently 
@@ -62,8 +65,9 @@ If you plan to contribute examples for use in the documentation (the purpose of
 read this section carefully so that we can work together effectively. 
 For process instructions and additional guidance, see the `Guidelines for contributing <CONTRIBUTING.md>`_. 
 
-* **Make sure that the code you want to contribute builds and runs**. There's nothing more frustrating in developer
-  documentation than code examples that don't work. Build the code and test it before submitting it!
+* **Make sure that the code you want to contribute builds and runs**. There's nothing more
+  frustrating in developer documentation than code examples that don't work. Build the code and
+  test it before submitting it!
 
 * **Don't include personal account data, keys, or IDs in your examples**. Code should obtain access
   keys from the standard SDK credentials and config files, use environment variables or external
@@ -74,10 +78,10 @@ For process instructions and additional guidance, see the `Guidelines for contri
   unreadable. If your code includes long text strings, consider breaking these into smaller chunks
   and concatenating them.
 
-* **Use short(er) variable names**. To aid in readability and to help keep line length to 80 characters, use
-  *short yet descriptive* names for variables. Do *not* mimic class names when creating
-  variables that represent an object of that class. It nearly always results in excessively long
-  variable names, making it difficult to keep code lines to 80 characters.
+* **Use short(er) variable names**. To aid in readability and to help keep line length to 80
+  characters, use *short yet descriptive* names for variables. Do *not* mimic class names when
+  creating variables that represent an object of that class. It nearly always results in excessively
+  long variable names, making it difficult to keep code lines to 80 characters.
 
 * **Use spaces, not tabs, for indentation**. Tabs are variable length in most editors, but will
   usually render as 8 characters wide in printed documentation. *Always use spaces* to ensure

gov2/kms/CreateKey/CreateKeyv2.go

@@ -0,0 +1,74 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX - License - Identifier: Apache - 2.0
+// snippet-start:[kms-go-v2.CreateKey]
+package main
+
+import (
+    "context"
+    "flag"
+    "fmt"
+
+    "github.com/aws/aws-sdk-go-v2/config"
+    "github.com/aws/aws-sdk-go-v2/service/kms"
+    "github.com/aws/aws-sdk-go-v2/service/kms/types"
+)
+
+// KMSCreateKeyAPI defines the interface for the CreateKey function.
+// We use this interface to test the function using a mocked service.
+type KMSCreateKeyAPI interface {
+    CreateKey(ctx context.Context,
+        params *kms.CreateKeyInput,
+        optFns ...func(*kms.Options)) (*kms.CreateKeyOutput, error)
+}
+
+// MakeKey creates an AWS Key Management Service (AWS KMS) customer master key (CMK).
+// Inputs:
+//     c is the context of the method call, which includes the AWS Region.
+//     api is the interface that defines the method call.
+//     input defines the input arguments to the service call.
+// Output:
+//     If success, a CreateKeyOutput object containing the result of the service call and nil.
+//     Otherwise, nil and an error from the call to CreateKey.
+func MakeKey(c context.Context, api KMSCreateKeyAPI, input *kms.CreateKeyInput) (*kms.CreateKeyOutput, error) {
+    result, err := api.CreateKey(c, input)
+
+    return result, err
+}
+
+func main() {
+    key := flag.String("k", "", "The KMS key name")
+    value := flag.String("v", "", "The value of the KMS key")
+    flag.Parse()
+
+    if *key == "" || *value == "" {
+        fmt.Println("You must supply a KMS key name and value (-k KEY-NAME -v KEY-VALUE)")
+        return
+    }
+
+    cfg, err := config.LoadDefaultConfig()
+    if err != nil {
+        panic("configuration error, " + err.Error())
+    }
+
+    client := kms.NewFromConfig(cfg)
+
+    input := &kms.CreateKeyInput{
+        Tags: []*types.Tag{
+            {
+                TagKey:   key,
+                TagValue: value,
+            },
+        },
+    }
+
+    result, err := MakeKey(context.Background(), client, input)
+    if err != nil {
+        fmt.Println("Got error creating key:")
+        fmt.Println(err)
+        return
+    }
+
+    fmt.Println(*result.KeyMetadata.KeyId)
+}
+
+// snippet-end:[kms-go-v2.CreateKey]

gov2/kms/CreateKey/CreateKeyv2_test.go

@@ -0,0 +1,95 @@
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "errors"
+    "fmt"
+    "io/ioutil"
+    "testing"
+    "time"
+
+    "github.com/aws/aws-sdk-go-v2/service/kms"
+    "github.com/aws/aws-sdk-go-v2/service/kms/types"
+    "github.com/aws/aws-sdk-go/aws"
+)
+
+type KMSCreateKeyImpl struct{}
+
+func (dt KMSCreateKeyImpl) CreateKey(ctx context.Context,
+    params *kms.CreateKeyInput,
+    optFns ...func(*kms.Options)) (*kms.CreateKeyOutput, error) {
+
+    if len(params.Tags) == 0 {
+        return nil, errors.New("You must supply at least one tag value")
+    }
+
+    keyMetadata := &types.KeyMetadata{KeyId: aws.String("aws-docs-example-kmskeyID")}
+
+    output := &kms.CreateKeyOutput{
+        KeyMetadata: keyMetadata,
+    }
+
+    return output, nil
+}
+
+type Config struct {
+    Key   string `json:"Key"`
+    Value string `json:"Value"`
+}
+
+var configFileName = "config.json"
+
+var globalConfig Config
+
+func populateConfiguration(t *testing.T) error {
+    content, err := ioutil.ReadFile(configFileName)
+    if err != nil {
+        return err
+    }
+
+    text := string(content)
+
+    err = json.Unmarshal([]byte(text), &globalConfig)
+    if err != nil {
+        return err
+    }
+
+    if globalConfig.Key == "" || globalConfig.Value == "" {
+        msg := "You must supply a value for Key and Value in " + configFileName
+        return errors.New(msg)
+    }
+
+    return nil
+}
+
+func TestCreateKey(t *testing.T) {
+    thisTime := time.Now()
+    nowString := thisTime.Format("2006-01-02 15:04:05 Monday")
+    t.Log("Starting unit test at " + nowString)
+
+    err := populateConfiguration(t)
+    if err != nil {
+        t.Fatal(err)
+    }
+
+    api := &KMSCreateKeyImpl{}
+
+    input := &kms.CreateKeyInput{
+        Tags: []*types.Tag{
+            {
+                TagKey:   &globalConfig.Key,
+                TagValue: &globalConfig.Value,
+            },
+        },
+    }
+
+    result, err := MakeKey(context.Background(), api, input)
+    if err != nil {
+        fmt.Println("Got error creating key:")
+        fmt.Println(err)
+        return
+    }
+
+    t.Log("KeyID: " + *result.KeyMetadata.KeyId)
+}

gov2/kms/CreateKey/README.md

@@ -0,0 +1,9 @@
+### CreateKeyv2.go
+
+This example creates an AWS Key Management Service (AWS KMS) customer master key (CMK).
+
+`go run CreateKeyv2.go -k KEY -v VALUE`
+
+- _KEY_ is the name of the key to create.
+
+The unit test accepts similar values in _config.json_.

gov2/kms/CreateKey/config.json

@@ -0,0 +1,4 @@
+{
+  "Key": "aws-docs-example-kmskey-key",
+  "Value": "aws-docs-example-kmskey-value"
+}

gov2/kms/DecryptData/DecryptDatav2.go

@@ -0,0 +1,69 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX - License - Identifier: Apache - 2.0
+// snippet-start:[kms.go-v2.DecryptData]
+package main
+
+import (
+    "context"
+    "flag"
+    "fmt"
+
+    "github.com/aws/aws-sdk-go-v2/config"
+    "github.com/aws/aws-sdk-go-v2/service/kms"
+)
+
+// KMSDecryptAPI defines the interface for the Decrypt function.
+// We use this interface to test the function using a mocked service.
+type KMSDecryptAPI interface {
+    Decrypt(ctx context.Context,
+        params *kms.DecryptInput,
+        optFns ...func(*kms.Options)) (*kms.DecryptOutput, error)
+}
+
+// DecodeData decrypts some text that was encrypted with an AWS Key Management Service (AWS KMS) customer master key (CMK).
+// Inputs:
+//     c is the context of the method call, which includes the AWS Region.
+//     api is the interface that defines the method call.
+//     input defines the input arguments to the service call.
+// Output:
+//     If success, a METHODOutput object containing the result of the service call and nil.
+//     Otherwise, nil and an error from the call to Decrypt.
+func DecodeData(c context.Context, api KMSDecryptAPI, input *kms.DecryptInput) (*kms.DecryptOutput, error) {
+    result, err := api.Decrypt(c, input)
+
+    return result, err
+}
+
+func main() {
+    data := flag.String("d", "", "The encrypted data, as a string")
+    flag.Parse()
+
+    if *data == "" {
+        fmt.Println("You must supply the encrypted data as a string")
+        fmt.Println("-d DATA")
+        return
+    }
+
+    cfg, err := config.LoadDefaultConfig()
+    if err != nil {
+        panic("configuration error, " + err.Error())
+    }
+
+    client := kms.NewFromConfig(cfg)
+
+    blob := []byte(*data)
+
+    input := &kms.DecryptInput{
+        CiphertextBlob: blob,
+    }
+
+    result, err := DecodeData(context.Background(), client, input)
+    if err != nil {
+        fmt.Println("Got error decrypting data: ", err)
+        return
+    }
+
+    fmt.Println(string(result.Plaintext))
+}
+
+// snippet-end:[kms.go-v2.DecryptData]