secrets-Spec.md

SecretClient

public class SecretAsyncClient extends ServiceClient
{
    // constructors
    private SecretClient(String vaultUrl, HttpPipeline pipeline);
    
    public static SecretAsyncClientBuilder builder() {
        return new SecretAsyncClientBuilder();
    }

    // methods
    public Mono<Response<Secret>> getSecret(String secretName);
    public Mono<Response<Secret>> getSecret(String secretName, String version);

    public Flux<SecretBase> listSecretVersions(String name);
    public Flux<SecretBase> listSecrets();
    
    public Mono<Response<SecretBase>> updateSecret(SecretBase secret);

    public Mono<Response<Secret>> setSecret(String name, String value);
    public Mono<Response<Secret>> setSecret(Secret secret);

    public Mono<Response<DeletedSecret>> deleteSecret(String name);
    public Mono<Response<DeletedSecret>> getDeletedSecret(String name);
    public Flux<DeletedSecret> listDeletedSecrets();
    public Mono<Response<Secret>> recoverDeletedSecret(String name);
    public Mono<VoidResponse> purgeDeletedSecret(String name);

    public Mono<Response<byte[]>> backupSecret(String name);
    public Mono<Response<Secret>> restoreSecret(byte[] backup);
}

public static final class SecretAsyncClientBuilder {

    SecretAsyncClientBuilder() {
    }

    public SecretAsyncClient build() {
       //Validate and Build the Client
    }

    public SecretAsyncClientBuilder vaultEndpoint(String vaultEndpoint) {}

    public SecretAsyncClientBuilder credentials(ServiceClientCredentials credentials) {}

    public SecretAsyncClientBuilder httpLogDetailLevel(HttpLogDetailLevel logLevel) {}

    public SecretAsyncClientBuilder addPolicy(HttpPipelinePolicy policy) {}

    public SecretAsyncClientBuilder httpClient(HttpClient client) {}
}

public class SecretClient extends ServiceClient
{
    // constructors
    private SecretClient(String vaultUrl, HttpPipeline pipeline);
    
    public static SecretClientBuilder builder() {
        return new SecretClientBuilder();
    }

    // methods
    public Response<Secret> getSecret(String secretName);
    public Response<Secret> getSecret(String secretName, String version);

    public List<SecretBase> listSecretVersions(String name);
    public List<SecretBase> listSecrets();
    
    public Response<SecretBase> updateSecret(SecretBase secret);

    public Response<Secret> setSecret(String name, String value);
    public Response<Secret> setSecret(Secret secret);

    public Response<DeletedSecret> deleteSecret(String name);
    public Response<DeletedSecret> getDeletedSecret(String name);
    public List<DeletedSecret> listDeletedSecrets();
    public Response<Secret> recoverDeletedSecret(String name);
    public VoidResponse purgeDeletedSecret(String name);

    public Mono<Response<byte[]>> backupSecret(String name);
    public Mono<Response<Secret>> restoreSecret(byte[] backup);
}

public final class SecretClientBuilder {

    SecretClientBuilder() {
    }

    public SecretClient build() {
       //Validate and Build the Client
    }

    public Builder vaultEndpoint(String vaultEndpoint) {}

    public Builder credentials(ServiceClientCredentials credentials) {}

    public Builder httpLogDetailLevel(HttpLogDetailLevel logLevel) {}

    public Builder addPolicy(HttpPipelinePolicy policy) {}

    public Builder httpClient(HttpClient client) {}
}

Get / Set Operations

SecretClient Set Secret operations

public Mono<RestResponse<Secret>> setSecretAsync(String name, String value);
public Mono<RestResponse<Secret>> setSecretAsync(Secret secret);

Usage:

SecretClient secretClient = SecretClient.builder()
                            .vaultEndpoint("https://myvault.vault.azure.net/")
                            .credentials(new KeyvaultCredentials())
                            .httpLogDetailLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
                            .build();            

// set a simple secret such as password
Secret passwordSecret = secretClient.setSecretAsync("user1pass", "password").block().body();

// set a symmetric key secret with nbf and exp
String encodeString = Base64.getEncoder().encodeToString(("password2").getBytes());

Secret keySecret = new Secret("secretkey", encodeString)
        .withContentType("application/octet-stream")
        .withNotBefore(OffsetDateTime.of(LocalDateTime.parse("2000-01-01 00:00", DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm")),ZoneOffset.UTC))
        .withExpires(OffsetDateTime.of(LocalDateTime.parse("2050-01-01 00:00", DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm")),ZoneOffset.UTC));

Secret retKeySecret = secretClient.setSecretAsync(keySecret).block().body();

Replaces:

ServiceFuture<SecretBundle> setSecretAsync(String vaultBaseUrl, String secretName, String value, final  ServiceCallback<SecretBundle> serviceCallback);
Observable<SecretBundle> setSecretAsync(String vaultBaseUrl, String secretName, String value);
Observable<ServiceResponse<SecretBundle>> setSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName, String value);
ServiceFuture<SecretBundle> setSecretAsync(String vaultBaseUrl, String secretName, String value, Map<String, String> tags, String contentType, SecretAttributes secretBase, final ServiceCallback<SecretBundle> serviceCallback);
Observable<SecretBundle> setSecretAsync(String vaultBaseUrl, String secretName, String value, Map<String, String> tags, String contentType, SecretAttributes secretBase);
Observable<ServiceResponse<SecretBundle>> setSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName, String value, Map<String, String> tags, String contentType, SecretAttributes secretBase);

Usage:

// TODO: Add Track one Set Secret usage examples.

SecretClient Get Secret Operations

public Mono<RestResponse<Secret>> getSecretAsync(String secretName);
public Mono<RestResponse<Secret>> getSecretAsync(String secretName, String version);

Usage:

// get the latest version of a secret
Secret secret = secretClient.getSecretAsync("user1pass").block().body();

// get a specific version of a secret
Secret secretWithVersion = secretClient.getSecretAsync("user1pass","6A385B124DEF4096AF1361A85B16C204").block().body();

Replaces:

ServiceFuture<SecretBundle> getSecretAsync(String secretIdentifier, final ServiceCallback<SecretBundle> serviceCallback);
ServiceFuture<SecretBundle> getSecretAsync(String vaultBaseUrl, String secretName, final ServiceCallback<SecretBundle> serviceCallback);
ServiceFuture<SecretBundle> getSecretAsync(String vaultBaseUrl, String secretName, String secretVersion, final ServiceCallback<SecretBundle> serviceCallback);
Observable<SecretBundle> getSecretAsync(String vaultBaseUrl, String secretName, String secretVersion);
Observable<ServiceResponse<SecretBundle>> getSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName, String secretVersion);

Usage:

// TODO: Add Track one Get Secret usage examples.

Update Secret Operation

public Mono<RestResponse<SecretAttributes>> updateSecretAsync(SecretAttributes secret);

Usage:

// Update the expiration of a secret
Secret secret = secretClient.getSecretAsync("secretkey").block().body();

secret.withNotBefore(OffsetDateTime.of(LocalDateTime.parse("2020-01-01 00:00", DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm")),ZoneOffset.UTC));

SecretInfo updatedInfo = secretClient.updateSecretAsync(secret).block().body();

Replaces:

Observable<SecretBundle> updateSecretAsync(String vaultBaseUrl, String secretName, String secretVersion);
Observable<ServiceResponse<SecretBundle>> updateSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName, String secretVersion);
SecretBundle updateSecret(String vaultBaseUrl, String secretName, String secretVersion, String contentType, SecretAttributes secretBase, Map<String, String> tags);
ServiceFuture<SecretBundle> updateSecretAsync(String vaultBaseUrl, String secretName, String secretVersion, String contentType, SecretAttributes secretBase, Map<String, String> tags, final ServiceCallback<SecretBundle> serviceCallback);
Observable<SecretBundle> updateSecretAsync(String vaultBaseUrl, String secretName, String secretVersion, String contentType, SecretAttributes secretBase, Map<String, String> tags);
Observable<ServiceResponse<SecretBundle>> updateSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName, String secretVersion, String contentType, SecretAttributes secretBase, Map<String, String> tags);

Usage:

// TODO: Add Track one Update Secret usage examples.

List Operations

listSecretsAsync, listSecretVersionsAsync

public Flux<SecretAttributes> getSecretVersionsAsync(String name);
public Flux<SecretAttributes> getSecretVersionsAsync(String name, int maxPageResults);
public Flux<SecretAttributes> getSecretsAsync();
public Flux<SecretAttributes> getSecretsAsync(int maxPageResults);

Usage:

// enumerate all secrets in the vault using Flux subscribe - TO BE TESTED.
secretClient.listSecretsAsync()
	.subscribe(secretInfo -> System.out.println(secretInfo.id()));

int maxPageResults = 5;
secretClient.listSecretsAsync(5)
	.subscribe(secretInfo -> System.out.println(secretInfo.id()));

Replaces:

ServiceFuture<List<SecretItem>> getSecretsAsync(final String vaultBaseUrl, final ListOperationCallback<SecretItem> serviceCallback);
Observable<Page<SecretItem>> getSecretsAsync(final String vaultBaseUrl);
Observable<ServiceResponse<Page<SecretItem>>> getSecretsWithServiceResponseAsync(final String vaultBaseUrl);
ServiceFuture<List<SecretItem>> getSecretsAsync(final String vaultBaseUrl, final Integer maxresults, final ListOperationCallback<SecretItem> serviceCallback);
Observable<Page<SecretItem>> getSecretsAsync(final String vaultBaseUrl, final Integer maxresults);
Observable<ServiceResponse<Page<SecretItem>>> getSecretsWithServiceResponseAsync(final String vaultBaseUrl, final Integer maxresults);
ServiceFuture<List<SecretItem>> getSecretsNextAsync(final String nextPageLink, final ServiceFuture<List<SecretItem>> serviceFuture, final ListOperationCallback<SecretItem> serviceCallback);
Observable<Page<SecretItem>> getSecretsNextAsync(final String nextPageLink);
Observable<ServiceResponse<Page<SecretItem>>> getSecretsNextWithServiceResponseAsync(final String nextPageLink);
ServiceFuture<List<SecretItem>> getSecretVersionsAsync(final String vaultBaseUrl, final String secretName, final ListOperationCallback<SecretItem> serviceCallback);
Observable<Page<SecretItem>> getSecretVersionsAsync(final String vaultBaseUrl, final String secretName);
Observable<ServiceResponse<Page<SecretItem>>> getSecretVersionsWithServiceResponseAsync(final String vaultBaseUrl, final String secretName);
ServiceFuture<List<SecretItem>> getSecretVersionsAsync(final String vaultBaseUrl, final String secretName, final Integer maxresults, final ListOperationCallback<SecretItem> serviceCallback);
Observable<Page<SecretItem>> getSecretVersionsAsync(final String vaultBaseUrl, final String secretName, final Integer maxresults);
Observable<ServiceResponse<Page<SecretItem>>> getSecretVersionsWithServiceResponseAsync(final String vaultBaseUrl, final String secretName, final Integer maxresults);
ServiceFuture<List<SecretItem>> getSecretVersionsNextAsync(final String nextPageLink, final ServiceFuture<List<SecretItem>> serviceFuture, final ListOperationCallback<SecretItem> serviceCallback);
Observable<Page<SecretItem>> getSecretVersionsNextAsync(final String nextPageLink);
Observable<ServiceResponse<Page<SecretItem>>> getSecretVersionsNextWithServiceResponseAsync(final String nextPageLink);

Usage:

// TODO: Add Track one List Secret usage examples.

Deleted Secret Operations

deleteSecretAsync, getDeletedSecretAsync, getDeletedSecretsAsync, recoverDeletedSecretAsync, purgeDeletedSecretAsync

public Mono<RestResponse<DeletedSecret>> deleteSecretAsync(string name);
public Mono<RestResponse<DeletedSecret>> getDeletedSecretAsync(string name);
public Flux<DeletedSecret> getDeletedSecretsAsync();
public Flux<DeletedSecret> getDeletedSecretsAsync(int maxPageResults);
public Mono<RestResponse<Secret>> recoverDeletedSecretAsync(string name);
public Mono<RestResponse> purgeDeletedSecretAsync(string name);

Usage:

// Delete a secret
DeletedSecret deletedSecret =  secretClient.deleteSecretAsync("user1pass").block().body();

// Wait for few seconds.
Thread.sleep(5000);

// Get the details of a deleted secret
 deletedSecret = secretClient.getDeletedSecretAsync("user1pass").block().body();

// List all the deleted secrets
secretClient.listDeletedSecretsAsync()
	.subscribe(delSecret -> System.out.println(delSecret.id()));

// Recover a deleted secret
Secret secret = secretClient.recoverDeletedSecretAsync("user1pass").block().body();

// Wait for few seconds.
Thread.sleep(5000);

// Delete the secret again after recovering it.
deletedSecret =  secretClient.deleteSecretAsync("user1pass").block().body();

// Wait for few seconds.
Thread.sleep(5000);

// Purge the deleted secret -- permanenetly delete it.
secretClient.purgeDeletedSecretAsync("user1pass").block();

Replaces:

ServiceFuture<DeletedSecretBundle> deleteSecretAsync(String vaultBaseUrl, String secretName, final ServiceCallback<DeletedSecretBundle> serviceCallback);
Observable<DeletedSecretBundle> deleteSecretAsync(String vaultBaseUrl, String secretName);
Observable<ServiceResponse<DeletedSecretBundle>> deleteSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName);
ServiceFuture<List<DeletedSecretItem>> getDeletedSecretsAsync(final String vaultBaseUrl, final ListOperationCallback<DeletedSecretItem> serviceCallback);
Observable<Page<DeletedSecretItem>> getDeletedSecretsAsync(final String vaultBaseUrl);
Observable<ServiceResponse<Page<DeletedSecretItem>>> getDeletedSecretsWithServiceResponseAsync(final String vaultBaseUrl);
PagedList<DeletedSecretItem> getDeletedSecrets(final String vaultBaseUrl, final Integer maxresults);
Observable<Page<DeletedSecretItem>> getDeletedSecretsAsync(final String vaultBaseUrl, final Integer maxresults);
Observable<ServiceResponse<Page<DeletedSecretItem>>> getDeletedSecretsWithServiceResponseAsync(final String vaultBaseUrl, final Integer maxresults);
ServiceFuture<DeletedSecretBundle> getDeletedSecretAsync(String vaultBaseUrl, String secretName, final ServiceCallback<DeletedSecretBundle> serviceCallback);
Observable<DeletedSecretBundle> getDeletedSecretAsync(String vaultBaseUrl, String secretName);
Observable<ServiceResponse<DeletedSecretBundle>> getDeletedSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName);
ServiceFuture<List<DeletedSecretItem>> getDeletedSecretsNextAsync(final String nextPageLink, final ServiceFuture<List<DeletedSecretItem>> serviceFuture, final ListOperationCallback<DeletedSecretItem> serviceCallback);
Observable<Page<DeletedSecretItem>> getDeletedSecretsNextAsync(final String nextPageLink);
Observable<ServiceResponse<Page<DeletedSecretItem>>> getDeletedSecretsNextWithServiceResponseAsync(final String nextPageLink);
ServiceFuture<SecretBundle> recoverDeletedSecretAsync(String vaultBaseUrl, String secretName, final ServiceCallback<SecretBundle> serviceCallback);
Observable<SecretBundle> recoverDeletedSecretAsync(String vaultBaseUrl, String secretName);
Observable<ServiceResponse<SecretBundle>> recoverDeletedSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName);
ServiceFuture<Void> purgeDeletedSecretAsync(String vaultBaseUrl, String secretName, final ServiceCallback<Void> serviceCallback);
Observable<Void> purgeDeletedSecretAsync(String vaultBaseUrl, String secretName);
Observable<ServiceResponse<Void>> purgeDeletedSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName);

Usage:

// TODO: Add Track one Delete, Recover and Purge Secret usage examples.

backupSecretAsync, restoreSecretAsync

public Mono<RestResponse<byte[]>> backupSecretAsync(string name);
public Mono<RestResponse<Secret>> restoreSecretAsync(byte[] backup);

Usage:

// backup the secret
SecretBackup backup = secretClient.backupSecretAsync("secretkey").block().body();

DeletedSecret deletedSecret =  secretClient.deleteSecretAsync("secretkey").block().body();

Thread.sleep(30000);

secretClient.purgeDeletedSecretAsync("secretkey").block();

//restore the secret from backup
Secret restored = secretClient.restoreSecretAsync(backup).block().body();

Replaces:

ServiceFuture<BackupSecretResult> backupSecretAsync(String vaultBaseUrl, String secretName, final ServiceCallback<BackupSecretResult> serviceCallback);
Observable<BackupSecretResult> backupSecretAsync(String vaultBaseUrl, String secretName);
Observable<ServiceResponse<BackupSecretResult>> backupSecretWithServiceResponseAsync(String vaultBaseUrl, String secretName);
ServiceFuture<SecretBundle> restoreSecretAsync(String vaultBaseUrl, byte[] secretBundleBackup, final ServiceCallback<SecretBundle> serviceCallback);
Observable<SecretBundle> restoreSecretAsync(String vaultBaseUrl, byte[] secretBundleBackup);
Observable<ServiceResponse<SecretBundle>> restoreSecretWithServiceResponseAsync(String vaultBaseUrl, byte[] secretBundleBackup);

Usage:

// TODO: Add Track one Backup and Restore Secret usage examples.