Share via

CertificateClient class

  • Reference
Package:
@azure/keyvault-certificates

The client to interact with the KeyVault certificates functionality

Constructors

CertificateClient(string, TokenCredential, CertificateClientOptions)

Creates an instance of CertificateClient.

Properties

vaultUrl

The base URL to the vault

Methods

backupCertificate(string, OperationOptions)

Requests that a backup of the specified certificate be downloaded to the client. All versions of the certificate will be downloaded. This operation requires the certificates/backup permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
const backup = await client.backupCertificate("MyCertificate");

Generates a backup of a certificate
beginCreateCertificate(string, CertificatePolicy, BeginCreateCertificateOptions)

Creates a new certificate. If this is the first version, the certificate resource is created. This function returns a Long Running Operation poller that allows you to wait indefinitely until the certificate is fully recovered.

Note: Sending Self as the issuerName of the certificate's policy will create a self-signed certificate.

This operation requires the certificates/create permission.

Example usage:

const client = new CertificateClient(url, credentials);
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert"
};
const createPoller = await client.beginCreateCertificate("MyCertificate", certificatePolicy);

// The pending certificate can be obtained by calling the following method:
const pendingCertificate = createPoller.getResult();

// Serializing the poller
const serialized = createPoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginCreateCertificate("MyCertificate", certificatePolicy, { resumeFrom: serialized });

// Waiting until it's done
const certificate = await createPoller.pollUntilDone();
console.log(certificate);

Creates a certificate
beginDeleteCertificate(string, CertificatePollerOptions)

The DELETE operation applies to any certificate stored in Azure Key Vault. DELETE cannot be applied to an individual version of a certificate. This function returns a Long Running Operation poller that allows you to wait indefinitely until the certificate is fully recovered.

This operation requires the certificates/delete permission.

Example usage:

const client = new CertificateClient(url, credentials);
const createPoller = await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
await createPoller.pollUntilDone();

const deletePoller = await client.beginDeleteCertificate("MyCertificate");

// Serializing the poller
const serialized = deletePoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginDeleteCertificate("MyCertificate", { resumeFrom: serialized });

// Waiting until it's done
const deletedCertificate = await deletePoller.pollUntilDone();
console.log(deletedCertificate);

Deletes a certificate from a specified key vault.
beginRecoverDeletedCertificate(string, CertificatePollerOptions)

Recovers the deleted certificate in the specified vault. This operation can only be performed on a soft-delete enabled vault. This operation This function returns a Long Running Operation poller that allows you to wait indefinitely until the certificate is fully recovered.

This operation requires the certificates/recover permission.

Example usage:

const client = new CertificateClient(url, credentials);

const deletePoller = await client.beginDeleteCertificate("MyCertificate");
await deletePoller.pollUntilDone();

const recoverPoller = await client.beginRecoverDeletedCertificate("MyCertificate");

// Serializing the poller
const serialized = deletePoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginRecoverDeletedCertificate("MyCertificate", { resumeFrom: serialized });

// Waiting until it's done
const certificate = await recoverPoller.pollUntilDone();
console.log(certificate);

Recovers a deleted certificate
createIssuer(string, string, CreateIssuerOptions)

The createIssuer operation adds or updates the specified certificate issuer. This operation requires the certificates/setissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Test");

Sets the specified certificate issuer.
deleteCertificateOperation(string, OperationOptions)

Deletes the creation operation for a specified certificate that is in the process of being created. The certificate is no longer created. This operation requires the certificates/update permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
await client.deleteCertificateOperation("MyCertificate");
await client.getCertificateOperation("MyCertificate"); // Throws error: Pending certificate not found: "MyCertificate"

Delete a certificate's operation
deleteContacts(OperationOptions)

Deletes all of the certificate contacts. This operation requires the certificates/managecontacts permission.

Example usage:

let client = new CertificateClient(url, credentials);
await client.setContacts([{
  email: "b@b.com",
  name: "b",
  phone: "222222222222"
}]);
await client.deleteContacts();

Deletes all of the certificate contacts
deleteIssuer(string, OperationOptions)

The deleteIssuer operation permanently removes the specified certificate issuer from the vault. This operation requires the certificates/manageissuers/deleteissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Provider");
await client.deleteIssuer("IssuerName");

Deletes the specified certificate issuer.
getCertificate(string, OperationOptions)

Gets the latest information available from a specific certificate, including the certificate's policy. This operation requires the certificates/get permission.

Example usage:

const client = new CertificateClient(url, credentials);
const poller = await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
await poller.pollUntilDone();
const certificate = await client.getCertificate("MyCertificate");
console.log(certificate);

Retrieves a certificate from the certificate's name (includes the certificate policy)
getCertificateOperation(string, CertificatePollerOptions)

Gets the creation operation associated with a specified certificate. This operation requires the certificates/get permission. This function returns a Long Running Operation poller that allows you to wait indefinitely until the certificate is fully recovered.

Example usage:

const client = new CertificateClient(url, credentials);
const createPoller = await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});

const poller = await client.getCertificateOperation("MyCertificate");
const pendingCertificate = poller.getResult();

const certificateOperation = poller.getOperationState().certificateOperation;
console.log(certificateOperation);

Gets a certificate's poller operation
getCertificatePolicy(string, OperationOptions)

The getCertificatePolicy operation returns the specified certificate policy resources in the specified key vault. This operation requires the certificates/get permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
const policy = await client.getCertificatePolicy("MyCertificate");
console.log(policy);

Gets a certificate's policy
getCertificateVersion(string, string, OperationOptions)

Gets information about a specific certificate on a specific version. It won't return the certificate's policy. This operation requires the certificates/get permission.

Example usage:

const client = new CertificateClient(url, credentials);
const poller = await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
await poller.pollUntilDone();
const certificateWithPolicy = await client.getCertificate("MyCertificate");
const certificate = await client.getCertificateVersion("MyCertificate", certificateWithPolicy.properties.version!);
console.log(certificate);

Retrieves a certificate from the certificate's name and a specified version
getContacts(OperationOptions)

Returns the set of certificate contact resources in the specified key vault. This operation requires the certificates/managecontacts permission.

Example usage:

let client = new CertificateClient(url, credentials);
await client.setContacts([{
  email: "b@b.com",
  name: "b",
  phone: "222222222222"
}]);
const contacts = await client.getContacts();
console.log(contacts);

Sets the certificate contacts.
getDeletedCertificate(string, OperationOptions)

retrieves the deleted certificate information plus its attributes, such as retention interval, scheduled permanent deletion and the current deletion recovery level. This operation requires the certificates/get permission.

Example usage:

const client = new CertificateClient(url, credentials);
const deletedCertificate = await client.getDeletedCertificate("MyDeletedCertificate");
console.log("Deleted certificate:", deletedCertificate);

Gets a deleted certificate
getIssuer(string, OperationOptions)

The getIssuer operation returns the specified certificate issuer resources in the specified key vault. This operation requires the certificates/manageissuers/getissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Test");
const certificateIssuer = await client.getIssuer("IssuerName");
console.log(certificateIssuer);

Gets he specified certificate issuer.
importCertificate(string, Uint8Array, ImportCertificateOptions)

Imports an existing valid certificate, containing a private key, into Azure Key Vault. The certificate to be imported can be in either PFX or PEM format. If the certificate is in PEM format the PEM file must contain the key as well as x509 certificates. This operation requires the certificates/import permission.

Example usage:

const client = new CertificateClient(url, credentials);
// See: @azure/keyvault-secrets
const certificateSecret = await secretClient.getSecret("MyCertificate");
const base64EncodedCertificate = certificateSecret.value!;
let buffer: Uint8Array;

if (isNode) {
  buffer = Buffer.from(base64EncodedCertificate, "base64");
} else {
  buffer = Uint8Array.from(atob(base64EncodedCertificate), (c) => c.charCodeAt(0));
}

await client.importCertificate("MyCertificate", buffer);

Imports a certificate from a certificate's secret value
listDeletedCertificates(ListDeletedCertificatesOptions)

Retrieves the certificates in the current vault which are in a deleted state and ready for recovery or purging. This operation includes deletion-specific information. This operation requires the certificates/get/list permission. This operation can only be enabled on soft-delete enabled vaults.

Example usage:

const client = new CertificateClient(url, credentials);
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log(deletedCertificate);
}
for await (const page of client.listDeletedCertificates().byPage()) {
  for (const deletedCertificate of page) {
    console.log(deletedCertificate);
  }
}

Lists deleted certificates
listPropertiesOfCertificates(ListPropertiesOfCertificatesOptions)

Iterates the latest version of all certificates in the vault. The full certificate identifier and attributes are provided in the response. No values are returned for the certificates. This operations requires the certificates/list permission.

Example usage:

const client = new CertificateClient(url, credentials);
// All in one call
for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log(certificateProperties);
}
// By pages
for await (const page of client.listPropertiesOfCertificates().byPage()) {
  for (const certificateProperties of page) {
    console.log(certificateProperties);
  }
}

List all versions of the specified certificate.
listPropertiesOfCertificateVersions(string, OperationOptions)

Returns the versions of a certificate in the specified key vault. This operation requires the certificates/list permission.

Example usage:

const client = new CertificateClient(url, credentials);
for await (const certificateProperties of client.listPropertiesOfCertificateVersions("MyCertificate")) {
  console.log(certificateProperties.version!);
}

List the versions of a certificate.
listPropertiesOfIssuers(OperationOptions)

Returns the set of certificate issuer resources in the specified key vault. This operation requires the certificates/manageissuers/getissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Test");
// All in one call
for await (const issuerProperties of client.listPropertiesOfIssuers()) {
  console.log(issuerProperties);
}
// By pages
for await (const page of client.listPropertiesOfIssuers().byPage()) {
  for (const issuerProperties of page) {
    console.log(issuerProperties);
  }
}

List the certificate issuers.
mergeCertificate(string, Uint8Array[], OperationOptions)

Performs the merging of a certificate or certificate chain with a key pair currently available in the service. This operation requires the certificates/create permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Unknown",
  subject: "cn=MyCert"
});
const poller = await client.getCertificateOperation("MyCertificate");
const { csr } = poller.getOperationState().certificateOperation!;
const base64Csr = Buffer.from(csr!).toString("base64");
const wrappedCsr = ["-----BEGIN CERTIFICATE REQUEST-----", base64Csr, "-----END CERTIFICATE REQUEST-----"].join("\n");

const fs = require("fs");
fs.writeFileSync("test.csr", wrappedCsr);

// Certificate available locally made using:
//   openssl genrsa -out ca.key 2048
//   openssl req -new -x509 -key ca.key -out ca.crt
// You can read more about how to create a fake certificate authority here: https://gist.github.com/Soarez/9688998

const childProcess = require("child_process");
childProcess.execSync("openssl x509 -req -in test.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out test.crt");
const base64Crt = fs.readFileSync("test.crt").toString().split("\n").slice(1, -1).join("");

await client.mergeCertificate("MyCertificate", [Buffer.from(base64Crt)]);

Merges a signed certificate request into a pending certificate
purgeDeletedCertificate(string, OperationOptions)

Performs an irreversible deletion of the specified certificate, without possibility for recovery. The operation is not available if the recovery level does not specify 'Purgeable'. This operation requires the certificate/purge permission.

Example usage:

const client = new CertificateClient(url, credentials);
const deletePoller = await client.beginDeleteCertificate("MyCertificate");
await deletePoller.pollUntilDone();
// Deleting a certificate takes time, make sure to wait before purging it
client.purgeDeletedCertificate("MyCertificate");

Gets a deleted certificate
restoreCertificateBackup(Uint8Array, OperationOptions)

Restores a backed up certificate, and all its versions, to a vault. This operation requires the certificates/restore permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
const backup = await client.backupCertificate("MyCertificate");
const poller = await client.beginDeleteCertificate("MyCertificate");
await poller.pollUntilDone();
// Some time is required before we're able to restore the certificate
await client.restoreCertificateBackup(backup!);

Restores a certificate from a backup
setContacts(CertificateContact[], OperationOptions)

Sets the certificate contacts for the key vault. This operation requires the certificates/managecontacts permission.

Example usage:

let client = new CertificateClient(url, credentials);
await client.setContacts([{
  email: "b@b.com",
  name: "b",
  phone: "222222222222"
}]);

Sets the certificate contacts.
updateCertificatePolicy(string, CertificatePolicy, OperationOptions)

Updates the certificate policy for the specified certificate. This operation requires the certificates/update permission. Gets a certificate's policy
updateCertificateProperties(string, string, UpdateCertificatePropertiesOptions)

Applies the specified update on the given certificate; the only elements updated are the certificate's attributes. This operation requires the certificates/update permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});

// You may pass an empty string for version which will update
// the latest version of the certificate
await client.updateCertificateProperties("MyCertificate", "", {
  tags: {
    customTag: "value"
  }
});

Updates a certificate
updateIssuer(string, UpdateIssuerOptions)

The updateIssuer operation performs an update on the specified certificate issuer entity. This operation requires the certificates/setissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Test");
await client.updateIssuer("IssuerName", {
  provider: "Provider2"
});

Updates the specified certificate issuer.

Constructor Details

CertificateClient(string, TokenCredential, CertificateClientOptions)

Creates an instance of CertificateClient.

new CertificateClient(vaultUrl: string, credential: TokenCredential, clientOptions?: CertificateClientOptions)

Parameters

vaultUrl

string

the base URL to the vault. You should validate that this URL references a valid Key Vault resource. See https://aka.ms/azsdk/blog/vault-uri for details.

credential
TokenCredential

An object that implements the TokenCredential interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs.

clientOptions
CertificateClientOptions

Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration.

Property Details

vaultUrl

The base URL to the vault

vaultUrl: string

Property Value

string

Method Details

backupCertificate(string, OperationOptions)

Requests that a backup of the specified certificate be downloaded to the client. All versions of the certificate will be downloaded. This operation requires the certificates/backup permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
const backup = await client.backupCertificate("MyCertificate");

Generates a backup of a certificate

function backupCertificate(certificateName: string, options?: OperationOptions): Promise<undefined | Uint8Array>

Parameters

certificateName

string

The name of the certificate

options
OperationOptions

The optional parameters

Returns

Promise<undefined | Uint8Array>

beginCreateCertificate(string, CertificatePolicy, BeginCreateCertificateOptions)

Creates a new certificate. If this is the first version, the certificate resource is created. This function returns a Long Running Operation poller that allows you to wait indefinitely until the certificate is fully recovered.

Note: Sending Self as the issuerName of the certificate's policy will create a self-signed certificate.

This operation requires the certificates/create permission.

Example usage:

const client = new CertificateClient(url, credentials);
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert"
};
const createPoller = await client.beginCreateCertificate("MyCertificate", certificatePolicy);

// The pending certificate can be obtained by calling the following method:
const pendingCertificate = createPoller.getResult();

// Serializing the poller
const serialized = createPoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginCreateCertificate("MyCertificate", certificatePolicy, { resumeFrom: serialized });

// Waiting until it's done
const certificate = await createPoller.pollUntilDone();
console.log(certificate);

Creates a certificate

function beginCreateCertificate(certificateName: string, policy: CertificatePolicy, options?: BeginCreateCertificateOptions): Promise<PollerLikeWithCancellation<CreateCertificateState, KeyVaultCertificateWithPolicy>>

Parameters

certificateName

string

The name of the certificate

policy
CertificatePolicy
options
BeginCreateCertificateOptions

Optional parameters

Returns

Promise<PollerLikeWithCancellation<CreateCertificateState, KeyVaultCertificateWithPolicy>>

beginDeleteCertificate(string, CertificatePollerOptions)

The DELETE operation applies to any certificate stored in Azure Key Vault. DELETE cannot be applied to an individual version of a certificate. This function returns a Long Running Operation poller that allows you to wait indefinitely until the certificate is fully recovered.

This operation requires the certificates/delete permission.

Example usage:

const client = new CertificateClient(url, credentials);
const createPoller = await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
await createPoller.pollUntilDone();

const deletePoller = await client.beginDeleteCertificate("MyCertificate");

// Serializing the poller
const serialized = deletePoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginDeleteCertificate("MyCertificate", { resumeFrom: serialized });

// Waiting until it's done
const deletedCertificate = await deletePoller.pollUntilDone();
console.log(deletedCertificate);

Deletes a certificate from a specified key vault.

function beginDeleteCertificate(certificateName: string, options?: CertificatePollerOptions): Promise<PollerLike<DeleteCertificateState, DeletedCertificate>>

Parameters

certificateName

string

The name of the certificate.

options
CertificatePollerOptions

The optional parameters

Returns

Promise<PollerLike<DeleteCertificateState, DeletedCertificate>>

beginRecoverDeletedCertificate(string, CertificatePollerOptions)

Recovers the deleted certificate in the specified vault. This operation can only be performed on a soft-delete enabled vault. This operation This function returns a Long Running Operation poller that allows you to wait indefinitely until the certificate is fully recovered.

This operation requires the certificates/recover permission.

Example usage:

const client = new CertificateClient(url, credentials);

const deletePoller = await client.beginDeleteCertificate("MyCertificate");
await deletePoller.pollUntilDone();

const recoverPoller = await client.beginRecoverDeletedCertificate("MyCertificate");

// Serializing the poller
const serialized = deletePoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginRecoverDeletedCertificate("MyCertificate", { resumeFrom: serialized });

// Waiting until it's done
const certificate = await recoverPoller.pollUntilDone();
console.log(certificate);

Recovers a deleted certificate

function beginRecoverDeletedCertificate(certificateName: string, options?: CertificatePollerOptions): Promise<PollerLike<RecoverDeletedCertificateState, KeyVaultCertificateWithPolicy>>

Parameters

certificateName

string

The name of the deleted certificate

options
CertificatePollerOptions

The optional parameters

Returns

Promise<PollerLike<RecoverDeletedCertificateState, KeyVaultCertificateWithPolicy>>

createIssuer(string, string, CreateIssuerOptions)

The createIssuer operation adds or updates the specified certificate issuer. This operation requires the certificates/setissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Test");

Sets the specified certificate issuer.

function createIssuer(issuerName: string, provider: string, options?: CreateIssuerOptions): Promise<CertificateIssuer>

Parameters

issuerName

string

The name of the issuer.

provider

string

The issuer provider.

options
CreateIssuerOptions

The optional parameters

Returns

Promise<CertificateIssuer>

deleteCertificateOperation(string, OperationOptions)

Deletes the creation operation for a specified certificate that is in the process of being created. The certificate is no longer created. This operation requires the certificates/update permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
await client.deleteCertificateOperation("MyCertificate");
await client.getCertificateOperation("MyCertificate"); // Throws error: Pending certificate not found: "MyCertificate"

Delete a certificate's operation

function deleteCertificateOperation(certificateName: string, options?: OperationOptions): Promise<CertificateOperation>

Parameters

certificateName

string

The name of the certificate

options
OperationOptions

The optional parameters

Returns

Promise<CertificateOperation>

deleteContacts(OperationOptions)

Deletes all of the certificate contacts. This operation requires the certificates/managecontacts permission.

Example usage:

let client = new CertificateClient(url, credentials);
await client.setContacts([{
  email: "b@b.com",
  name: "b",
  phone: "222222222222"
}]);
await client.deleteContacts();

Deletes all of the certificate contacts

function deleteContacts(options?: OperationOptions): Promise<undefined | CertificateContact[]>

Parameters

options
OperationOptions

The optional parameters

Returns

Promise<undefined | CertificateContact[]>

deleteIssuer(string, OperationOptions)

The deleteIssuer operation permanently removes the specified certificate issuer from the vault. This operation requires the certificates/manageissuers/deleteissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Provider");
await client.deleteIssuer("IssuerName");

Deletes the specified certificate issuer.

function deleteIssuer(issuerName: string, options?: OperationOptions): Promise<CertificateIssuer>

Parameters

issuerName

string

The name of the issuer.

options
OperationOptions

The optional parameters

Returns

Promise<CertificateIssuer>

getCertificate(string, OperationOptions)

Gets the latest information available from a specific certificate, including the certificate's policy. This operation requires the certificates/get permission.

Example usage:

const client = new CertificateClient(url, credentials);
const poller = await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
await poller.pollUntilDone();
const certificate = await client.getCertificate("MyCertificate");
console.log(certificate);

Retrieves a certificate from the certificate's name (includes the certificate policy)

function getCertificate(certificateName: string, options?: OperationOptions): Promise<KeyVaultCertificateWithPolicy>

Parameters

certificateName

string

The name of the certificate

options
OperationOptions

The optional parameters

Returns

Promise<KeyVaultCertificateWithPolicy>

getCertificateOperation(string, CertificatePollerOptions)

Gets the creation operation associated with a specified certificate. This operation requires the certificates/get permission. This function returns a Long Running Operation poller that allows you to wait indefinitely until the certificate is fully recovered.

Example usage:

const client = new CertificateClient(url, credentials);
const createPoller = await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});

const poller = await client.getCertificateOperation("MyCertificate");
const pendingCertificate = poller.getResult();

const certificateOperation = poller.getOperationState().certificateOperation;
console.log(certificateOperation);

Gets a certificate's poller operation

function getCertificateOperation(certificateName: string, options?: CertificatePollerOptions): Promise<PollerLikeWithCancellation<CertificateOperationState, KeyVaultCertificateWithPolicy>>

Parameters

certificateName

string

The name of the certificate

options
CertificatePollerOptions

The optional parameters

Returns

Promise<PollerLikeWithCancellation<CertificateOperationState, KeyVaultCertificateWithPolicy>>

getCertificatePolicy(string, OperationOptions)

The getCertificatePolicy operation returns the specified certificate policy resources in the specified key vault. This operation requires the certificates/get permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
const policy = await client.getCertificatePolicy("MyCertificate");
console.log(policy);

Gets a certificate's policy

function getCertificatePolicy(certificateName: string, options?: OperationOptions): Promise<CertificatePolicy>

Parameters

certificateName

string

The name of the certificate

options
OperationOptions

The optional parameters

Returns

Promise<CertificatePolicy>

getCertificateVersion(string, string, OperationOptions)

Gets information about a specific certificate on a specific version. It won't return the certificate's policy. This operation requires the certificates/get permission.

Example usage:

const client = new CertificateClient(url, credentials);
const poller = await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
await poller.pollUntilDone();
const certificateWithPolicy = await client.getCertificate("MyCertificate");
const certificate = await client.getCertificateVersion("MyCertificate", certificateWithPolicy.properties.version!);
console.log(certificate);

Retrieves a certificate from the certificate's name and a specified version

function getCertificateVersion(certificateName: string, version: string, options?: OperationOptions): Promise<KeyVaultCertificate>

Parameters

certificateName

string

The name of the certificate

version

string

The specific version of the certificate

options
OperationOptions

The optional parameters

Returns

Promise<KeyVaultCertificate>

getContacts(OperationOptions)

Returns the set of certificate contact resources in the specified key vault. This operation requires the certificates/managecontacts permission.

Example usage:

let client = new CertificateClient(url, credentials);
await client.setContacts([{
  email: "b@b.com",
  name: "b",
  phone: "222222222222"
}]);
const contacts = await client.getContacts();
console.log(contacts);

Sets the certificate contacts.

function getContacts(options?: OperationOptions): Promise<undefined | CertificateContact[]>

Parameters

options
OperationOptions

The optional parameters

Returns

Promise<undefined | CertificateContact[]>

getDeletedCertificate(string, OperationOptions)

retrieves the deleted certificate information plus its attributes, such as retention interval, scheduled permanent deletion and the current deletion recovery level. This operation requires the certificates/get permission.

Example usage:

const client = new CertificateClient(url, credentials);
const deletedCertificate = await client.getDeletedCertificate("MyDeletedCertificate");
console.log("Deleted certificate:", deletedCertificate);

Gets a deleted certificate

function getDeletedCertificate(certificateName: string, options?: OperationOptions): Promise<DeletedCertificate>

Parameters

certificateName

string

The name of the certificate

options
OperationOptions

The optional parameters

Returns

Promise<DeletedCertificate>

getIssuer(string, OperationOptions)

The getIssuer operation returns the specified certificate issuer resources in the specified key vault. This operation requires the certificates/manageissuers/getissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Test");
const certificateIssuer = await client.getIssuer("IssuerName");
console.log(certificateIssuer);

Gets he specified certificate issuer.

function getIssuer(issuerName: string, options?: OperationOptions): Promise<CertificateIssuer>

Parameters

issuerName

string

The name of the issuer.

options
OperationOptions

The optional parameters

Returns

Promise<CertificateIssuer>

importCertificate(string, Uint8Array, ImportCertificateOptions)

Imports an existing valid certificate, containing a private key, into Azure Key Vault. The certificate to be imported can be in either PFX or PEM format. If the certificate is in PEM format the PEM file must contain the key as well as x509 certificates. This operation requires the certificates/import permission.

Example usage:

const client = new CertificateClient(url, credentials);
// See: @azure/keyvault-secrets
const certificateSecret = await secretClient.getSecret("MyCertificate");
const base64EncodedCertificate = certificateSecret.value!;
let buffer: Uint8Array;

if (isNode) {
  buffer = Buffer.from(base64EncodedCertificate, "base64");
} else {
  buffer = Uint8Array.from(atob(base64EncodedCertificate), (c) => c.charCodeAt(0));
}

await client.importCertificate("MyCertificate", buffer);

Imports a certificate from a certificate's secret value

function importCertificate(certificateName: string, certificateBytes: Uint8Array, options?: ImportCertificateOptions): Promise<KeyVaultCertificateWithPolicy>

Parameters

certificateName

string

The name of the certificate

certificateBytes

Uint8Array

The PFX or ASCII PEM formatted value of the certificate containing both the X.509 certificates and the private key

options
ImportCertificateOptions

The optional parameters

Returns

Promise<KeyVaultCertificateWithPolicy>

listDeletedCertificates(ListDeletedCertificatesOptions)

Retrieves the certificates in the current vault which are in a deleted state and ready for recovery or purging. This operation includes deletion-specific information. This operation requires the certificates/get/list permission. This operation can only be enabled on soft-delete enabled vaults.

Example usage:

const client = new CertificateClient(url, credentials);
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log(deletedCertificate);
}
for await (const page of client.listDeletedCertificates().byPage()) {
  for (const deletedCertificate of page) {
    console.log(deletedCertificate);
  }
}

Lists deleted certificates

function listDeletedCertificates(options?: ListDeletedCertificatesOptions): PagedAsyncIterableIterator<DeletedCertificate, DeletedCertificate[], PageSettings>

Parameters

options
ListDeletedCertificatesOptions

The optional parameters

Returns

PagedAsyncIterableIterator<DeletedCertificate, DeletedCertificate[], PageSettings>

listPropertiesOfCertificates(ListPropertiesOfCertificatesOptions)

Iterates the latest version of all certificates in the vault. The full certificate identifier and attributes are provided in the response. No values are returned for the certificates. This operations requires the certificates/list permission.

Example usage:

const client = new CertificateClient(url, credentials);
// All in one call
for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log(certificateProperties);
}
// By pages
for await (const page of client.listPropertiesOfCertificates().byPage()) {
  for (const certificateProperties of page) {
    console.log(certificateProperties);
  }
}

List all versions of the specified certificate.

function listPropertiesOfCertificates(options?: ListPropertiesOfCertificatesOptions): PagedAsyncIterableIterator<CertificateProperties, CertificateProperties[], PageSettings>

Parameters

options
ListPropertiesOfCertificatesOptions

The optional parameters

Returns

PagedAsyncIterableIterator<CertificateProperties, CertificateProperties[], PageSettings>

listPropertiesOfCertificateVersions(string, OperationOptions)

Returns the versions of a certificate in the specified key vault. This operation requires the certificates/list permission.

Example usage:

const client = new CertificateClient(url, credentials);
for await (const certificateProperties of client.listPropertiesOfCertificateVersions("MyCertificate")) {
  console.log(certificateProperties.version!);
}

List the versions of a certificate.

function listPropertiesOfCertificateVersions(certificateName: string, options?: OperationOptions): PagedAsyncIterableIterator<CertificateProperties, CertificateProperties[], PageSettings>

Parameters

certificateName

string

The name of the certificate.

options
OperationOptions

The optional parameters

Returns

PagedAsyncIterableIterator<CertificateProperties, CertificateProperties[], PageSettings>

listPropertiesOfIssuers(OperationOptions)

Returns the set of certificate issuer resources in the specified key vault. This operation requires the certificates/manageissuers/getissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Test");
// All in one call
for await (const issuerProperties of client.listPropertiesOfIssuers()) {
  console.log(issuerProperties);
}
// By pages
for await (const page of client.listPropertiesOfIssuers().byPage()) {
  for (const issuerProperties of page) {
    console.log(issuerProperties);
  }
}

List the certificate issuers.

function listPropertiesOfIssuers(options?: OperationOptions): PagedAsyncIterableIterator<IssuerProperties, IssuerProperties[], PageSettings>

Parameters

options
OperationOptions

The optional parameters

Returns

PagedAsyncIterableIterator<IssuerProperties, IssuerProperties[], PageSettings>

mergeCertificate(string, Uint8Array[], OperationOptions)

Performs the merging of a certificate or certificate chain with a key pair currently available in the service. This operation requires the certificates/create permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Unknown",
  subject: "cn=MyCert"
});
const poller = await client.getCertificateOperation("MyCertificate");
const { csr } = poller.getOperationState().certificateOperation!;
const base64Csr = Buffer.from(csr!).toString("base64");
const wrappedCsr = ["-----BEGIN CERTIFICATE REQUEST-----", base64Csr, "-----END CERTIFICATE REQUEST-----"].join("\n");

const fs = require("fs");
fs.writeFileSync("test.csr", wrappedCsr);

// Certificate available locally made using:
//   openssl genrsa -out ca.key 2048
//   openssl req -new -x509 -key ca.key -out ca.crt
// You can read more about how to create a fake certificate authority here: https://gist.github.com/Soarez/9688998

const childProcess = require("child_process");
childProcess.execSync("openssl x509 -req -in test.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out test.crt");
const base64Crt = fs.readFileSync("test.crt").toString().split("\n").slice(1, -1).join("");

await client.mergeCertificate("MyCertificate", [Buffer.from(base64Crt)]);

Merges a signed certificate request into a pending certificate

function mergeCertificate(certificateName: string, x509Certificates: Uint8Array[], options?: OperationOptions): Promise<KeyVaultCertificateWithPolicy>

Parameters

certificateName

string

The name of the certificate

x509Certificates

Uint8Array[]

The certificate(s) to merge

options
OperationOptions

The optional parameters

Returns

Promise<KeyVaultCertificateWithPolicy>

purgeDeletedCertificate(string, OperationOptions)

Performs an irreversible deletion of the specified certificate, without possibility for recovery. The operation is not available if the recovery level does not specify 'Purgeable'. This operation requires the certificate/purge permission.

Example usage:

const client = new CertificateClient(url, credentials);
const deletePoller = await client.beginDeleteCertificate("MyCertificate");
await deletePoller.pollUntilDone();
// Deleting a certificate takes time, make sure to wait before purging it
client.purgeDeletedCertificate("MyCertificate");

Gets a deleted certificate

function purgeDeletedCertificate(certificateName: string, options?: OperationOptions): Promise<null>

Parameters

certificateName

string

The name of the deleted certificate to purge

options
OperationOptions

The optional parameters

Returns

Promise<null>

restoreCertificateBackup(Uint8Array, OperationOptions)

Restores a backed up certificate, and all its versions, to a vault. This operation requires the certificates/restore permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});
const backup = await client.backupCertificate("MyCertificate");
const poller = await client.beginDeleteCertificate("MyCertificate");
await poller.pollUntilDone();
// Some time is required before we're able to restore the certificate
await client.restoreCertificateBackup(backup!);

Restores a certificate from a backup

function restoreCertificateBackup(backup: Uint8Array, options?: OperationOptions): Promise<KeyVaultCertificateWithPolicy>

Parameters

backup

Uint8Array

The back-up certificate to restore from

options
OperationOptions

The optional parameters

Returns

Promise<KeyVaultCertificateWithPolicy>

setContacts(CertificateContact[], OperationOptions)

Sets the certificate contacts for the key vault. This operation requires the certificates/managecontacts permission.

Example usage:

let client = new CertificateClient(url, credentials);
await client.setContacts([{
  email: "b@b.com",
  name: "b",
  phone: "222222222222"
}]);

Sets the certificate contacts.

function setContacts(contacts: CertificateContact[], options?: OperationOptions): Promise<undefined | CertificateContact[]>

Parameters

contacts

CertificateContact[]

The contacts to use

options
OperationOptions

The optional parameters

Returns

Promise<undefined | CertificateContact[]>

updateCertificatePolicy(string, CertificatePolicy, OperationOptions)

Updates the certificate policy for the specified certificate. This operation requires the certificates/update permission. Gets a certificate's policy

function updateCertificatePolicy(certificateName: string, policy: CertificatePolicy, options?: OperationOptions): Promise<CertificatePolicy>

Parameters

certificateName

string

The name of the certificate

policy
CertificatePolicy

The certificate policy

options
OperationOptions

The optional parameters

Returns

Promise<CertificatePolicy>

updateCertificateProperties(string, string, UpdateCertificatePropertiesOptions)

Applies the specified update on the given certificate; the only elements updated are the certificate's attributes. This operation requires the certificates/update permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.beginCreateCertificate("MyCertificate", {
  issuerName: "Self",
  subject: "cn=MyCert"
});

// You may pass an empty string for version which will update
// the latest version of the certificate
await client.updateCertificateProperties("MyCertificate", "", {
  tags: {
    customTag: "value"
  }
});

Updates a certificate

function updateCertificateProperties(certificateName: string, version: string, options?: UpdateCertificatePropertiesOptions): Promise<KeyVaultCertificate>

Parameters

certificateName

string

The name of the certificate

version

string

The version of the certificate to update (an empty string will update the latest version)

options
UpdateCertificateOptions

The options, including what to update

Returns

Promise<KeyVaultCertificate>

updateIssuer(string, UpdateIssuerOptions)

The updateIssuer operation performs an update on the specified certificate issuer entity. This operation requires the certificates/setissuers permission.

Example usage:

const client = new CertificateClient(url, credentials);
await client.createIssuer("IssuerName", "Test");
await client.updateIssuer("IssuerName", {
  provider: "Provider2"
});

Updates the specified certificate issuer.

function updateIssuer(issuerName: string, options?: UpdateIssuerOptions): Promise<CertificateIssuer>

Parameters

issuerName

string

The name of the issuer.

options
UpdateIssuerOptions

The optional parameters

Returns

Promise<CertificateIssuer>