How to connect to passbolt API with PHP

API & Customization issues
1

This post is an “how to” example to connect to the passbolt API with PHP.

I invite you to clone that repository and to try the code inside : GitHub - passbolt/passbolt_api_php_example: Passbolt API - PHP usage example.

Please, as written in the README, note that the source code provided is not to be used in production as it is. It is only a simplified example of how to connect to passbolt API in PHP and perform operations.

To be able to use it, you need to first modify the config/config.php file :

server_url = the url of your passbolt instance.
private_key_path = the path to your private key.
private_key_passphrase = the passphrase used for your private key, if there is not, set it to null.

Then, depending on your passbolt version/installation, you will maybe have to do some modification in the passbolt_api_php_example because the cookie name might not be the same as in the passbolt_api_php_example code. To know what cookie name your passbolt installation uses, do as below :

If you installed passbolt from sources, you will need to be sure that you have the ‘cookie’ set in your app.php, for this, open the /var/www/passbolt/config/app.php and to the very end of the file you have something like :

'Session' => [
        'cookie' => env('SESSION_COOKIE', 'passbolt_session'),
        'defaults' => env('SESSION_DEFAULTS', 'php'),
    ],

If you don’t have the ‘cookie’ line, add it to your file.

If you installed passbolt from debian packages :

grep 'SESSION_COOKIE' /etc/passbolt/app.php

Output example, in this case the cookie name is ‘passbolt_session’:

'cookie' => env('SESSION_COOKIE', 'passbolt_session'),

If your cookie name is CAKEPHP, it’s all good, you don’t have to change anything and you can proceed with the rest.

Otherwise, if your cookie name is passbolt_session, PHPSESSID or something else, you will need to modify the passbolt_api_php_example code. Now open the lib/gpg_auth.php file and modify lines 191 and 218 with your cookie name, for example, my cookie name was “passbolt_session” so I did like this :

sed -i 's/CAKEPHP/passbolt_session/g' passbolt_api_php_example/lib/gpg_auth.php

This command will replace the cookie name for you in the desired file.

Your passbolt_api_php_example is now good to go, we just need a last trick for GPG to not ask you your key passphrase each time. Create or edit the ~/.gnupg/gpg-agent.conf file by adding this line :

allow-preset-passphrase

Then restart your gpg agent for it to take this new config into account :

gpg-connect-agent reloadagent /bye

Now you will need to use the “gpg-preset-passphrase” utility. This tool will seed your gpg agent with your passphrase to not be password prompted every time you use the API. This utility needs you to know the keygrip of your key. The keygrip is an identifier internal to GnuPG, and it is a SHA1 hash of the key. To retrieve it you need to execute that command to display the keygrip :

gpg --list-keys --with-keygrip

There are several ways of passing the passphrase to the gpg-preset-passphrase utility. For example you could pass it via an ENV variable as follow:

/usr/lib/gnupg/gpg-preset-passphrase --preset $KEYGRIP <<< $PASSPHRASE

Depending on how you’re using gpg, it would probably be worth it to check the time to leave of the passphrase in the gpg agent. There are two options that you can play with to suit your needs :

- default-cache-ttl : set the timeout in seconds after the last GnuPG activity (so it resets if you use it).
- maximum-cache-ttl : set the timespan in seconds it caches after entering your password.

The default value is 600 seconds (10 minutes) for default-cache-ttl and 7200 seconds (2 hours) for maximum-cache-ttl. You can set these configuration in your ~/.gnupg/gpg-agent.conf like this :

default-cache-ttl <desiredvalue>
maximum-cache-ttl <desiredvalue>

This concludes the PHP example to connect to the passbolt API.

1 Like