AWS.CloudHSMV2 reference

Cluster

Source: src/AWS/CloudHSMV2/Cluster.ts

An AWS CloudHSM cluster — a fleet of FIPS-validated, single-tenant hardware security modules (HSMs) inside your VPC.

A fresh cluster provisions to the UNINITIALIZED state in a few minutes and holds no HSMs; add Hsm resources to place HSMs into its subnets’ Availability Zones (each HSM is billed hourly). Activating the cluster (signing the cluster CSR and calling InitializeCluster) is an offline certificate-authority ceremony that stays out of band — the clusterCsr attribute exposes the CSR to sign.

Cluster: Creating a Cluster

Cluster Spanning Two Availability Zones

const cluster = yield* Cluster("HsmCluster", {
  hsmType: "hsm2m.medium",
  subnetIds: [subnetA.subnetId, subnetB.subnetId],
});

Non-FIPS Cluster with Custom Backup Retention

const cluster = yield* Cluster("HsmCluster", {
  hsmType: "hsm2m.medium",
  subnetIds: [subnetA.subnetId, subnetB.subnetId],
  mode: "NON_FIPS",
  backupRetention: "30 days",
});

Cluster: Adding HSMs

const cluster = yield* Cluster("HsmCluster", {
  hsmType: "hsm2m.medium",
  subnetIds: [subnetA.subnetId, subnetB.subnetId],
});
const hsm = yield* Hsm("Primary", {
  clusterId: cluster.clusterId,
  availabilityZone: "us-west-2a",
});

CopyBackupToRegion

Source: src/AWS/CloudHSMV2/CopyBackupToRegion.ts

Runtime binding for the CopyBackupToRegion operation (IAM action cloudhsm:CopyBackupToRegion; the grant includes cloudhsm:TagResource so user tags on the source backup can be copied to the destination backup).

Copies a CloudHSM cluster backup into another region — the building block of cross-region disaster-recovery automation. Provide the implementation with Effect.provide(AWS.CloudHSMV2.CopyBackupToRegionHttp).

CopyBackupToRegion: Managing Backups

const copyBackupToRegion = yield* AWS.CloudHSMV2.CopyBackupToRegion();

const copy = yield* copyBackupToRegion({
  DestinationRegion: "us-east-1",
  BackupId: backupId,
});
// copy.DestinationBackup?.SourceBackup === backupId

DeleteBackup

Source: src/AWS/CloudHSMV2/DeleteBackup.ts

Runtime binding for the DeleteBackup operation (IAM action cloudhsm:DeleteBackup).

Marks a CloudHSM backup for deletion — it enters PENDING_DELETION and can still be recovered with RestoreBackup for 7 days. Pair with DescribeBackups to build a backup-pruning job. Provide the implementation with Effect.provide(AWS.CloudHSMV2.DeleteBackupHttp).

DeleteBackup: Managing Backups

const deleteBackup = yield* AWS.CloudHSMV2.DeleteBackup();

const deleted = yield* deleteBackup({ BackupId: backupId });
// deleted.Backup?.BackupState === "PENDING_DELETION"

DeleteResourcePolicy

Source: src/AWS/CloudHSMV2/DeleteResourcePolicy.ts

Runtime binding for the DeleteResourcePolicy operation (IAM action cloudhsm:DeleteResourcePolicy).

Removes the resource policy from a CloudHSM backup, unsharing it (and removing it from any RAM resource shares); clusters already created from the backup are unaffected. Provide the implementation with Effect.provide(AWS.CloudHSMV2.DeleteResourcePolicyHttp).

DeleteResourcePolicy: Sharing Backups

const deleteResourcePolicy = yield* AWS.CloudHSMV2.DeleteResourcePolicy();

yield* deleteResourcePolicy({ ResourceArn: backupArn });

DescribeBackups

Source: src/AWS/CloudHSMV2/DescribeBackups.ts

Runtime binding for the DescribeBackups operation (IAM action cloudhsm:DescribeBackups).

Lists the account’s CloudHSM cluster backups (or backups shared with the account when Shared is true), optionally filtered by backup id, cluster id or state — the observation half of backup-retention and disaster- recovery automation. Provide the implementation with Effect.provide(AWS.CloudHSMV2.DescribeBackupsHttp).

DescribeBackups: Managing Backups

const describeBackups = yield* AWS.CloudHSMV2.DescribeBackups();

const page = yield* describeBackups({
  Filters: { clusterIds: [clusterId], states: ["READY"] },
});

DescribeClusters

Source: src/AWS/CloudHSMV2/DescribeClusters.ts

Runtime binding for the DescribeClusters operation (IAM action cloudhsm:DescribeClusters).

Lists the account’s CloudHSM clusters (optionally filtered by cluster id, VPC or state) with each cluster’s HSMs embedded — the building block of cluster-health monitoring and automatic-HSM-replacement automation. Provide the implementation with Effect.provide(AWS.CloudHSMV2.DescribeClustersHttp).

DescribeClusters: Monitoring Clusters

const describeClusters = yield* AWS.CloudHSMV2.DescribeClusters();

const page = yield* describeClusters({
  Filters: { clusterIds: [clusterId] },
});
const active = page.Clusters?.[0]?.Hsms?.filter(
  (hsm) => hsm.State === "ACTIVE",
);

GetResourcePolicy

Source: src/AWS/CloudHSMV2/GetResourcePolicy.ts

Runtime binding for the GetResourcePolicy operation (IAM action cloudhsm:GetResourcePolicy).

Reads the resource policy attached to a CloudHSM backup (backups are the only CloudHSM resource that supports policies — they govern cross-account backup sharing). Provide the implementation with Effect.provide(AWS.CloudHSMV2.GetResourcePolicyHttp).

GetResourcePolicy: Sharing Backups

const getResourcePolicy = yield* AWS.CloudHSMV2.GetResourcePolicy();

const { Policy } = yield* getResourcePolicy({ ResourceArn: backupArn });

Hsm

Source: src/AWS/CloudHSMV2/Hsm.ts

A hardware security module (HSM) inside an AWS CloudHSM Cluster.

HSMs take roughly 10-20 minutes to provision and are billed hourly while they exist. The cluster must be in the UNINITIALIZED, ACTIVE, or DEGRADED state to accept a new HSM. Destroy HSMs you are not using.

Hsm: Creating an HSM

HSM in a Cluster’s Availability Zone

const hsm = yield* Hsm("Primary", {
  clusterId: cluster.clusterId,
  availabilityZone: "us-west-2a",
});

HSM with a Fixed ENI Address

const hsm = yield* Hsm("Primary", {
  clusterId: cluster.clusterId,
  availabilityZone: "us-west-2a",
  ipAddress: "10.0.1.20",
});

InitializeCluster

Source: src/AWS/CloudHSMV2/InitializeCluster.ts

Runtime binding for the InitializeCluster operation (IAM action cloudhsm:InitializeCluster).

Claims an UNINITIALIZED CloudHSM cluster by submitting the cluster certificate (the cluster’s CSR signed by your issuing CA) and the CA’s root certificate — lets a Function automate the activation ceremony around your CA. The certificates are public key material. Provide the implementation with Effect.provide(AWS.CloudHSMV2.InitializeClusterHttp).

InitializeCluster: Activating a Cluster

const initializeCluster = yield* AWS.CloudHSMV2.InitializeCluster();

const result = yield* initializeCluster({
  ClusterId: clusterId,
  SignedCert: signedClusterCertPem,
  TrustAnchor: issuingCaRootPem,
});
// result.State === "INITIALIZE_IN_PROGRESS"

ModifyBackupAttributes

Source: src/AWS/CloudHSMV2/ModifyBackupAttributes.ts

Runtime binding for the ModifyBackupAttributes operation (IAM action cloudhsm:ModifyBackupAttributes).

Toggles a backup’s NeverExpires attribute — pin a golden backup so the cluster’s retention policy never deletes it, or unpin it again. Provide the implementation with Effect.provide(AWS.CloudHSMV2.ModifyBackupAttributesHttp).

ModifyBackupAttributes: Managing Backups

const modifyBackupAttributes =
  yield* AWS.CloudHSMV2.ModifyBackupAttributes();

yield* modifyBackupAttributes({ BackupId: backupId, NeverExpires: true });

PutResourcePolicy

Source: src/AWS/CloudHSMV2/PutResourcePolicy.ts

Runtime binding for the PutResourcePolicy operation (IAM action cloudhsm:PutResourcePolicy).

Creates or replaces the resource policy on a CloudHSM backup, sharing a READY backup you own with other accounts (AWS recommends RAM for discoverable multi-resource shares; this is the direct API). Provide the implementation with Effect.provide(AWS.CloudHSMV2.PutResourcePolicyHttp).

PutResourcePolicy: Sharing Backups

const putResourcePolicy = yield* AWS.CloudHSMV2.PutResourcePolicy();

yield* putResourcePolicy({
  ResourceArn: backupArn,
  Policy: JSON.stringify({
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: { AWS: "arn:aws:iam::123456789012:root" },
      Action: ["cloudhsm:DescribeBackups"],
      Resource: backupArn,
    }],
  }),
});

RestoreBackup

Source: src/AWS/CloudHSMV2/RestoreBackup.ts

Runtime binding for the RestoreBackup operation (IAM action cloudhsm:RestoreBackup).

Recovers a CloudHSM backup in the PENDING_DELETION state back to READY — the undo for DeleteBackup, available for 7 days after the delete. Provide the implementation with Effect.provide(AWS.CloudHSMV2.RestoreBackupHttp).

RestoreBackup: Managing Backups

const restoreBackup = yield* AWS.CloudHSMV2.RestoreBackup();

const restored = yield* restoreBackup({ BackupId: backupId });
// restored.Backup?.BackupState === "READY"