# Rust SDK

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F6YSOQI8zWNP3zQIkfHdI%2FKSM%20%2B%20Rust%20Icon.png?alt=media&#x26;token=18a7851d-7a71-47c1-af38-4b1970cb3250" alt=""><figcaption></figcaption></figure>

### Download and Installation

#### Adding as Package using Cargo

```
cargo add keeper-secrets-manager-core
```

#### Source Code

Find the Rust source code in the [GitHub repository](https://github.com/Keeper-Security/secrets-manager/tree/master/sdk/rust)

### Using the SDK

### Initialise

{% hint style="info" %}
Using token only to generate a new config (for later usage) requires at least one read operation to bind the token and fully populate `config.json`
{% endhint %}

{% tabs %}
{% tab title="Secrets Manager" %}

```python
SecretsManager::new(client_options)?
```

{% endtab %}

{% tab title="Example Usage" %}

```rust
use keeper_secrets_manager_core::{ClientOptions, SecretsManager,storage::FileKeyValueStorage}

fn main()-> Result<(), KSMRError>{
    let client_options = ClientOptions::new_client_options_with_token(token, config);
    let mut secrets_manager = SecretsManager::new(client_options)?;
    Ok(())
}
```

{% endtab %}
{% endtabs %}

<table data-header-hidden><thead><tr><th width="150">Parameter</th><th width="150">Required</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Description</td><td>Type</td></tr><tr><td>token</td><td>Yes</td><td>One Time Access Token</td><td>String</td></tr><tr><td>config</td><td>Yes</td><td>Storage Configuration</td><td><code>KeyValueStorage</code></td></tr></tbody></table>

### Retrieve Secrets

{% tabs %}
{% tab title="Get Secrets" %}

```python
let records_filter = Vec::new(); // add record filters of needed based on UID
let secrets = secrets_manager.get_secrets(records_filter)?;
```

{% endtab %}

{% tab title="Example: Get All Secrets" %}

```rust
use keeper_secrets_manager_core::{core::{ClientOptions, SecretsManager}, custom_error::KSMRError, storage::FileKeyValueStorage};

fn main()-> Result<(), KSMRError>{
    let token = "<Your One time token>".to_string();
    let file_name = FileKeyValueStorage::new_config_storage("test.json".to_string())?;
    let client_options = ClientOptions::new_client_options(token, file_name); 
    
    let mut secrets_manager = SecretsManager::new(client_options)?;
    let secrets = secrets_manager.get_secrets(Vec::new())?;

    for secret in secrets {
        secret.print();
        println!("---");
    }
    Ok(())
}
```

{% endtab %}

{% tab title="Example: Get Secrets With a Filter" %}

```python
use keeper_secrets_manager_core::{core::{ClientOptions, SecretsManager}, custom_error::KSMRError, storage::FileKeyValueStorage};

fn main()-> Result<(), KSMRError>{
    let token = "<Your One time token>".to_string();
    let file_name = FileKeyValueStorage::new_config_storage("test.json".to_string())?;
    let client_options = ClientOptions::new_client_options(token, file_name); 
    
    let mut secrets_manager = SecretsManager::new(client_options)?;
    let records_filter = vec!["record_uid1","record_uid2"]; // add record filters of needed based on UID
    let secrets = secrets_manager.get_secrets(records_filter)?;

    for secret in secrets {
        secret.print();
        println!("---");
    }
    Ok(())
}
```

{% endtab %}
{% endtabs %}

<table data-header-hidden><thead><tr><th width="150">Parameter</th><th width="150">Type</th><th width="150">Required</th><th width="150">Default</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Required</td><td>Default</td><td>Description</td></tr><tr><td><code>uids</code></td><td><code>Vec&#x3C;String></code></td><td>Optional</td><td>None</td><td>Record UIDs to fetch</td></tr></tbody></table>

**Response**

Type: `Vec<Record>`

All Keeper records, or records with the given UIDs

> default - we will get all records which the token given has access to

### Retrieve Values from secret

#### Retrieve a password

This shortcut gets the password of a secret once that secret has been retrieved from Keeper Secrets Manager.

{% tabs %}
{% tab title="Get Password" %}

```rust
secret.get_standard_field_value('password', true);
```

{% endtab %}

{% tab title="Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by record UID
    let secrets = secrets_manager.get_secrets(vec!["record_uid".to_string()])?;
    let secret = match secrets.len(){
        0 => return Err(KSMRError::CustomError("no secret with given uid is found".to_string())),
        _ => &secrets[0],
    };
    // get password from record
    let my_secret_password = secret.get_standard_field_value("password", true);
    Ok(())
}
```

{% endtab %}
{% endtabs %}

#### Retrieve Standard Fields

{% tabs %}
{% tab title="Standard Field" %}

```rust
secret.get_standard_field_value(“FIELD_TYPE”.to_string(), true);
```

{% endtab %}

{% tab title="Standard Field Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::FileKeyValueStorage,
    custom_error::KSMRError,
    enums::StandardFieldTypeEnum
};

fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let token = "your_token_goes_here".to_string();
    let config = FileKeyValueStorage::new_config_storage("test.json".to_string())?;
    let client_options = ClientOptions::new_client_options_with_token(token, config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by record UID
    let secrets = secrets_manager.get_secrets(vec!["record_uid".to_string()])?;
    let secret = match secrets.len(){
        0 => return Err(KSMRError::CustomError("no secret with given uid is found".to_string())),
        _ => &secrets[0],
    };
    // use StandardFieldTypeEnum for getting accurate type for standard field without any typographic errors
    let login_field = StandardFieldTypeEnum::LOGIN.get_type().to_string();
    // get login field from the secret
    let my_secret_login = secret.get_standard_field_value(login_field, true)
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter    | Type      | Required | Default | Description                 |
| ------------ | --------- | -------- | ------- | --------------------------- |
| `field_type` | `String`  | Yes      | None    | Field type to get           |
| `single`     | `boolean` | Optional | False   | Return only the first value |

Field types are based on the Keeper [Record Type](https://app.gitbook.com/s/-LO5CAzpxoaEquZJBpYz/record-types). For a detailed list of available fields based on the Keeper Record Type, see the [record-type-info](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference/record-commands/record-type-commands#record-type-info-command) command in Keeper Commander.

#### Retrieve Custom Fields

{% tabs %}
{% tab title="Custom Field" %}

```rust
secret.get_custom_field_value(“FIELD_TYPE”, true);
```

{% endtab %}

{% tab title="Custom Field Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by record UID
    let secrets = secrets_manager.get_secrets(vec!["record_uid".to_string()])?;
    let secret = match secrets.len(){
        0 => return Err(KSMRError::CustomError("no secret with given uid is found".to_string())),
        _ => &secrets[0],
    };
    // Get a custom field, e.g. API Key
    let api_key = secret.get_custom_field_value(“API Key”, true)
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter    | Type      | Required | Default | Description                 |
| ------------ | --------- | -------- | ------- | --------------------------- |
| `field_type` | `String`  | Yes      | -       | Field type to get           |
| `single`     | `boolean` | Optional | False   | Return only the first value |

Custom fields are any field that is not part of the record type definition but can be added by users.

**Response**

> Type: `String` or `Vec<String>`

the value or values of the field.  It will be a single value only if the `single=true` option is passed.

#### Records by Title

{% tabs %}
{% tab title="Records by Title" %}

```rust
secrets_manager.get_secret_by_title(record_title);
```

{% endtab %}

{% tab title="Records By Title Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get all secrets matching the record title
    let secrets = secrets_manager.get_secret_by_title("My Credentials").unwrap().unwrap();
    Ok(())
}
```

{% endtab %}
{% endtabs %}

**Response**

> Type: `Record<Option<Vec<Record>>>`

| Parameter      | Type   | Required | Description                       |
| -------------- | ------ | -------- | --------------------------------- |
| `record_title` | `&str` | Yes      | Title of the record to be fetched |

#### Retrieve Values using Keeper Notation

{% tabs %}
{% tab title="get Notation" %}

```rust
secrets_manager.get_notation(query)
```

{% endtab %}

{% tab title="Notation Example" %}

<pre class="language-rust"><code class="lang-rust">use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result&#x3C;(), KSMRError>{
    // setup secrets manager
<strong>    let config_string = "your_base64_goes_here".to_string();
</strong>    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
<strong>    let mut secrets_manager = SecretsManager::new(client_options)?;
</strong>
    // get all secrets matching the notation
    let mut notation = "HDQTnxkTcPSOsHNAlbI4aQ/field/login".to_string();
    let mut result = secrets_manager.get_notation(notation)?;
    Ok(())
}
</code></pre>

{% endtab %}
{% endtabs %}

See [Keeper Notation documentation](https://docs.keeper.io/en/secrets-manager/secrets-manager/about/keeper-notation) to learn about Keeper Notation format and capabilities

| Parameter | Type     | Required | Default | Description                                                      |
| --------- | -------- | -------- | ------- | ---------------------------------------------------------------- |
| `query`   | `String` | Yes      | -       | Keeper Notation query for getting a value from a specified field |

**Returns**

The value of the queried field

Type: String or `Vec<String>`

#### Retrieve a TOTP Code

{% tabs %}
{% tab title="Get TOTP Code" %}

```
get_totp_code(&url)
```

{% endtab %}

{% tab title="Example Usage" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get TOTP url value from a record
    let value = record.get_standard_field_value(StandardFieldTypeEnum::ONETIMECODE.get_type(), false)
    let url: String = utils::get_otp_url_from_value_obj(value)?;

    // get code from TOTP url
    let totp = utils::get_totp_code(&url)?;
    println!("{}", totp.get_code());
    Ok(())
}
```

{% endtab %}
{% endtabs %}

**Returns**

> Type: `Result<TotpCode,KSMRError>`

| Parameter | Type     | Required | Description |
| --------- | -------- | -------- | ----------- |
| `url`     | `String` | Yes      | TOTP Url    |

### Update a Secret

{% hint style="warning" %}
Record update commands don't update local record data on success *(esp. updated record revision)* so any consecutive updates to an already updated record will fail due to **revision** mismatch. Make sure to reload all updated records after each update batch.
{% endhint %}

**Save Changes to a Secret**

{% tabs %}
{% tab title="Save Secret" %}

```rust
secrets_manager.save(Record, UpdateTransactionType)
```

{% endtab %}

{% tab title="Saving secret updates" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secret_to_update = secrets_manager.get_secrets(["<RECORD UID>".to_string()])?;

    // update a field value
    let field_type= StandardFieldTypeEnum::LOGIN.get_type();
    secret_to_update.set_standard_field_value_mut(field_type, "sample@ks.com".into())?;

    let transaction_type: Option<UpdateTransactionType> = Some(UpdateTransactionType::None);

    secrets_manager.save(secret_to_update, transaction_type);
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter          | Type                    | Required | Default | Description                            |
| ------------------ | ----------------------- | -------- | ------- | -------------------------------------- |
| `record`           | `Record`                | Yes      |         | Storage and query configuration        |
| `transaction_type` | `UpdateTransactionType` | Yes      |         | Configuration for transactional update |

Set field values using the `set_standard_field_value_mut` or the `set_custom_field_value_mut` method.

Fields are found by type.

For a list of field types, see the [Record Types](https://docs.keeper.io/en/secrets-manager/commander-cli/command-reference/record-commands/default-record-types#field-types) documentation. Some fields have multiple values in these cases, the value can be set to a list.

#### Update a Standard Field Value

{% tabs %}
{% tab title="Update Standard Field value" %}

```rust
secret.set_standard_field_value_mut(field_type, "new_field_value".into())
```

{% endtab %}

{% tab title="Update Standard field Value Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secret_to_update = secrets_manager.get_secrets(["<RECORD UID>".to_string()])?;

    // update a field value
    let field_type= StandardFieldTypeEnum::LOGIN.get_type();
    secret_to_update.set_standard_field_value_mut(field_type, "sample@ks.com".into())?;

    let transaction_type: Option<UpdateTransactionType> = Some(UpdateTransactionType::None);

    secrets_manager.save(secret_to_update, transaction_type);
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter          | Type                    | Required | Default | Description                            |
| ------------------ | ----------------------- | -------- | ------- | -------------------------------------- |
| `field_type`       | `String`                | Yes      |         | Field type to get                      |
| `transaction_type` | `UpdateTransactionType` | Yes      | None    | Configuration for transactional update |

Fields are found by type. For a list of field types, see the [Record Types](https://docs.keeper.io/en/secrets-manager/commander-cli/command-reference/record-commands/default-record-types#field-types) documentation.

#### Update a Custom Field Value

{% tabs %}
{% tab title="Custom Field Update" %}

```rust
secret.set_custom_field_value_mut(field_type, "new_field_value".into());
```

{% endtab %}

{% tab title="Custom Field Update Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secret_to_update = secrets_manager.get_secrets(["<RECORD UID>".to_string()])?;

    // update a field value
    secret_to_update.set_custom_field_value_mut("Email", "sample@ks.com".into())?;

    let transaction_type: Option<UpdateTransactionType> = Some(UpdateTransactionType::None);

    secrets_manager.save(secret_to_update, transaction_type);
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter          | Type                    | Required | Default | Description                            |
| ------------------ | ----------------------- | -------- | ------- | -------------------------------------- |
| `field_type`       | `String`                | Yes      |         | Field type to get                      |
| `transaction_type` | `UpdateTransactionType` | Yes      | None    | Configuration for transactional update |

#### Generate a Random Password

{% tabs %}
{% tab title="Generate Password" %}

```rust
generate_password_with_options(password_options);
```

{% endtab %}

{% tab title="Generate Password Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secret_to_update = secrets_manager.get_secrets(["<RECORD UID>".to_string()])?;

    # generate a random password
    let charset: String = "$_!?#".to_string();
    let length = 32;
    let digits = 2;
    let lowercase = 2;
    let uppercase = 2;
    let special_characters = 2;
    let password_options = PasswordOptions::new().length(length).digits(digits).lowercase(lowercase).uppercase(uppercase).special_characters(special_characters).special_characterset(charset);
    let password = generate_password_with_options(password_options).unwrap();

    # update a record with new password
    let field_type= StandardFieldTypeEnum::PASSWORD.get_type();
    secret.set_standard_field_value_mut(field_type, password.into())?;

    # Save changes to the secret
    let transaction_type: Option<UpdateTransactionType> = Some(UpdateTransactionType::None);
    secrets_manager.save(secret, transaction_type);
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter            | Type              | Required | Default | Description                                              |
| -------------------- | ----------------- | -------- | ------- | -------------------------------------------------------- |
| `password_options`   | `PasswordOptions` | Yes      |         | Configuration for the password                           |
| `charset`            | `String`          | Optional |         | Set of special characters to be included in the password |
| `length`             | `i32`             | Optional | 64      | Length of password                                       |
| `lowercase`          | `i32`             | Optional | 0       | Count of lowercase characters in the password            |
| `uppercase`          | `i32`             | Optional | 0       | Count of uppercase characters in the password            |
| `digits`             | `i32`             | Optional | 0       | Count of digits in the password                          |
| `special_characters` | `i32`             | Optional | 0       | Count of special characters in the password              |

Each parameter indicates the minimum number of a type of character to include. For example, 'uppercase' indicates the minimum number of uppercase letters to include.

### Download a File

{% tabs %}
{% tab title="Download File" %}

```rust
download_file(file_name, path);
```

{% endtab %}

{% tab title="Download File example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secrets = secrets_manager.get_secrets(["<RECORD UID>".to_string()])?[0];
    // Save all files to a tmp folder (create folder if does not exist)
    let path = format!("./temp/demo_{}.txt", secret.title);
    secret.download_file("uploaded_file.txt", &path)?;
    Ok(())
}
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th width="82.734375">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>file_name</code></td><td><code>&#x26;str</code></td><td>Yes</td><td></td><td>Name of the file to be downloaded</td></tr><tr><td><code>path</code></td><td><code>&#x26;str</code></td><td>Yes</td><td></td><td>Path to download file</td></tr></tbody></table>

### Upload File

{% tabs %}
{% tab title="Upload File" %}

```rust
upload_file(owner_record, keeper_file);
```

{% endtab %}

{% tab title="Upload File Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secrets = secrets_manager.get_secrets(["<RECORD UID>".to_string()])?[0];
    // Save all files to a tmp folder (create folder if does not exist)
    let path = format!("./temp/demo_{}.txt", secret.title);
    // Prepare file data for upload
    let keeper_file = KeeperFileUpload::get_file_for_upload(file_path, Some(file_name),file_title, mime_type)?;

    // Upload file attached to the owner record and get the file UID
    file_uid = secrets_manager.upload_file(owner_record, keeper_file)?;
    Ok(())
}
```

{% endtab %}
{% endtabs %}

**Upload File Parameters**

<table><thead><tr><th>Parameter</th><th width="162.203125">Type</th><th>Required</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>owner_record</code></td><td><code>Record</code></td><td>Yes</td><td>None</td><td>The record in which the file has to be uploaded</td></tr><tr><td><code>keeper_file</code></td><td><code>KeeperFileUpload</code></td><td>Yes</td><td></td><td>The file to be uploaded</td></tr></tbody></table>

**File Parameters**

| Parameter    | Type           | Required | Default | Description                                                                                |
| ------------ | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| `file_path`  | `&str`         | Yes      |         | Path to upload file                                                                        |
| `file_name`  | `Option<&str>` | Yes      |         | Name of the file to be uploaded                                                            |
| `file_title` | `Option<&str>` | Yes      |         | Title of the file to be uploaded                                                           |
| `mime_type`  | `Option<&str>` | Yes      | None    | The type of data in the file. If none is provided, 'application/octet-stream' will be used |

**Returns**

> Type: `String`

The file UID of the attached file

### Create a secret

**Prerequisites:**

* Shared folder UID
  * The shared folder must be accessible by the Secrets Manager Application
  * You and the Secrets Manager application must have edit permission
  * There must be at least one record in the shared folder
* Created records and record fields must be formatted correctly
  * See the [documentation](https://docs.keeper.io/en/secrets-manager/commander-cli/command-reference/record-commands/default-record-types#field-types) for expected field formats for each record type
* TOTP fields accept only URL generated outside of the KSM SDK
* After record creation, you can upload file attachments using [upload\_file](https://docs.keeper.io/en/secrets-manager/secrets-manager/developer-sdk-library/python-sdk#upload-a-file)

{% tabs %}
{% tab title="Create Record" %}

```rust
secrets_manager.create_secret(folder_uid, record);
```

{% endtab %}

{% tab title="Login record Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    dto::{dtos::RecordCreate, field_structs::RecordField}
};
use serde_json::{self, json, Number, Value};

fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // This is how we create a Record
    let mut created_record =  RecordCreate::new("login".to_string(), "Login Record RUST_LOG_TEST".to_string(), Some("Dummy Notes".to_string()));
    
    // This is how we create a single field 
    let password_field = RecordField::new_record_field_with_options("password".to_string(), Value::String(utils::generate_password()?), Some("Random password label".to_string()), false, true);

    //This is one way to create all fields directly in a vector
    let fields = vec![
        RecordField::new_record_field("login".to_string(), Value::String("login@email.com".to_string()), Some("My Custom Login lbl".to_string())),

        password_field,
     ];

    created_record.fields = Some(fields);
  
    // Make the API call
    let _ = secrets_manager.create_secret("Shared_folder_uid".to_string(), created_record)?;
    Ok(())
}
```

{% endtab %}

{% tab title="Custom Type example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    dto::{dtos::RecordCreate, field_structs::RecordField}
};
use serde_json::{self, json, Number, Value};

fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // This is how we create a Record
    let mut created_record =  RecordCreate::new("login".to_string(), "Login Record RUST_LOG_TEST".to_string(), Some("Dummy Notes".to_string()));
    
    // This is how we create a single field 
    let password_field = RecordField::new_record_field_with_options("password".to_string(), Value::String(utils::generate_password()?), Some("Random password label".to_string()), false, true);

    // This is one of the ways to create a value object from JSON String
    let security_question_value = Value::from_str("{\"question\": \"What is the question?\", \"answer\": \"This is the answer!\"}")?;
    
    //This is one way to create all fields directly in a vector
    let fields = vec![
        RecordField::new_record_field("login".to_string(), Value::String("login@email.com".to_string()), Some("My Custom Login lbl".to_string())),

        RecordField::new_record_field("login".to_string(), Value::String("login@email.com".to_string()), Some("My Label".to_string())),

        password_field,
        
        RecordField::new_record_field("securityQuestion".to_string(),security_question_value , Some("My Label".to_string())),

        RecordField::new_record_field("multiline".to_string(),Value::String("This\nIs a multiline\nnote".to_string()) , Some("My Multiline lbl".to_string())),

        RecordField::new_record_field("secret".to_string(),Value::String("SecretText".to_string()) , Some("My Hidden Field lbl".to_string())),

        RecordField::new_record_field("pinCode".to_string(),Value::String("1234567890".to_string()) , Some("My Pin Code Field Lbl".to_string())),

        RecordField::new_record_field("addressRef".to_string(),Value::String("some_UID".to_string()) , Some("My Address Reference".to_string())),

        RecordField::new_record_field("phone".to_string(),json!({"region": "US", "number": "510-444-3333"}) , Some("My Phone Number".to_string())),

        RecordField::new_record_field("date".to_string(),Value::Number(Number::from(1641934793000i64)) , Some("My date".to_string())),

        RecordField::new_record_field("date".to_string(),Value::String("September eleventh two thousand and eleven".to_string()) , Some("Bad day in history of humanity".to_string())),

        RecordField::new_record_field("name".to_string(),json!({"first": "Lincoln", "last": "Adams"}) , Some("His Name".to_string())),
        ];

    // Here we are adding fields object to standard fields 
    created_record.fields = Some(fields);
    
    created_record.custom = Some(
        vec![
            RecordField::new_record_field("phone".to_string(),json!({"region": "US", "number": "510-222-5555", "ext": "99887", "type": "Mobile"}) , Some("My Custom Phone Lbl".to_string())),
        ]
    );
   
    // Make the API call
    let _ = secrets_manager.create_secret("Shared_folder_uid".to_string(), created_record)?;
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter        | Type                | Required | Default | Description                                 |
| ---------------- | ------------------- | -------- | ------- | ------------------------------------------- |
| `record_type`    | `DefaultRecordType` | Yes      | None    | Type of record to be created                |
| `title`          | `String`            | Yes      |         | The title of the created record             |
| `note`           | `String`            | Yes      | None    | The note to be made in the created record   |
| `value`          | `String`            | Yes      |         | Value for the field                         |
| `label`          | `String`            | Yes      | None    | Label for the field                         |
| `required`       | `bool`              | Yes      | false   | Defines if the field is required            |
| `privacy_screen` | `bool`              | Yes      | false   | Defines if the field value should be hidden |

**Returns**

> Type: `String`

The record UID of the new record

### Delete A Secret

The Rust KSM SDK can delete records in the Keeper Vault.

{% tabs %}
{% tab title="Delete Secret" %}

```rust
secrets_manager.delete_secret(vec![record_uid]);
```

{% endtab %}

{% tab title="Delete Secret Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // delete a specific secret by UID
    let secret_to_delete = secrets_manager.delete_secret(["<RECORD UID>".to_string()])?;
    Ok(())
}
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="121.6927490234375">Parameter</th><th width="105.942626953125">Type</th><th width="107.692626953125">Required</th><th width="95.7239990234375">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>record_uid</code></td><td><code>String</code></td><td>Yes</td><td>None</td><td>The uid of the record to be deleted</td></tr></tbody></table>

### Caching

To protect against losing access to your secrets when network access is lost, the Rust SDK allows caching of secrets to the local machine in an encrypted file.

**Setup and Configure Cache**

In order to setup caching in the Rust SDK, include a caching post function when creating a `SecretsManager` object.

The Rust SDK includes a default caching function in the `KSMRCache` class, which stores cached queries to a local file, thus serving as a disaster recovery function (as long as there's network connectivity, it always prefers network over cached data and will use cache only if the web vault is inaccessible).

```rust
use keeper_secrets_manager_core::{core::{ClientOptions, SecretsManager}, custom_error::KSMRError, storage::FileKeyValueStorage, cache::KSMRCache};
fn main()-> Result<(), KSMRError>{
    let cache = KSMRCache::new_file_cache(Some("./cache.bin"))?;

    let token = "<Token>".to_string();

    let file_name = FileKeyValueStorage::new_config_storage("test.json".to_string())?;
    
    let mut client_options = ClientOptions::new_client_options_with_token(token, file_name);
    client_options.set_cache(cache.into()); 
    
    let mut secrets_manager = SecretsManager::new(client_options)?;  
    let secrets = secrets_manager.get_secrets(Vec::new())?;
    for secret in secrets {
        info!("Secret: {}", secret);
    };
}
```

{% hint style="danger" %}
The default caching function in `KSMCache` class always stores last request only. For example, if the first request (R1) successfully retrieves UID1 and updates the cache, but a subsequent request (R2) for UID2 fails, the cache will not include UID2. As a result, any later operations involving UID2 (e.g., lookup or disconnect) will return an empty response, since it was never added to the cache.
{% endhint %}

{% hint style="warning" %}
Updating a record from cache (or creating new record) invalidates cached record data and consecutive updates of the same record will fail. Batch updates work as long as they modify different records. Always follow up cached record updates with a call to `get_secrets` function to refresh cache *(and pull updated metadata from vault like the new record revision etc.)*
{% endhint %}

### Folders

Folders have full CRUD support—create, read, update, and delete operations.

### Read Folders

Downloads full folder hierarchy.

{% tabs %}
{% tab title="Read Folders" %}

```rust
get_folders()
```

{% endtab %}

{% tab title="Read Folders Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;
    
    // get all folder
    let secrets = secrets_manager.ger_folders()?;
    Ok(())
}
```

{% endtab %}
{% endtabs %}

**Returns**

> Type: `Vec<KeeperFolder>`

### Create Folder

Requires `CreateOptions` and folder name to be provided. The folder UID parameter in `CreateOptions` is required—the UID of a shared folder, while sub-folder UID is optional, and if missing, a new regular folder is created directly under the parent (shared folder). There's no requirement for the sub-folder to be a direct descendant of the parent shared folder - it could be many levels deep.

{% tabs %}
{% tab title="Create Folder" %}

```rust
create_folder(create_options: CreateOptions, folder_name: str, folders=None)
```

{% endtab %}

{% tab title="Create Folder  Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    let parent_folder_uid: String = "<parent_folder_uid>".to_string();
    let sub_folder_uid: Option<String> = Option::Some((""));
    let create_options: CreateOptions = CreateOptions::new(parent_folder_uid, None);
    let new_folder_name: String = "Sample Folder 200".to_string();
    println!("Creating folder: {new_folder_name}");
    let created_folder_name = new_folder_name.clone();
    let result = secrets_manager.create_folder(create_options, new_folder_name, Vec::new())?;
    println!("Created folder {created_folder_name}");
    Ok(())
}
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="146.0677490234375">Parameter</th><th width="179.9166259765625">Type</th><th width="105.2344970703125">Required</th><th width="97.6875">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>create_options</code></td><td><code>CreateOptions</code></td><td>Yes</td><td>None</td><td>The parent and sub-folder UIDs</td></tr><tr><td><code>folder_name</code></td><td><code>str</code></td><td>Yes</td><td></td><td>The folder name</td></tr><tr><td><code>folders</code></td><td><code>Vec&#x3C;KeeperFolder></code></td><td>No</td><td>None</td><td>List of folders to use in the search for parent and sub-folder from CreateOptions</td></tr></tbody></table>

### Update Folder

Updates the folder metadata—currently folder name only.

{% tabs %}
{% tab title="Update Folder" %}

```rust
secrets_manager.update_folder(folder_uid: str, folder_name: str, folders=None)
```

{% endtab %}

{% tab title="Update Folder Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    let update_folder = secrets_manager.update_folder("<folder_uid>".to_string(),"dummy_updated_API_RUST".to_string(),Vec::new())?;
    println!("{}",(serde_json::to_string_pretty(&update_folder)?));
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter     | Type                | Required | Default | Description                                            |
| ------------- | ------------------- | -------- | ------- | ------------------------------------------------------ |
| `folder_uid`  | `str`               | Yes      |         | The folder uid                                         |
| `folder_name` | `str`               | Yes      |         | The new folder name                                    |
| `folders`     | `Vec<KeeperFolder>` | No       | None    | List of folders to use in the search for parent folder |

### Delete Folders

Removes a list of folders. Use the `force_deletion` flag to remove non-empty folders.

{% hint style="info" %}
Any folders UIDs missing from the vault or not shared to the KSM Application will not result in error.
{% endhint %}

{% hint style="info" %}
When using `force_deletion` avoid sending parent with its children folder UIDs. Depending on the delete order you may get an error - *ex.* if parent force-deleted child first. There's no guarantee that list will always be processed in FIFO order.
{% endhint %}

{% tabs %}
{% tab title="Delete Folder" %}

```rust
delete_folder(vec![“<FOLDER_UID>”.to_string()], false);
```

{% endtab %}

{% tab title="Delete Folder Example" %}

```rust
use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::FileKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;
    
    let folder_uids = vec!["folder1_uid".to_string(),"folder_2_uid".to_string()];
    secrets_manager.delete_folder(folder_uids, true)?;
    Ok(())
}
```

{% endtab %}
{% endtabs %}

| Parameter        | Type          | Required | Default | Description                         |
| ---------------- | ------------- | -------- | ------- | ----------------------------------- |
| `folder_uids`    | `Vec<String>` | Yes      |         | The folder UID list                 |
| `force_deletion` | `boolean`     | No       | false   | Force deletion of non-empty folders |
