github.com/Venafi/vcert/v5@v5.10.2/README-CLI-TPP-SSH.md (about) 1  2 [](https://opensource.org/licenses/Apache-2.0) 3  4  5 _**This open source project is community-supported.** To report a problem or share an idea, use 6 **[Issues](../../issues)**; and if you have a suggestion for fixing the issue, please include those details, too. 7 In addition, use **[Pull Requests](../../pulls)** to contribute actual bug fixes or proposed enhancements. 8 We welcome and appreciate all contributions. Got questions or want to discuss something with our team? 9 **[Join us on Slack](https://join.slack.com/t/venafi-integrations/shared_invite/zt-i8fwc379-kDJlmzU8OiIQOJFSwiA~dg)**!_ 10 11 # VCert CLI for Venafi Trust Protection Platform 12 13 Venafi VCert is a command line tool designed to generate keys and simplify certificate acquisition, eliminating the need to write code that's required to interact with the Venafi REST API. VCert is available in 32- and 64-bit versions for Linux, Windows, and macOS. 14 15 This article applies to the latest version of VCert CLI, which you can [download here](https://github.com/Venafi/vcert/releases/latest). 16 17 ## Quick Links 18 19 Use these to quickly jump to a relevant section lower on this page: 20 21 - [Detailed usage examples](#examples) 22 - [Options for requesting an SSH certificate using the `sshenroll` action](#ssh-certificate-request-parameters) 23 - [Options for downloading an SSH certificate using the `sshpickup` action](#ssh-certificate-retrieval-parameters) 24 - [Options for downloading an SSH CA's public key using the `sshgetconfig` action](#parameters-for-retrieving-an-ssh-cas-public-key) 25 - [Options for obtaining a new authorization token using the `getcred` action](#obtaining-an-authorization-token) 26 - [Options for checking the validity of an authorization token using the `checkcred` action](#checking-the-validity-of-an-authorization-token) 27 - [Options for invalidating an authorization token using the `voidcred` action](#invalidating-an-authorization-token) 28 29 ## Prerequisites 30 31 Review these prerequistes to get started. You'll need: 32 33 1. A user account that has an authentication token with "ssh:manage" scope (i.e. access to the "Venafi VCert CLI" API Application as of 21.2) 34 2. A folder where the user has been granted the following permissions: View, Read, Write, Create, and Private Key Read; this is for the pickup action when the certificate signing request (CSR) is service-generated. 35 36 ### Compatibility 37 38 VCert is compatible with Trust Protection Platform 20.3 or later for SSH Certificates. 39 40 ## General Command Line Parameters 41 42 The following options apply to the `sshenroll` and `sshpickup` actions: 43 44 | Command | Description | 45 | ------------------- | ------------------------------------------------------------ | 46 | `--config` | Use to specify INI configuration file containing connection details. Available parameters: `tpp_url`, `access_token`, `tpp_user`, `tpp_password`, `tpp_zone`, `trust_bundle`, `test_mode` | 47 | `--no-prompt` | Use to exclude password prompts. If you enable the prompt and you enter incorrect information, an error is displayed. This option is useful with scripting. | 48 | `--t` | Use to specify the token required to authenticate with Venafi Platform 20.1 (and higher). See the [Appendix](#obtaining-an-authorization-token) for help using VCert to obtain a new authorization token. | 49 | `--test-mode` | Use to test operations without connecting to Venafi Platform. This option is useful for integration tests where the test environment does not have access to Venafi Platform. Default is false. | 50 | `--test-mode-delay` | Use to specify the maximum number of seconds for the random test-mode connection delay. Default is 15 (seconds). | 51 | `--timeout` | Use to specify the maximum amount of time to wait in seconds for a certificate to be processed by Venafi Platform. Default is 120 (seconds). | 52 | `--trust-bundle` | Use to specify a file with PEM formatted certificates to be used as trust anchors when communicating with Venafi Platform. VCert uses the trust store of your operating system for this purpose if not specified.<br/>Example: `--trust-bundle /path-to/bundle.pem` | 53 | `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.<br/>Example: `-u https://tpp.venafi.example` | 54 | `--verbose` | Use to increase the level of logging detail, which is helpful when troubleshooting issues. | 55 56 ### Environment Variables 57 58 As an alternative to specifying a token, trust bundle, url, and/or zone via the command line or in a config file, VCert supports supplying those values using environment variables `VCERT_TOKEN`, `VCERT_TRUST_BUNDLE`, `VCERT_URL`, and `VCERT_ZONE` respectively. 59 60 61 ## SSH Certificate Request Parameters 62 ``` 63 vcert sshenroll -u <tpp url> -t <auth token> --template <ssh ca> --id <cert id> --principal <user> --valid-hours 1 64 ``` 65 Options: 66 67 | Command | Description | 68 | ------------------------------------------------------------ | ------------------------------------------------------------ | 69 | `--destination-address` | Use to specify the address (FQDN, hostname, IP address, or CIDR) of the destination host where the certificate will be used for authentication. Applicable for client certificates and is used for reporting/auditing only. | 70 | `--extension` | Use to request certificate extensions. For basic extensions use `--extension <value>` and for key-value extensions use `--extension <key>:<value>` | 71 | `--folder` | Use to specify the DN of the policy folder within which the certificate object will be created. If not specified, the default policy folder indicated by the certificate template will be used. | 72 | `--force-command` | Use to request a force command. Example: `--force-command "/usr/scripts/db_backup.sh"` | 73 | `--id` | Use to specify the identifier of the SSH certificate. This is typically used to determine ownership. | 74 | `--key-passphrase` | Use to specify the passphrase for encrypting the private key. | 75 | `--key-size` | Use to specify the key size in bits when creating a keypair using `--public-key local` | 76 | `--object-name` | Use to specify a friendly name for the certificate object. If not specified, the value of the `--id` parameter is used. | 77 | `--principal` | Use to specify principals for the certificate. If not specified, the default principals indicated by the certificate template will be used. | 78 | `--public-key` | Use to specify the origin of the public key. Options: `local` (default), `service`, or `file:/path-to/key.pub` | 79 | `--source-address` | Use to specify the source addresses as list of IP addresses or CIDR. Example: `--source-address 192.168.1.1/24` | 80 | `--template` | Used to specify the SSH certificate issuing template that will be used to sign the certificate. | 81 | `--valid-hours` | Use to specify the number of hours a certificate needs to be valid. | 82 | `--windows` | Output certificate and key files in Windows format (i.e. with \r\n line endings) instead of Unix format (i.e. \n line endings). | 83 84 85 ## SSH Certificate Retrieval Parameters 86 ``` 87 vcert sshpickup -u <tpp url> -t <auth token> --pickup-id <cert DN> 88 ``` 89 Options: 90 91 | Command | Description | 92 | ------------------------------------------------------------ | ------------------------------------------------------------ | 93 | `--guid` | Use to specify the identifier of the SSH certificate to retrieve (alternative to specifying the SSH certificate by DN using `--pickup-id`). | 94 | `--key-passphrase` | Use to specify the passphrase for encrypting the private key. | 95 | `--pickup-id` | Use to specify the DN of the SSH certificate to retrieve. | 96 | `--windows` | Output certificate and key files in Windows format (i.e. with \r\n line endings) instead of Unix format (i.e. \n line endings). | 97 98 99 ## Parameters for retrieving an SSH CA's public key 100 ``` 101 vcert sshgetconfig -u <tpp url> -t <auth token> --template <ssh ca> 102 ``` 103 Options: 104 105 | Command | Description | 106 | ------------------------------------------------------------ | ------------------------------------------------------------ | 107 | `--file` | Use to specify the file to which the SSH CA public key will be written. Example: `--file /path-to/ssh_ca.pub` | 108 | `--guid` | Use to specify the identifier of the SSH certificate issuing template to view (alternative to specifying the issuing template by DN using `--template`). | 109 | `--template` | Use to specify the DN of the SSH certificate issuing template to view. | 110 111 112 ## Examples 113 114 For the purposes of the following examples, assume the following: 115 116 - The Trust Protection Platform REST API is available at https://tpp.venafi.example/vedsdk 117 - A user account named _SshCertSvc_ has been created with an authentication token of "ql8AEpCtGSv61XGfAknXIA==", with a scope of "ssh:manage". 118 - A folder structure has been created at the root of the Policy Tree called _ssh-certificates\dev-db-admins_ and the *SshCertSvc* user has been granted View, Read, Write, Create, and Private Key Read permissions to that folder. 119 - An SSH Certificate Issuing Template has been created called _DB-Admins-Template_. 120 121 Use the Help to view the command line syntax for enroll: 122 ``` 123 vcert enroll -h 124 ``` 125 Submit a Trust Protection Platform request for enrolling an SSH certificate from the SSH Certificate Issuing Template for the db-admin, to access a computer for 8 hours: 126 ``` 127 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --principal db-admin --valid-hours 8 128 ``` 129 Submit a Trust Protection Platform request for enrolling an SSH certificate with multiple principals for 8 hours: 130 ``` 131 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --principal db-admin --principal db-user --valid-hours 8 132 ``` 133 Submit a Trust Protection Platform request for enrolling an SSH certificate with a different object name on TPP: 134 ``` 135 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --principal db-admin --object-name "DB-admin-certificate" 136 ``` 137 Submit a Trust Protection Platform request for enrolling an SSH certificate with extensions: 138 ``` 139 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --principal db-admin --extension "permit-pty" --extension "permit-port-forwarding" 140 ``` 141 Submit a Trust Protection Platform request for enrolling an SSH certificate with a custom extension: 142 ``` 143 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --principal db-admin --extension "login@github.com":"alice@github.com" 144 ``` 145 Submit a Trust Protection Platform request for enrolling an SSH certificate with source addresses where one is an IP the other is CIDR: 146 ``` 147 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate "192.168.2.73" --source-address "192.168.1.0/24" 148 ``` 149 Submit a Trust Protection Platform request for enrolling an SSH certificate with the private key to be generated and stored in Trusted Protect Platform: 150 ``` 151 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --public-key "service" 152 ``` 153 Submit a Trust Protection Platform request for enrolling an SSH certificate using a pre-existing SSH public key: 154 ``` 155 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --public-key "file:/home/db-user/.ssh/id_rsa.pub" 156 ``` 157 Submit a Trust Protection Platform request for enrolling an SSH certificate with a specific key size and a non-default policy folder: 158 ``` 159 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --key-size 4096 --folder "\VED\Policy\ssh-certificates\dev-db-admins" 160 ``` 161 Submit a Trust Protection Platform request for enrolling an SSH certificate with forced command: 162 ``` 163 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --force-command "./home/db-user/scripts/configure.sh" 164 ``` 165 Submit a Trust Protection Platform request for enrolling an SSH certificate without any credential or password prompts: 166 ``` 167 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --no-prompt 168 ``` 169 Submit a Trust Protection Platform request for enrolling an SSH certificate with a passphrase encrypted private key and for the private key file to use Windows line endings: 170 ``` 171 vcert sshenroll -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --template DB-Admins-Template --id example-certificate --key-passphrase "MyPassword" --windows 172 ``` 173 Submit a Trust Protection Platform request for retrieving an SSH certificate by its object DN: 174 ``` 175 vcert sshpickup -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --pickup-id "\VED\Policy\ssh-certificates\dev-db-admins\example-certificate" 176 ``` 177 Submit a Trust Protection Platform request for retrieving an SSH certificate by its object GUID: 178 ``` 179 vcert sshpickup -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --guid "{855bbf35-b098-412d-b45a-2091f8c653c8}" 180 ``` 181 Submit a Trust Protection Platform request for retrieving an SSH certificate without any credential or password prompts: 182 ``` 183 vcert sshpickup -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --pickup-id "\VED\Policy\ssh-certificates\dev-db-admins\example-certificate" --no-prompt 184 ``` 185 Submit a Trust Protection Platform request for retrieving an SSH certificate with a passphrase encrypted private key and for the private key file to use Windows line endings: 186 ``` 187 vcert sshpickup -u https://tpp.venafi.example -t "ql8AEpCtGSv61XGfAknXIA==" --guid "{855bbf35-b098-412d-b45a-2091f8c653c8}" --key-passphrase "MyPassword" --windows 188 ``` 189 190 191 ## Appendix 192 193 ### Obtaining an Authorization Token 194 ``` 195 vcert getcred -u <tpp url> --username <tpp username> --password <tpp password> --ssh 196 197 vcert getcred -u <tpp url> --p12-file <client cert file> --p12-password <client cert file password> --ssh 198 ``` 199 Options: 200 201 | Command | Description | 202 | ---------------- | ------------------------------------------------------------ | 203 | `--client-id` | Use to specify the application that will be using the token. "vcert-cli" is the default. | 204 | `--format` | Specify "json" to get JSON formatted output instead of the plain text default. | 205 | `--password` | Use to specify the Venafi Platform user's password. | 206 | `--p12-file` | Use to specify a PKCS#12 file containing a client certificate (and private key) of a Venafi Platform user to be used for mutual TLS. Required if `--username` or `--t` is not present and may not be combined with either. Must specify `--trust-bundle` if the chain for the client certificate is not in the PKCS#12 file. | 207 | `--p12-password` | Use to specify the password of the PKCS#12 file containing the client certificate 208 | `--ssh` | Use to request a token that can be used for ssh actions. This is the equivalent of `--scope ssh:manage;`| 209 | `--scope` | Use to request specific scopes and restrictions. If not specified, tokens with the "certificate:manage,revoke;" scope are returned. When requesting a token for ssh actions `--scope ssh:manage;` is required or alternatively, the `--ssh` option can be specified.| 210 | `-t` | Use to specify a refresh token for a Venafi Platform user. Required if `--username` or `--p12-file` is not present and may not be combined with either. | 211 | `--trust-bundle` | Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server. | 212 | `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.<br/>Example: `-u https://tpp.venafi.example` | 213 | `--username` | Use to specify the username of a Venafi Platform user. Required if `--p12-file` or `--t` is not present and may not be combined with either. | 214 215 ### Checking the validity of an Authorization Token 216  217 ``` 218 vcert checkcred -u <tpp url> -t <access token> 219 ``` 220 Options: 221 222 | Command | Description | 223 | ---------------- | ------------------------------------------------------------ | 224 | `--format` | Specify "json" to get JSON formatted output instead of the plain text default. | 225 | `-t` | Use to specify an access token for a Venafi Platform user. | 226 | `--trust-bundle` | Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server. | 227 | `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.<br/>Example: `-u https://tpp.venafi.example` | 228 229 ### Invalidating an Authorization Token 230 ``` 231 vcert voidcred -u <tpp url> -t <access token> 232 ``` 233 Options: 234 235 | Command | Description | 236 | ---------------- | ------------------------------------------------------------ | 237 | `-t` | Use to specify an access token for a Venafi Platform user. | 238 | `--trust-bundle` | Use to specify a PEM file name to be used as trust anchors when communicating with the Venafi Platform API server. | 239 | `-u` | Use to specify the URL of the Venafi Trust Protection Platform API server.<br/>Example: `-u https://tpp.venafi.example` |