docs: add API usage examples templates #179
Conversation
| # In this example, we use an AWS KMS customer master key (CMK), | ||
| # but you can use other key management options with the AWS Encryption SDK. | ||
| # For examples that demonstrate how to use other key management configurations, | ||
| # see the ``keyring`` and ``master_key_provider`` directories. |
There was a problem hiding this comment.
Do we have these directories in the spec/will we? If not, should we link to something else here?
This applies to this doc page and others in this PR.
There was a problem hiding this comment.
Also, for master_key_provider not all implementations support this.
We may want to try and remove it?
| - **source plaintext** : | ||
| Plaintext to encrypt | ||
| - **AWS KMS CMK** : | ||
| The ARN of an AWS KMS CMK that protects data keys |
There was a problem hiding this comment.
Might be good to link to AWS docs (for ARN)? Either way, might also be good to note if this can be an alias ARN.
There was a problem hiding this comment.
Or a link to the KMS examples?
We don't want any given example
to be so complete that it tries to explain everything.
| # Changing the algorithm suite example | ||
|
|
||
| Implementations of this example MUST follow the rules defined in | ||
| [Example Templates](../../../examples.md#example-templates). |
There was a problem hiding this comment.
This applies here and in other documents in this PR.
I think this path isn't resolving properly.
There was a problem hiding this comment.
I think these might just need to be
[Example Templates](../../examples.md#example-templates).
There was a problem hiding this comment.
doh; that is correct; I copy-pasted that from the raw keyring examples and they have at least one extra directory layer x_x
| # In this example, we use an AWS KMS customer master key (CMK), | ||
| # but you can use other key management options with the AWS Encryption SDK. | ||
| # For examples that demonstrate how to use other key management configurations, | ||
| # see the ``keyring`` and ``master_key_provider`` directories. |
There was a problem hiding this comment.
Also, for master_key_provider not all implementations support this.
We may want to try and remove it?
| # For examples that demonstrate how to use other key management configurations, | ||
| # see the ``keyring`` and ``master_key_provider`` directories. | ||
| # | ||
| # The default algorithm suite includes a message-level signature |
There was a problem hiding this comment.
If the "default algorithm suite" ever changes, how are we going to find all these places to update them?
| - **source plaintext** : | ||
| Plaintext to encrypt | ||
| - **AWS KMS CMK** : | ||
| The ARN of an AWS KMS CMK that protects data keys |
There was a problem hiding this comment.
Or a link to the KMS examples?
We don't want any given example
to be so complete that it tries to explain everything.
| 1. Decrypt encrypted data. | ||
|
|
||
| ```python | ||
| # Decrypt your encrypted data using the same keyring you used on encrypt. |
There was a problem hiding this comment.
Some of this language is getting copy/paste.
Not a blocker, but in the long run, some more tokenization may be in order.
|
|
||
| ```python | ||
| # Open the files you want to work with. | ||
| with open(source_plaintext_filename, "rb") as plaintext, open(ciphertext_filename, "wb") as ciphertext: |
There was a problem hiding this comment.
Yup, I think that this is so language specific,
that maybe nothing is better?
(in the long run :) no need to block )
| ## Header | ||
|
|
||
| ```python | ||
| # This example shows how to use the streaming encrypt and decrypt APIs on data in memory. |
There was a problem hiding this comment.
I like the idea here,
but maybe a little more complicated example?
Like why are we doing this?
Is the idea like a proxy where
you take a network socket and decrypt
it on the fly and send it to some back end server?
acioc
modified the milestones:
Spec 1.0 (Official Keyring Release),
Spec 1.0 Implementation (Official Keyring Release)
Issue #, if available:
#143
Description of changes:
NOTE: The specific Python code in these templates will change before keyrings are released. I suggest that either we hold this in limbo until those changes are finalized or we update the code in the template when we come back to update links from the keyring branch to the master branch.
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.