How to get OOB credentials via public API

What are OOB credentials

OOB (Out-of-Band) is a method of remote server management that allows interaction with hardware via a separate network interface, independent of the operating system or primary network state.

You can find more details on accessing and authenticating to OOB and iDRAC in this article: How to access the OOB management of a Dell server.

What is a GPG key

A GPG (GNU Privacy Guard) key is a cryptographic tool used for encryption, decryption, digital signatures, and data authentication. It is based on asymmetric cryptography and consists of a key pair:

• Public key is used for encryption and verifying signatures

• Private key is used for decryption and creating signatures

GPG keys can be customized to meet specific requirements, including key length, algorithm, expiration date, and other parameters.

Steps to obtain OOB credentials

The process of obtaining OOB credentials involves the following steps:

1. Add a GPG key to the customer portal and obtain its fingerprint

2. Execute API requests to retrieve the server ID and OOB credentials

3. Decrypt the received message using GPG decryption

Detailed instructions for each step are provided below.

Add a GPG key to the customer portal

Since GPG keys are used for sensitive tasks and require strict security control, their creation is the user's responsibility. Only users with the Owner role can add them to the customer portal. Unlike SSH key generation, the customer portal only supports adding GPG keys with the RSA/RSA type.

To add your GPG key:

1. In the left-hand menu, navigate to Identity and Access → SSH & GPG keys

2. Scroll to the GPG keys section and click Create

3. In the Public key field, enter or paste your public key

   Ensure the key is fully copied, including all lines from ----BEGIN PGP PUBLIC KEY BLOCK---- to
   ----END PGP PUBLIC KEY BLOCK----, with no extra spaces or characters

4. Enter the key name and click Create

The public part of your GPG key will be added.

Obtain a GPG key fingerprint in the customer portal

The GPG key fingerprint is a unique sequence of characters representing the hash of a public key. It is used in API requests and ensures the public key has not been altered during transmission. Additionally, the fingerprint serves as a compact identifier for authentication and key validation.

To display the key fingerprint:

1. In the customer portal, navigate to Identity and Access → SSH & GPG keys → GPG keys

2. The fingerprint is displayed next to the added key

Obtain the server ID via Public API

Before you begin, ensure the following prerequisites are met:

• The required server is provisioned and ready

• An API key has been created in the customer portal → Identity and Access → API tokens

All public API requests must include your authentication token and should be executed using cURL commands.

To obtain the server ID:

1. Make a GET request to the public API using the following cURL command:

   curl -g "https://api.servers.com/v1/hosts" -X GET \-H "Authorization: Bearer TOKEN"

   Replace TOKEN with your API key

2. Find the server ID in the response list

3. Alternatively, access the customer portal and navigate to Dedicated Servers → Manage → Your_Server → Details → ID to find the server ID

For example, the server ID is ex4mp1e.

Retrieve OOB credentials via Public API

To request OOB credentials via the Public API, you need your GPG key fingerprint. For example, your key's fingerprint is: F1NGERPR1NT123456.

Send the following API request:

curl -g "https://api.servers.com/v1/hosts/dedicated_servers/{server_id}/oob_credentials/?fingerprint={fingerprint}" -X GET \-H "Authorization: Bearer TOKEN" 

The API response will include a string called the secret, which contains data encoded in Base64 format.

Decode the secret from Base64 format

To decode the Base64-encoded secret and convert it back to its original format:

Linux/macOS (Terminal)

Run the following command:

echo "base64-encoded-secret-string" | base64 --decode > decoded_secret.asc

Replace base64-encoded-secret-string with the actual secret from the API response. The decoded secret will be saved in the decoded_secret.asc file

Windows

1. Save the Base64-encoded secret to a file

2. Use the certutil utility with the following command:

   certutil -decode inputfile decoded_secret.asc

   where

   • inputfile is the file containing the secret

   • decoded_secret.asc is the file where the decoded secret will be saved

After decoding, the file encoded_secret.asc will contain the secret in PGP MESSAGE format. This message is encrypted using your private PGP key, providing an additional layer of security.

Extract the OOB password using GPG decryption

Ensure you have the private key corresponding to the public key used for encryption. The key must be imported into your GPG keyring and have the [E] (encryption) attribute.

Mac OS, Linux

Verify your keys

Run the following command to list your keys:

gpg --list-secret-keys

Example output:

sec   rsa4096 2025-01-24 [SC]      F1NGERPR1NT123456uid           
[ultimate] User Name <your-email>
ssb   rsa4096 2025-01-24 [E]

Where

• The main key (sec) has [SC] attributes for signing and certification

• The subkey (ssb) has the [E] attribute for encryption and decryption

If no key with the [E] attribute is listed, you cannot decrypt the PGP message. Refer to the instructions in How to create a subkey

Decrypt the PGP message

To do this:

1. Run the following command to decrypt the PGP message:

   gpg --decrypt decoded_secret.asc

2. Where decoded_secret.asc is a file containing the encrypted PGP message

3. Enter the passphrase for your private key (if applicable)

The output will include the password for OOB access.

Windows

To decrypt the PGP message, use any suitable utilities or tools for decoding, such as Kleopatra:

1. Download Kleopatra from its official website and install it

2. Open Kleopatra, click Import, and select the private key file to import

3. Click Decrypt/Verify

4. Select the file containing the decoded secret (e.g., decoded_secret.asc)

5. Click Save all to save the decrypted output

The OOB credentials will be saved in a newly created file.

How to create a subkey

When working with GPG keys, you may encounter the error "used key is not marked for encryption use" when trying to decrypt data. This typically occurs when the main key [SC] does not support encryption and decryption.

This guide explains the process of creating an [E] (Encrypt) subkey to resolve this issue.

Mac OS, Linux

1. List your keys

   gpg --list-keys --keyid-format LONG

   Find the fingerprint for your main key (e.g., F1NGERPR1NT123456LONG123456789).

2. Edit the key

   gpg --edit-key "F1NGERPR1NT123456LONG12345678"

3. Add a subkey

   addkey

4. Configure the subkey:

   • Choose the subkey type, e.g., RSA (encryption only) for encryption purposes.

   • Set the key length, e.g., 3072 bits.

   • Define the key expiration date or choose 0 for no expiration.

   • Confirm the creation and save changes by typing:

     save

5. Verify the subkey

   gpg --list-keys --keyid-format LONG

   Example output:

   sec   rsa4096 2025-01-24 [SC]      F1NGERPR1NT123456uid
              [ultimate] Your Name <your-email>
   sub   rsa4096 2025-01-24 [E]
   

6. Export the updated key to the file:

   gpg --export --armor "your-email" > public_key.asc

7. Open the public_key.asc file and add the updated key to the customer portal → Identity and Access → SSH & GPG Keys → GPG Keys

If the fingerprint has changed:

• Update your API request with the new fingerprint

• Obtain a new secret and decode it from Base64 format