Reference¶

sapient:
    sign:
        enabled: boolean
        public: string
        private: string
        host: string
        response: boolean
    seal:
        enabled: boolean
        public: string
        private: string
        response: boolean
    guzzle_middleware:
        unseal: boolean
        verify: boolean
        sign_request: boolean
        seal_request: boolean
        requester_host: string
    sealing_public_keys:
        -
            host: string
            key: string
    verifying_public_keys:
        -
            host: string
            key: string
    verify_request: boolean
    unseal_request: boolean

Above, you have full configuration reference.

sign¶

Enable signing response. If sign key is present, it must contain public, private and name property. If not present, feature is disabled.

sign.public¶

Required if sign key is present.

It is signing public key string. It is generated by \ParagonIE\Sapient\CryptographyKeys\SigningSecretKey::generate() function.

sign.private¶

Required if sign key is present.

It is signing private key string. It is generated by \ParagonIE\Sapient\CryptographyKeys\SigningSecretKey::generate() function. This key must never be revealed. If it is leaked, you must regenerate a new key pair.

sign.host¶

Required if sign key is present.

Host of who sign response. It is required if client want to verifying signature in response.

sign.response¶

Enable or disable subscriber that sign response.

seal¶

Enable sealing response. Sealing mean that response content is encrypted. Only receiver with sealing private key can decrypt and reveal response content in clear. If seal key is present, it must contain public, private and name property. If not present, feature is disabled.

seal.public¶

Required if seal key is present.

It is sealing public key string. It is generated by \ParagonIE\Sapient\CryptographyKeys\SealingSecretKey::generate() function.

seal.private¶

Required if seal key is present.

It is sealing private key string. It is generated by \ParagonIE\Sapient\CryptographyKeys\SealingSecretKey::generate() function. This key must never be revealed. If it is leaked, you must regenerate a new key pair.

seal.response¶

Enable or disable subscriber that seal response. To use this feature, you must enable sign feature. Without sign feature you will not able to use it. Sealing a response without signing is not secure. It mean your recipient will unseal the response but he will not be sure it was sent by the right sender.

guzzle_middleware¶

This bundle contain Guzzle middleware to decrypt and verify response.

guzzle_middleware.unseal¶

If enable, it will activate Guzzle middleware that decrypt response. By default it is disabled.

You must enable “seal” option and configure a “seal.private” key before using “guzzle_middleware.unseal” feature.

guzzle_middleware.verify¶

If enable, it will activate Guzzle middleware that verify signature in response. By default it is disabled.

Before enabling this option, you must configure verifying_public_keys array.

guzzle_middleware.requester_host¶

This Guzzle middleware will add a header Sapient-Requester automatically on each request. This header is used by recipient to choose the right key to encrypt response.

It is optional but highly recommended. If not enable, you must add header manually in Guzzle client configuration.

guzzle_middleware.sign_request¶

If enable, it will activate Guzzle middleware that sign all request. By default it is disabled.

You must enable “sign” option and configure a “sign.private” key before using “guzzle_middleware.sign_request” feature.

guzzle_middleware.seal_request¶

If enable, it will activate Guzzle middleware that seal all request. By default it is disabled.

It use hostname configured in Guzzle client in order to choose public key to seal request.

You must enable: - “seal” option and configure a “seal.private” key before using “guzzle_middleware.seal_request” feature. - “guzzle_middleware.sign_request” option before using “guzzle_middleware.seal_request” feature.

sealing_public_keys¶

List of all sealing public keys used to encrypt response. Your client must give you the value in sapient.seal.public. Each item must contain a key and a name. name must match header value Sapient-Signer.

sapient:
    sealing_public_keys:
        -
            name: "client-bob"
            key: "sealing public key of client-bob"

verifying_public_keys¶

List of all verifying public keys used to verify response. Your api must give you the value in sapient.sign.public. Each item must contain a key and a name. name must match header value Sapient-Requester.

sapient:
    verifying_public_keys:
        -
            name: "api-alice"
            key: "verifying public key of api-alice"

verify_request¶

Each request received by HttpKernel will enter in subscriber that verify signature. It check Sapient-Requester header and fetch the public key in verifying public keys array. If found, then it verify signature. If signature is invalid, an InvalidMessageException is raised.

unseal_request¶

Each request received by HttpKernel will enter in subscriber that unseal signature. It use it own private key to unseal request. If unseal process fail, an InvalidMessageException is raised.

You must enable “seal” option before using “unseal_request” feature.