Prepare for GA release

sdk/attestation/attestation/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Release History
 
-## 1.0.0-beta.5 (Unreleased)
+## 1.0.0 (2021-08-10)
 
 ### Features Added
 

sdk/attestation/attestation/README.md

@@ -43,8 +43,9 @@ npm install @azure/attestation
 
 ### Authenticate the client
 
-In order to interact with the Microsoft Azure Attestation service, you'll need to create an instance of the [Attestation Client][attestation_client] or [Attestation Administration Client][attestation_admin_client] class. You need a **attestation instance url**, which you may see as "DNS Name" in the portal,
-and **client secret credentials (client id, client secret, tenant id)** to instantiate a client object.
+In order to interact with the Microsoft Azure Attestation service, you'll need to create an instance of the [Attestation Client][attestation_client] or [Attestation Administration Client][attestation_admin_client] class. You need a **attestation instance url**, which will either be the  "Attest URI"
+shown in the portal, or will be one of the shared attestation providers.
+You will also need client credentials to use the Attestation Administration Client or call the `attestTpm` API. Client credentials require **(client id, client secret, tenant id)** to instantiate a client object.
 
 In this getting started section, we'll be authenticating using client secret credentials through the [DefaultAzureCredential][defaultazurecredential] provider, but we offer more authentication mechanisms through the [@azure/identity][azure_identity] package. To install the @azure/identity package:
 
@@ -109,7 +110,7 @@ The Microsoft Azure Attestation service runs in two separate modes: "Isolated" a
 provide additional information beyond their authentication credentials to verify that they are authorized to modify the state of an attestation instance.
 
 Finally, each region in which the Microsoft Azure Attestation service is available supports a "shared" instance, which
-can be used to attest SGX enclaves which only need verification against the azure baseline (there are no policies applied to the shared instance). TPM attestation is not available in the shared instance.
+can be used to attest SGX enclaves which only need verification against the azure baseline (there are no policies applied to the shared provider). TPM attestation is not available in the shared provider.
 While the shared instance requires AAD authentication, it does not have any RBAC policies - any customer with a valid AAD bearer token can attest using the shared instance.
 
 ### Attestation
@@ -187,9 +188,8 @@ const client = new AttestationClient(endpoint, {credentials: credentials});
 const attestationSigners = await client.getAttestationSigners();
 ```
 
-If your `endpoint` is one of the shared attestation endpoints, then you do not need
-to provide credentials to access the endpoint. So a shared client can be created
-with:
+If you are not calling the `attestTpm` API, you do not need to provide credentials
+to access the attestation client. This means a client can be created simply with:
 
 ```ts
 const client = new AttestationClient(endpoint);
@@ -250,8 +250,8 @@ const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCre
 const newPolicy = `<New Policy Document>`;
 
 // Set the new attestation policy. Set the policy as an secured policy.
-const privateKey = <Get isolated mode private key from storage>
-const certificate = <Get certificate associated with that private key>
+const privateKey = <Retrieve isolated mode private key from storage>
+const certificate = <Retrieve certificate associated with that private key>
 
 const setPolicyResult = await client.setPolicy(
   KnownAttestationType.OpenEnclave,
@@ -263,13 +263,11 @@ const setPolicyResult = await client.setPolicy(
 );
 ```
 
-Under the covers, the setPolicy APIs create a [JSON Web Token][json_web_token] based on the policy document and signing information which is sent to the attestation service.
+Under the covers, the setPolicy APIs create a [JSON Web Token][json_web_token] containing on the policy document `certificate` and signed with the `privateKey` which is then sent to the attestation service.
 
-Clients need to be able to verify that the attestation policy document was not modified before the policy document was received by the attestation service's enclave.
+If a client wishes to ensure that the attestation policy document was not modified before the policy document was received by the attestation service's enclave, they can use the properties returned in the [PolicyResult][attestation_policy_result] objct which can be used to verify that the service received the policy document:
 
-There are two properties provided in the [PolicyResult][attestation_policy_result] that can be used to verify that the service received the policy document:
-
-- [`policySigner`][attestation_policy_result_parameters] - if the `setPolicy` call included a signing certificate, this will be the certificate provided at the time of the `setPolicy` call. If no policy signer was set, this will be null.
+- [`policySigner`][attestation_policy_result_parameters] - if the `setPolicy` call included a `certificate`, this value will be the certificate provided at the time of the `setPolicy` call. If no policy signer was set, this will be null.
 - [`policyTokenHash`][attestation_policy_result_parameters] - this is the hash of the [JSON Web Signature][json_web_token] sent to the service for the setPolicy API.
 
 To verify the hash, clients can create an attestation policy token (a helper class which represents the token used to set the attestation policy) and verify the hash generated from that token:
@@ -281,16 +279,14 @@ const expectedPolicy = createAttestationPolicyToken(
   certificate);
 
 // Use your favorite SHA256 hash generator function to create a hash of the
-// stringized JWS. The code in this package uses `KJUR.crypto.Util.hashString(buffer, "sha256")`
-// from the `jsrsasign` library, but any crypto library will
-// work.
+// stringized JWS.
 const expectedHash = generateSha256Hash(expectedPolicy.serialize());
 
-// The hash returned in expectedHash will match the value in
+// The hash returned in expectedHash should match the value in
 // `setResult.body.policyTokenHash`.
 ```
 
-### Attest SGX Enclave
+### Attest SGX and Open Enclave
 
 Use the [`attestSgxEnclave`][attest_sgx] method to attest an SGX enclave.
 
@@ -308,10 +304,10 @@ The client can then send that Attestation Token (which contains the serialized k
 
 This example shows one common pattern of calling into the attestation service to retrieve an attestation token associated with a request.
 
-This example assumes that you have an existing `AttestationClient` object which is configured with the base URI for your endpoint. It also assumes that you have an SGX Quote (`quote`) generated from within the SGX enclave you are attesting, and "Runtime Data" (`binaryRuntimeData`) which is referenced in the SGX Quote.
+This example assumes that you have an existing `AttestationClient` object which is configured with the Attest URI for your endpoint. It also assumes that you have an OpenEnclave report (`report`) generated from within the SGX enclave you are attesting, and "Runtime Data" (`binaryRuntimeData`) which is referenced in the SGX Quote.
 
 ```ts
-const attestationResult = await client.attestOpenEnclave(quote, {
+const attestationResult = await client.attestOpenEnclave(report, {
   runTimeData: binaryRuntimeData
 });
 ```
@@ -321,16 +317,27 @@ intended to be interpreted as JSON data. In that case, the client should specify
 the attest API call:
 
 ```ts
-const attestationResult = await client.attestOpenEnclave(quote, {
+const attestationResult = await client.attestOpenEnclave(report, {
   runTimeJson: binaryRuntimeData
 });
 ```
 
+Similarly, if you are using the Intel SDK to generate a "quote", you can validate the quote using:
+
+```ts
+const attestationResult = await client.attestSgxEnclave(quote, {
+  runTimeData: binaryRuntimeData
+});
+```
+
 Additional information on how to perform attestation token validation can be found in the [MAA Service Attestation Sample](https://github.com/Azure-Samples/microsoft-azure-attestation).
 
 ### Retrieve Token Certificates
 
-Use `getSigningCertificates` to retrieve the certificates which can be used to validate the token returned from the attestation service.
+Use `getSigningCertificates` to retrieve the certificates which can be used to
+validate the token returned from the attestation service. Note that this call
+creates a client with azure credentials, that is not needed if you are calling
+the `attestSgxEnclave` or `attestOpenEnclave` APIs
 
 ```ts
 const credentials = new DefaultAzureCredential();
@@ -348,11 +355,9 @@ Most Attestation service operations will raise exceptions defined in [Azure Core
 
 ```ts
 try {
-  await client.attestSgxEnclave(_openEnclaveReport, {
-    runTimeJson: stringToBytes('{"bogus": 10 }')
-  });
+  await client.attestSgxEnclave(openEnclaveReport);
 } catch (error) {
-  console.log(`Expected Exception thrown for invalid request: ${error.message}`);
+  console.log(`Exception thrown for invalid request: ${error.message}`);
 }
 ```
 

sdk/attestation/attestation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/attestation",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0",
   "description": "Javascript/Typescript client implementation for the Microsoft Azure Attestation service.",
   "sdk-type": "client",
   "main": "dist/index.js",

sdk/attestation/attestation/src/constants.ts

@@ -1,4 +1,4 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-export const SDK_VERSION: string = "1.0.0-beta.5";
+export const SDK_VERSION: string = "1.0.0";