docs: client sample docs update (#219)

Sita04 · sitalakshmis · gcf-owl-bot[bot] · Sita04 · commit fdf198f08b99 · 2023-01-18T04:58:08.000+05:30
* docs: update comments * docs: update comments * (docs): Adding README.md * 🦉 Updates from OwlBot See https://github.com/googleapis/repo-automation-bots/blob/master/packages/owl-bot/README.md * docs: updated README.md * refactor: replaced POOL_NAME with POOL_ID to align with cloud docs. * docs: lint fix * 🦉 Updates from OwlBot See https://github.com/googleapis/repo-automation-bots/blob/master/packages/owl-bot/README.md Co-authored-by: sitalakshmis <79585041+sitalakshmis@users.noreply.github.com> Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
diff --git a/privateca/cloud-client/README.md b/privateca/cloud-client/README.md
@@ -0,0 +1,75 @@
+# Google Cloud Private Certificate Authority Service
+
+<a href="https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-security-private-ca&page=editor&open_in_editor=samples/snippets/cloud-client/README.md">
+<img alt="Open in Cloud Shell" src ="http://gstatic.com/cloudssh/images/open-btn.png"></a>
+
+Google [Cloud Private Certificate Authority Service](https://cloud.google.com/certificate-authority-service) is a highly available, scalable Google Cloud service that enables you to simplify, automate, and customize the deployment, management, and security of private certificate authorities (CA).
+
+These sample Java applications demonstrate how to access the Cloud CA API using the
+Google Java API Client Libraries.
+
+## Prerequisites
+
+### Google Cloud Project
+
+Set up a Google Cloud project with billing enabled.
+
+### Enable the API
+
+You must [enable the Google Private Certificate Authority Service API](https://console.cloud.google.com/flows/enableapi?apiid=privateca.googleapis.com) for your project in order to use these samples.
+
+### Service account
+
+A service account with private key credentials is required to create signed bearer tokens.
+Create a [service account](https://console.cloud.google.com/iam-admin/serviceaccounts/create) and download the credentials file as JSON.
+
+### Set Environment Variables
+
+You must set your project ID and service account credentials in order to run the tests.
+
+```
+$ export GOOGLE_CLOUD_PROJECT="<google-project-id-here>"
+$ export GOOGLE_APPLICATION_CREDENTIALS="<path-to-service-account-credentials-file>"
+```
+
+### Grant Permissions
+
+You must ensure that the [user account or service account](https://cloud.google.com/iam/docs/service-accounts#differences_between_a_service_account_and_a_user_account) you used to authorize your gcloud session has the proper permissions to edit Private CA resources for your project. In the Cloud Console under IAM, add the following roles to the project whose service account you're using to test:
+
+* Cloud CA Service Admin
+* Cloud CA Service Certificate Requester
+* Cloud CA Service Certificate Manager  
+* Cloud CA Service Certificate Template User
+* Cloud CA Service Workload Certificate Requester  
+* Cloud CA Service Operation Manager  
+* Cloud CA Service Auditor
+
+More information can be found in the [Google Private Certificate Authority Service Docs](https://cloud.google.com/certificate-authority-service/docs/reference/permissions-and-roles).
+
+
+## Build and Run
+
+The following instructions will help you prepare your development environment.
+
+1. Download and install the [Java Development Kit (JDK)](https://www.oracle.com/java/technologies/javase-downloads.html). 
+   Verify that the [JAVA_HOME](https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/envvars001.html) environment variable is set and points to your JDK installation.
+
+
+2. Download and install [Apache Maven](http://maven.apache.org/download.cgi) by following the [Maven installation guide](http://maven.apache.org/install.html) for your specific operating system.
+
+
+3. Clone the java-security-private-ca repository.
+```
+git clone https://github.com/googleapis/java-security-private-ca.git
+```
+
+4. Navigate to the sample code directory.
+
+```
+cd java-security-private-ca/samples/snippets/cloud-client
+```
+
+5. Run the **SnippetsIT** test file present under the test folder.
+
+### Crypto frameworks 
+[Bouncy Castle](https://www.bouncycastle.org/documentation.html) cryptographic framework is used as a part of testing.
diff --git a/privateca/cloud-client/src/main/java/privateca/CreateCaPool.java b/privateca/cloud-client/src/main/java/privateca/CreateCaPool.java
@@ -34,16 +34,16 @@ public static void main(String[] args)
     // TODO(developer): Replace these variables before running the sample.
     // location: For a list of locations, see:
     // https://cloud.google.com/certificate-authority-service/docs/locations
-    // caPoolName: Set a unique name for the CA pool.
+    // pool_Id: Set a unique pool_Id for the CA pool.
     String project = "your-project-id";
     String location = "ca-location";
-    String caPoolName = "ca-pool-name";
-    createCaPool(project, location, caPoolName);
+    String pool_Id = "ca-pool-id";
+    createCaPool(project, location, pool_Id);
   }
 
   // Create a Certificate Authority Pool. All certificates created under this CA pool will
   // follow the same issuance policy, IAM policies,etc.,
-  public static void createCaPool(String project, String location, String caPoolName)
+  public static void createCaPool(String project, String location, String pool_Id)
       throws InterruptedException, ExecutionException, IOException {
     // Initialize client that will be used to send requests. This client only needs to be created
     // once, and can be reused for multiple requests. After completing all of your requests, call
@@ -59,7 +59,7 @@ Set the Tier (see: https://cloud.google.com/certificate-authority-service/docs/t
       CreateCaPoolRequest caPoolRequest =
           CreateCaPoolRequest.newBuilder()
               .setParent(LocationName.of(project, location).toString())
-              .setCaPoolId(caPoolName)
+              .setCaPoolId(pool_Id)
               .setCaPool(CaPool.newBuilder().setTier(Tier.ENTERPRISE).build())
               .build();
 
@@ -73,7 +73,7 @@ Set the Tier (see: https://cloud.google.com/certificate-authority-service/docs/t
         return;
       }
 
-      System.out.println("CA pool created successfully: " + caPoolName);
+      System.out.println("CA pool created successfully: " + pool_Id);
     }
   }
 }
diff --git a/privateca/cloud-client/src/main/java/privateca/CreateCertificate.java b/privateca/cloud-client/src/main/java/privateca/CreateCertificate.java
@@ -47,18 +47,18 @@ public static void main(String[] args)
     // publicKeyBytes: Public key used in signing the certificates.
     // location: For a list of locations, see:
     // https://cloud.google.com/certificate-authority-service/docs/locations
-    // caPoolName: Set a unique name for the CA pool.
+    // pool_Id: Set a unique id for the CA pool.
     // certificateAuthorityName: The name of the certificate authority which issues the certificate.
     // certificateName: Set a unique name for the certificate.
     String project = "your-project-id";
     ByteString publicKeyBytes = ByteString.copyFrom(new byte[] {});
     String location = "ca-location";
-    String caPoolName = "ca-pool-name";
+    String pool_Id = "ca-pool_Id";
     String certificateAuthorityName = "certificate-authority-name";
     String certificateName = "certificate-name";
 
     createCertificate(
-        project, location, caPoolName, certificateAuthorityName, certificateName, publicKeyBytes);
+        project, location, pool_Id, certificateAuthorityName, certificateName, publicKeyBytes);
   }
 
   // Create a Certificate which is issued by the Certificate Authority present in the CA Pool.
@@ -67,7 +67,7 @@ public static void main(String[] args)
   public static void createCertificate(
       String project,
       String location,
-      String caPoolName,
+      String pool_Id,
       String certificateAuthorityName,
       String certificateName,
       ByteString publicKeyBytes)
@@ -133,7 +133,7 @@ public static void createCertificate(
       // Create the Certificate Request.
       CreateCertificateRequest certificateRequest =
           CreateCertificateRequest.newBuilder()
-              .setParent(CaPoolName.of(project, location, caPoolName).toString())
+              .setParent(CaPoolName.of(project, location, pool_Id).toString())
               .setCertificateId(certificateName)
               .setCertificate(certificate)
               .setIssuingCertificateAuthorityId(certificateAuthorityName)
diff --git a/privateca/cloud-client/src/main/java/privateca/CreateCertificateAuthority.java b/privateca/cloud-client/src/main/java/privateca/CreateCertificateAuthority.java
@@ -43,19 +43,18 @@ public static void main(String[] args)
     // TODO(developer): Replace these variables before running the sample.
     // location: For a list of locations, see:
     // https://cloud.google.com/certificate-authority-service/docs/locations
-    // caPoolName: Set it to the CA Pool under which the CA should be created.
+    // pool_Id: Set it to the CA Pool under which the CA should be created.
     // certificateAuthorityName: Unique name for the CA.
     String project = "your-project-id";
     String location = "ca-location";
-    String caPoolName = "ca-pool-name";
+    String pool_Id = "ca-pool-id";
     String certificateAuthorityName = "certificate-authority-name";
-    createCertificateAuthority(project, location, caPoolName, certificateAuthorityName);
+    createCertificateAuthority(project, location, pool_Id, certificateAuthorityName);
   }
 
-  // Create Certificate Authority which is the root CA in the given CA Pool. This CA will be
-  // responsible for signing certificates within this pool.
+  // Create Certificate Authority which is the root CA in the given CA Pool.
   public static void createCertificateAuthority(
-      String project, String location, String caPoolName, String certificateAuthorityName)
+      String project, String location, String pool_Id, String certificateAuthorityName)
       throws InterruptedException, ExecutionException, IOException {
     // Initialize client that will be used to send requests. This client only needs to be created
     // once, and can be reused for multiple requests. After completing all of your requests, call
@@ -68,7 +67,7 @@ public static void createCertificateAuthority(
       String orgName = "org-name";
       int caDuration = 100000; // Validity of this CA in seconds.
 
-      // Set the types of Algorithm used to create a cloud KMS key.
+      // Set the type of Algorithm.
       KeyVersionSpec keyVersionSpec =
           KeyVersionSpec.newBuilder().setAlgorithm(SignHashAlgorithm.RSA_PKCS1_4096_SHA256).build();
 
@@ -108,7 +107,7 @@ public static void createCertificateAuthority(
       // Create the CertificateAuthorityRequest.
       CreateCertificateAuthorityRequest certificateAuthorityRequest =
           CreateCertificateAuthorityRequest.newBuilder()
-              .setParent(CaPoolName.of(project, location, caPoolName).toString())
+              .setParent(CaPoolName.of(project, location, pool_Id).toString())
               .setCertificateAuthorityId(certificateAuthorityName)
               .setCertificateAuthority(certificateAuthority)
               .build();
diff --git a/privateca/cloud-client/src/main/java/privateca/DeleteCaPool.java b/privateca/cloud-client/src/main/java/privateca/DeleteCaPool.java
@@ -33,16 +33,16 @@ public static void main(String[] args)
     // TODO(developer): Replace these variables before running the sample.
     // location: For a list of locations, see:
     // https://cloud.google.com/certificate-authority-service/docs/locations
-    // caPoolName: The name of the CA pool to be deleted.
+    // pool_Id: The id of the CA pool to be deleted.
     String project = "your-project-id";
     String location = "ca-location";
-    String caPoolName = "ca-pool-name";
-    deleteCaPool(project, location, caPoolName);
+    String pool_Id = "ca-pool-id";
+    deleteCaPool(project, location, pool_Id);
   }
 
-  // Delete the CA pool as mentioned by the caPoolName.
+  // Delete the CA pool as mentioned by the pool_Id.
   // Before deleting the pool, all CAs in the pool MUST BE deleted.
-  public static void deleteCaPool(String project, String location, String caPoolName)
+  public static void deleteCaPool(String project, String location, String pool_Id)
       throws InterruptedException, ExecutionException, IOException {
     // Initialize client that will be used to send requests. This client only needs to be created
     // once, and can be reused for multiple requests. After completing all of your requests, call
@@ -51,12 +51,12 @@ public static void deleteCaPool(String project, String location, String caPoolNa
     try (CertificateAuthorityServiceClient certificateAuthorityServiceClient =
         CertificateAuthorityServiceClient.create()) {
 
-      // Set the project, location and caPoolName to delete.
+      // Set the project, location and pool_Id to delete.
       CaPoolName caPool =
           CaPoolName.newBuilder()
               .setProject(project)
               .setLocation(location)
-              .setCaPool(caPoolName)
+              .setCaPool(pool_Id)
               .build();
 
       // Create the Delete request.
@@ -73,7 +73,7 @@ public static void deleteCaPool(String project, String location, String caPoolNa
         return;
       }
 
-      System.out.println("Deleted CA Pool: " + caPoolName);
+      System.out.println("Deleted CA Pool: " + pool_Id);
     }
   }
 }
diff --git a/privateca/cloud-client/src/main/java/privateca/DeleteCertificateAuthority.java b/privateca/cloud-client/src/main/java/privateca/DeleteCertificateAuthority.java
@@ -33,19 +33,19 @@ public static void main(String[] args)
     // TODO(developer): Replace these variables before running the sample.
     // location: For a list of locations, see:
     // https://cloud.google.com/certificate-authority-service/docs/locations
-    // caPoolName: The name of the CA pool under which the CA is present.
+    // pool_Id: The id of the CA pool under which the CA is present.
     // certificateAuthorityName: The name of the CA to be deleted.
     String project = "your-project-id";
     String location = "ca-location";
-    String caPoolName = "ca-pool-name";
+    String pool_Id = "ca-pool-id";
     String certificateAuthorityName = "certificate-authority-name";
-    deleteCertificateAuthority(project, location, caPoolName, certificateAuthorityName);
+    deleteCertificateAuthority(project, location, pool_Id, certificateAuthorityName);
   }
 
   // Delete the Certificate Authority from the specified CA pool.
   // Before deletion, the CA must be disabled and must not contain any active certificates.
   public static void deleteCertificateAuthority(
-      String project, String location, String caPoolName, String certificateAuthorityName)
+      String project, String location, String pool_Id, String certificateAuthorityName)
       throws IOException, ExecutionException, InterruptedException {
     // Initialize client that will be used to send requests. This client only needs to be created
     // once, and can be reused for multiple requests. After completing all of your requests, call
@@ -58,7 +58,7 @@ public static void deleteCertificateAuthority(
           CertificateAuthorityName.newBuilder()
               .setProject(project)
               .setLocation(location)
-              .setCaPool(caPoolName)
+              .setCaPool(pool_Id)
               .setCertificateAuthority(certificateAuthorityName)
               .build();
 
diff --git a/privateca/cloud-client/src/main/java/privateca/DisableCertificateAuthority.java b/privateca/cloud-client/src/main/java/privateca/DisableCertificateAuthority.java
@@ -33,18 +33,18 @@ public static void main(String[] args)
     // TODO(developer): Replace these variables before running the sample.
     // location: For a list of locations, see:
     // https://cloud.google.com/certificate-authority-service/docs/locations
-    // caPoolName: The name of the CA pool under which the CA is present.
+    // pool_Id: The id of the CA pool under which the CA is present.
     // certificateAuthorityName: The name of the CA to be disabled.
     String project = "your-project-id";
     String location = "ca-location";
-    String caPoolName = "ca-pool-name";
+    String pool_Id = "ca-pool-id";
     String certificateAuthorityName = "certificate-authority-name";
-    disableCertificateAuthority(project, location, caPoolName, certificateAuthorityName);
+    disableCertificateAuthority(project, location, pool_Id, certificateAuthorityName);
   }
 
   // Disable a Certificate Authority which is present in the given CA pool.
   public static void disableCertificateAuthority(
-      String project, String location, String caPoolName, String certificateAuthorityName)
+      String project, String location, String pool_Id, String certificateAuthorityName)
       throws IOException, ExecutionException, InterruptedException {
     // Initialize client that will be used to send requests. This client only needs to be created
     // once, and can be reused for multiple requests. After completing all of your requests, call
@@ -58,7 +58,7 @@ public static void disableCertificateAuthority(
           CertificateAuthorityName.newBuilder()
               .setProject(project)
               .setLocation(location)
-              .setCaPool(caPoolName)
+              .setCaPool(pool_Id)
               .setCertificateAuthority(certificateAuthorityName)
               .build();
 
diff --git a/privateca/cloud-client/src/main/java/privateca/EnableCertificateAuthority.java b/privateca/cloud-client/src/main/java/privateca/EnableCertificateAuthority.java
@@ -33,19 +33,19 @@ public static void main(String[] args)
     // TODO(developer): Replace these variables before running the sample.
     // location: For a list of locations, see:
     // https://cloud.google.com/certificate-authority-service/docs/locations
-    // caPoolName: The name of the CA pool under which the CA is present.
+    // pool_Id: The id of the CA pool under which the CA is present.
     // certificateAuthorityName: The name of the CA to be enabled.
     String project = "your-project-id";
     String location = "ca-location";
-    String caPoolName = "ca-pool-name";
+    String pool_Id = "ca-pool-id";
     String certificateAuthorityName = "certificate-authority-name";
-    enableCertificateAuthority(project, location, caPoolName, certificateAuthorityName);
+    enableCertificateAuthority(project, location, pool_Id, certificateAuthorityName);
   }
 
   // Enable the Certificate Authority present in the given ca pool.
   // CA cannot be enabled if it has been already deleted.
   public static void enableCertificateAuthority(
-      String project, String location, String caPoolName, String certificateAuthorityName)
+      String project, String location, String pool_Id, String certificateAuthorityName)
       throws IOException, ExecutionException, InterruptedException {
     try (CertificateAuthorityServiceClient certificateAuthorityServiceClient =
         CertificateAuthorityServiceClient.create()) {
@@ -54,7 +54,7 @@ public static void enableCertificateAuthority(
           CertificateAuthorityName.newBuilder()
               .setProject(project)
               .setLocation(location)
-              .setCaPool(caPoolName)
+              .setCaPool(pool_Id)
               .setCertificateAuthority(certificateAuthorityName)
               .build();
 
diff --git a/privateca/cloud-client/src/main/java/privateca/ListCaPools.java b/privateca/cloud-client/src/main/java/privateca/ListCaPools.java
@@ -54,8 +54,8 @@ public static void listCaPools(String project, String location) throws IOExcepti
           certificateAuthorityServiceClient.listCaPools(locationName).iterateAll()) {
         caPoolName = caPool.getName();
         // caPoolName represents the full resource name of the
-        // format 'projects/{project-id}/locations/{location}/ca-pools/{ca-pool-name}'.
-        // Hence stripping it down to just pool name.
+        // format 'projects/{project-id}/locations/{location}/ca-pools/{ca-pool-id}'.
+        // Hence stripping it down to just CA pool id.
         System.out.println(
             caPoolName.substring(caPoolName.lastIndexOf("/") + 1) + " " + caPool.isInitialized());
       }
diff --git a/privateca/cloud-client/src/main/java/privateca/ListCertificateAuthorities.java b/privateca/cloud-client/src/main/java/privateca/ListCertificateAuthorities.java
@@ -28,15 +28,15 @@ public static void main(String[] args) throws IOException {
     // TODO(developer): Replace these variables before running the sample.
     // location: For a list of locations, see:
     // https://cloud.google.com/certificate-authority-service/docs/locations
-    // caPoolName: The name of the CA pool under which the CAs to be listed are present.
+    // pool_Id: The id of the CA pool under which the CAs to be listed are present.
     String project = "your-project-id";
     String location = "ca-location";
-    String caPoolName = "ca-pool-name";
-    listCertificateAuthority(project, location, caPoolName);
+    String pool_Id = "ca-pool-id";
+    listCertificateAuthority(project, location, pool_Id);
   }
 
   // List all Certificate authorities present in the given CA Pool.
-  public static void listCertificateAuthority(String project, String location, String caPoolName)
+  public static void listCertificateAuthority(String project, String location, String pool_Id)
       throws IOException {
     // Initialize client that will be used to send requests. This client only needs to be created
     // once, and can be reused for multiple requests. After completing all of your requests, call
@@ -50,7 +50,7 @@ public static void listCertificateAuthority(String project, String location, Str
           CaPoolName.newBuilder()
               .setProject(project)
               .setLocation(location)
-              .setCaPool(caPoolName)
+              .setCaPool(pool_Id)
               .build();
 
       // List the CA name and its corresponding state.
diff --git a/privateca/cloud-client/src/main/java/privateca/ListCertificates.java b/privateca/cloud-client/src/main/java/privateca/ListCertificates.java
diff --git a/privateca/cloud-client/src/main/java/privateca/RevokeCertificate.java b/privateca/cloud-client/src/main/java/privateca/RevokeCertificate.java
diff --git a/privateca/cloud-client/src/test/java/privateca/SnippetsIT.java b/privateca/cloud-client/src/test/java/privateca/SnippetsIT.java
