If you're familiar with Composer, setup is as easy as php composer.phar require paragonie/sapient:^1
.
If you're not using Composer, you can either adopt Composer or extract the contents of our
src
directory to an appropriate place in your project and write your own SPL autoloader.
We recommend using Composer and keeping your dependencies up-to-date.
If your framework already uses PSR-7 objects, you can simply use the Sapient methods through a Middleware to add signatures, encryption, etc.
For example, this will first encrypt an HTTP response with the client's public key (so that only the client may decrypt it), and then sign the encrypted message with the server's secret key (so that the client can verify it came from the server):
<?php
/**
* @var Psr\Http\Message\ResponseInterface $nakedResponse
* @var ParagonIE\Sapient\Sapient $sapient
* @var ParagonIE\Sapient\CryptographyKeys\SigningSecretKey $signingKey
* @var ParagonIE\Sapient\CryptographyKeys\SealingPublicKey $clientPublicKey
*/
$sealedResponse = $sapient->sealResponse($nakedResponse, $clientPublicKey);
$signedResponse = $sapient->signResponse($sealedResponse, $signingKey);
Before you get to this point, first you'll need to create and store your cryptography keys.
To generate a new key, you can simply use the generate()
method on the appropriate
CryptographyKey
object.
<?php
use ParagonIE\Sapient\CryptographyKeys\{
SealingSecretKey,
SharedAuthenticationKey,
SharedEncryptionKey,
SigningSecretKey
};
$sealSecret = SealingSecretKey::generate();
$signSecret = SigningSecretKey::generate();
$sharedEncryptionKey = SharedEncryptionKey::generate();
$sharedAuthenticationKey = SharedAuthenticationKey::generate();
Note: You cannot generate public keys. You can generate a secret key and then obtain the associated public key, but it doesn't mane sense to generate a public key for which you do not know the secret key.
$sealPublic = $sealSecret->getPublicKey();
$signPublic = $signSecret->getPublicKey();
Every key object has a getString()
method which will return a base64url
encoded string by default. If you want raw binary, pass true
as the only argument to this method.
You may then store these strings as you would any other secret information.
To load a CryptographyKey
from a string, simply pass it to the constructor, like so:
<?php
use ParagonIE\Sapient\CryptographyKeys\SigningSecretKey;
use ParagonIE\ConstantTime\Base64UrlSafe;
/** @var string $yourEncodedStringHere*/
$signSecret = new SigningSecretKey(
Base64UrlSafe::decode($yourEncodedStringHere)
// This assumes it was stored with getString() rather than getString(true)
);