U gn@sdZddlZddlZddlZddlZddlmZmZddlmZm Z ddl m Z m Z m Z mZmZddlZddlmZmZddlmZddlmZmZdd lmZdd lmZmZz ddlZWnek red YnXd d dddddgZ e!e"Z#eddGdd d Z$eddGdddZ%d&ej&e$e'e%dddZ(e%dddZ)e*e+e+dddZ,eddGd ddZ-Gd!ddej.Z/Gd"dde/Z0eGd#d$d$Z1Gd%d d eZ2dS)'a .. versionadded:: 0.10.0 Asynchronous :class:`~pyhanko.sign.signers.pdf_cms.Signer` implementation for interacting with a remote signing service using the Cloud Signature Consortium (CSC) API. This implementation is based on version 1.0.4.0 (2019-06) of the CSC API specification. Usage notes ----------- This module's :class:`.CSCSigner` class supplies an implementation of the :class:`~pyhanko.sign.signers.pdf_cms.Signer` class in pyHanko. As such, it is flexible enough to be used either through pyHanko's high-level API (:func:`~pyhanko.sign.signers.functions.sign_pdf` et al.), or through the :ref:`interrupted signing API `. :class:`.CSCSigner` overview ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :class:`.CSCSigner` is only directly responsible for calling the ``signatures/signHash`` endpoint in the CSC API. Other than that, it only handles batch control. This means that the following tasks require further action on the API user's part: * authenticating to the signing service (typically using OAuth2); * obtaining Signature Activation Data (SAD) from the signing service; * provisioning the certificates to embed into the document (usually those are supplied by the signing service as well). The first two involve a degree of implementation/vendor dependence that is difficult to cater to in full generality, and the third is out of scope for :class:`~pyhanko.sign.signers.pdf_cms.Signer` subclasses in general. However, this module still provides a number of convenient hooks and guardrails that should allow you to fill in these blanks with relative ease. We briefly discuss these below. Throughout, the particulars of how pyHanko should connect to a signing service are supplied in a :class:`.CSCServiceSessionInfo` object. This object contains the base CSC API URL, the CSC credential ID to use, and authentication data. Authenticating to the signing service ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ While the authentication process itself is the API user's responsibility, :class:`.CSCServiceSessionInfo` includes an :attr:`~.CSCServiceSessionInfo.oauth_token` field that will (by default) be used to populate the HTTP ``Authorization`` header for every request. To handle OAuth-specific tasks, you might want to use a library like `OAuthLib `_. Obtaining SAD from the signing service ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is done by subclassing :class:`.CSCAuthorizationInfo` and passing an instance to the :class:`.CSCSigner`. The :class:`.CSCAuthorizationInfo` instance should call the signer's ``credentials/authorize`` endpoint with the proper parameters required by the service. See the documentation for :class:`.CSCAuthorizationInfo` for details and= information about helper functions. Certificate provisioning ^^^^^^^^^^^^^^^^^^^^^^^^ In pyHanko's API, :class:`~pyhanko.sign.signers.pdf_cms.Signer` instances need to be initialised with the signer's certificate, preferably together with other relevant CA certificates. In a CSC context, these are typically retrieved from the signing service by calling the ``credentials/info`` endpoint. This module offers a helper function to handle that task, see :func:`.fetch_certs_in_csc_credential`. N) dataclassfield)datetime timedelta)AnyDict FrozenSetListOptional)algosx509)hashes)CertificateStoreSimpleCertificateStore)Signer) SigningErrorget_pyca_cryptography_hashz!Install pyHanko with [async_http] CSCSignerCSCServiceSessionInfoCSCCredentialInfofetch_certs_in_csc_credentialCSCAuthorizationInfoCSCAuthorizationManager!PrefetchedSADAuthorizationManagerT)frozenc@sReZdZUdZeed<eed<dZeeed<dZeed<dd Z e d d Z dS) rz` Information about the CSC service, together with the required authentication data. service_url credential_idN oauth_tokenZv1api_vercCs|jd|jd|S)z Complete an endpoint name to a full URL. :param endpoint_name: Name of the endpoint (e.g. ``credentials/info``). :return: A URL. z/csc//)rr)selfZ endpoint_namer!C/tmp/pip-unpacked-wheel-owvgwkas/pyhanko/sign/signers/csc_signer.py endpoint_urls z"CSCServiceSessionInfo.endpoint_urlcCs|j}|rdd|iSiS)a= HTTP Header(s) necessary for authentication, to be passed with every request. .. note:: By default, this supplies the ``Authorization`` header with the value of :attr:`oauth_token` as the ``Bearer`` value. :return: A ``dict`` of headers. AuthorizationzBearer )r)r tokr!r!r" auth_headerssz"CSCServiceSessionInfo.auth_headers) __name__ __module__ __qualname____doc__str__annotations__rr rr#propertyr&r!r!r!r"rzs   c@s\eZdZUdZejed<eejed<ee ed<e ed<e ed<e ed<e dd d Zd S) rz Information about a CSC credential, typically fetched using a ``credentials/info`` call. See also :func:`.fetch_certs_in_csc_credential`. signing_certchainsupported_mechanismsmax_batch_sizehash_pinning_required response_datareturncCs"t}||j||j|S)z Register the relevant certificates into a :class:`.CertificateStore` and return it. :return: A :class:`.CertificateStore`. )rregisterr.Zregister_multipler/)r Zscsr!r!r" as_cert_stores   zCSCCredentialInfo.as_cert_storeN)r'r(r)r*r Certificater,r rr+intbooldictrr7r!r!r!r"rs   )sessioncsc_session_infotimeoutr5c s|d}|jddd}zB|j||j|d|d4IdH}|IdH}W5QIdHRXWn.tjk r}ztd|W5d}~XYnXt|S) a Call the ``credentials/info`` endpoint of the CSC service for a specific credential, and encode the result into a :class:`.CSCCredentialInfo` object. :param session: The ``aiohttp`` session to use when performing queries. :param csc_session_info: General information about the CSC service and the credential. :param timeout: How many seconds to allow before time-out. :return: A :class:`.CSCCredentialInfo` object with the processed response. zcredentials/infor/F) credentialID certificatesZcertInfoTheadersjsonraise_for_statusr?NzCredential info request failed) r#rpostr&rDaiohttp ClientErrorr"_process_certificate_info_response)r=r>r?urlreq_dataresponser3er!r!r"rs$ "r4c Csz|dd}Wn,tk r<}ztd|W5d}~XYnXzdd|D}Wn,tk r|}ztd|W5d}~XYnXz0|dd}t|tsttd d |D}Wn2tttfk r}ztd |W5d}~XYnXzt|d }Wn2ttfk r$}ztd |W5d}~XYnX|dd}zt|}|dkrJtWntk rjtdYnX|dk}t |d|dd||||dS)NcertrAz-Could not retrieve certificates from responsecSsg|]}tjt|qSr!)r r8loadbase64 b64decode).0rNr!r!r" sz6_process_certificate_info_response..z)Could not decode certificates in responsekeyalgocss|]}t|jVqdSN)r ZSignedDigestAlgorithmIdnative)rRoidr!r!r" &sz5_process_certificate_info_response..z=Could not retrieve supported signing mechanisms from responseZ multisignz/Could not retrieve max batch size from responseZSCAL)rZzSCAL value must be "1" or "2".r[r)r.r/r0r1r2r3) KeyErrorr ValueError isinstancelist TypeError frozensetr9getr) r3Z b64_certsrMcertsZ algo_oidsZsupported_algosr1Z scal_valuer2r!r!r"rIsf       rIdatadigest_algorithmr5cCs0t|}t|}||t|dS)z Digest some bytes and base64-encode the result. :param data: Data to digest. :param digest_algorithm: Name of the digest algorihtm to use. :return: A base64-encoded hash. ascii)rr ZHashupdaterP b64encodefinalizedecode)rerfZ hash_specZmdr!r!r" base64_digestKs   rlc@s*eZdZUdZeed<dZeeed<dS)rzv Authorization data to make a signing request. This is the result of a call to ``credentials/authorize``. sadN expires_at) r'r(r)r*r+r,rnr rr!r!r!r"r]s c @seZdZdZeedddZeee dddZ de e ee ee eee ee ee d d d Zee e d ddZeddZd S)ra Abstract class that handles authorisation requests for the CSC signing client. .. note:: Implementations may wish to make use of the :meth:`format_csc_auth_request` convenience method to format requests to the ``credentials/authorize`` endpoint. :param csc_session_info: General information about the CSC service and the credential. :param credential_info: Details about the credential. r>credential_infocCs||_||_dSrVro)r r>rpr!r!r"__init__sz CSCAuthorizationManager.__init__ hash_b64sr5cstdS)a Request a SAD token from the signing service, either freshly or to extend the current transaction. Depending on the lifecycle of this object, pre-fetched SAD values may be used. All authorization transaction management is left to implementing subclasses. :param hash_b64s: Base64-encoded hash values about to be signed. :return: Authorization data. N)NotImplementedErrorr rsr!r!r"authorize_signaturesz+CSCAuthorizationManager.authorize_signaturerZN)num_signaturespinotprs description client_datar5cCspd|jji}|dk r$t|}||d<||d<|dk r<||d<|dk rL||d<|dk r\||d<|dk rl||d<|S) a Format the parameters for a call to ``credentials/authorize``. :param num_signatures: The number of signatures to request authorisation for. :param pin: The user's PIN (if applicable). :param otp: The current value of an OTP token, provided by the user (if applicable). :param hash_b64s: An explicit list of base64-encoded hashes to be tied to the SAD. Is optional if the service's SCAL value is 1, i.e. when :attr:`~.CSCCredentialInfo.hash_pinning_required` is false. :param description: A free-form description of the authorisation request (optional). :param client_data: Custom vendor-specific data (if applicable). :return: A dict that, when encoded as a JSON object, be used as the request body for a call to ``credentials/authorize``. r@NhashZ numSignaturesZPINZOTPrz clientData)r>rlen)r rwrxryrsrzr{resultr!r!r"format_csc_auth_requests !z/CSCAuthorizationManager.format_csc_auth_request)r3r5c Cszt|d}Wntk r,tdYnXz2t|dd}tjtd}|t |d}Wn,t k r}ztd|W5d}~XYnXt ||d S) a  Parse the response from a ``credentials/authorize`` call into a :class:`.CSCAuthorizationInfo` object. :param response_data: The decoded response JSON. :return: A :class:`.CSCAuthorizationInfo` object. SADz.Could not extract SAD value from auth responseZ expiresIni)tz)secondsz2Could not process expiresIn value in auth responseN)rmrn) r+r\rr9rbrnowtzlocalZ get_localzonerr]r)r3rmZlifetime_secondsrrnrMr!r!r"parse_csc_auth_responses z/CSCAuthorizationManager.parse_csc_auth_responsecCs|jjS)z HTTP Header(s) necessary for authentication, to be passed with every request. By default, this delegates to :attr:`.CSCServiceSessionInfo.auth_headers`. :return: A ``dict`` of headers. )r>r&)r r!r!r"r&s z$CSCAuthorizationManager.auth_headers)rZNNNNN)r'r(r)r*rrrqr r+rrvr9r r;r staticmethodrr-r&r!r!r!r"ros4    7cs>eZdZdZeeedfdd Zee edddZ Z S)ra Simplistic :class:`.CSCAuthorizationManager` for use with pre-fetched signature activation data. This class is effectively only useful for CSC services that do not require SAD to be pinned to specific document hashes. It allows you to use a SAD that was fetched before starting the signing process, for a one-shot signature. This can simplify resource management in cases where obtaining a SAD is time-consuming, but the caller still wants the conveniences of pyHanko's high-level API without having to keep too many pyHanko objects in memory while waiting for a ``credentials/authorize`` call to go through. Legitimate uses are limited, but the implementation is trivial, so we provide it here. :param csc_session_info: General information about the CSC service and the credential. :param credential_info: Details about the credential. :param csc_auth_info: The pre-fetched signature activation data. )r>rp csc_auth_infocst||||_d|_dS)NF)superrqr_used)r r>rpr __class__r!r"rqsz*PrefetchedSADAuthorizationManager.__init__rrcs|jrtdd|_|jS)z Return the prefetched SAD, or raise an error if called twice. :param hash_b64s: List of hashes to be signed; ignored. :return: The prefetched authorisation data. zPrefetched SAD token is staleT)rrrrur!r!r"rvs z5PrefetchedSADAuthorizationManager.authorize_signature) r'r(r)r*rrrrqr r+rv __classcell__r!r!rr"rs c@sjeZdZUdZejed<eed<ee dZ e eed<dZ e ed<dZee eed <eed d d ZdS) _CSCBatchInfoz: Internal value type to track batch control data. notifier md_algorithm)default_factory b64_hashesF initiatedNresults)b64_hashr5cCst|j}|j||SrV)r~rappend)r rixr!r!r"addMs  z_CSCBatchInfo.add)r'r(r)r*asyncioEventr,r+rr_rr rr:rr bytesr9rr!r!r!r"r-s   rc seZdZdZdejeeeee e ee edfdd Z fd d Z e e e ed d dZedddZdee edddZddZedddZZS)rar Implements the :class:`~pyhanko.sign.signers.pdf_cms.Signer` interface for a remote CSC signing service. Requests are made asynchronously, using ``aiohttp``. :param session: The ``aiohttp`` session to use when performing queries. :param auth_manager: A :class:`.CSCAuthorizationManager` instance capable of procuring signature activation data from the signing service. :param sign_timeout: Timeout for signing operations, in seconds. Defaults to 300 seconds (5 minutes). :param prefer_pss: When signing using an RSA key, prefer PSS padding to legacy PKCS#1 v1.5 padding. Default is ``False``. This option has no effect on non-RSA signatures. :param embed_roots: Option that controls whether or not additional self-signed certificates should be embedded into the CMS payload. The default is ``True``. :param client_data: CSC client data to add to any signing request(s), if applicable. :param batch_autocommit: Whether to automatically commit a signing transaction as soon as a batch is full. The default is ``True``. If ``False``, the caller has to trigger :meth:`commit` manually. :param batch_size: The number of signatures to sign in one transaction. This defaults to 1 (i.e. a separate ``signatures/signHash`` call is made for every signature). :param est_raw_signature_size: Estimated raw signature size (in bytes). Defaults to 512 bytes, which, combined with other built-in safety margins, should provide a generous overestimate. ,FTN)r= auth_manager sign_timeout prefer_pss embed_rootsr{batch_autocommit batch_sizec sX|j} ||_||_| |_||_||_||_d|_|p6d|_t j ||| j | ddS)NrZ)rrr.Z cert_registry) rprr=est_raw_signature_sizerr{r_current_batchrrrqr.r7) r r=rrrrr{rrrrprr!r"rqxs  zCSCSigner.__init__csd|jdk r|jSt|}|d}|jjj}|j|kr`td|jdddd|Dd|S)N algorithmzSignature mechanism z" is not supported, must be one of z, css|] }|VqdSrVr!)rRZalgr!r!r"rYsz?CSCSigner.get_signature_mechanism_for_digest...) Zsignature_mechanismr"get_signature_mechanism_for_digestrrpr0rWrjoin)r rfrZ result_algo supportedrr!r"rs    "z,CSCSigner.get_signature_mechanism_for_digest) tbs_hashesrfr5cs||}|jj}|j|IdH}|j|jt|j|dj|d}|dj dk rt|d }t | d|d<|jdk r|j|d<|S)a{ Populate the request data for a CSC signing request :param tbs_hashes: Base64-encoded hashes that require signing. :param digest_algorithm: The digest algorithm to use. :return: A dict that, when encoded as a JSON object, be used as the request body for a call to ``signatures/signHash``. Nr)r@rZhashAlgoZsignAlgor| parametersrgZsignAlgoParamsr})rrr>rvrrmr ZDigestAlgorithmIdZdottedrWdumprPrirkr{)r rrfZ mechanism session_infoZ auth_inforKZ params_derr!r!r"format_csc_signing_reqs$       z CSCSigner.format_csc_signing_reqr4cs|jdk rH|jjrHtd|jjIdHtdt|jdq|jdk r~|j}|j|krztd|jd|d|St t |d|_}|S)Nz*Commit ongoing... Waiting for it to finishz$Done waiting for commit: new batch: )zUAll signatures in the same batch must use the same digest function; encountered both z and r)rr) rrloggerdebugrwaitreprrrrrr)r rfbatchr!r!r" _ensure_batchs$    zCSCSigner._ensure_batchrdc s|rt|jSt||}||IdH}||}|jr||jdkrz|IdHWn0tk r}zt j d|dW5d}~XYnX|j IdH|j std|j |S)NrZzFailed to commit signatures)exc_infozNo signing results available)rrrlrrrrcommitrrerrorrrr)r rerfdry_runZtbs_hashrrrMr!r!r"async_sign_raws    zCSCSigner.async_sign_rawcs\|j}|dks|jdk rdS|jrB|jIdH|jsXtdnd|_||IdHdS)a  Commit the current batch by calling the ``signatures/signHash`` endpoint on the CSC service. This coroutine does not return anything; instead, it notifies all waiting signing coroutines that their signature has been fetched. Nz Commit failedT)rrrrrr _do_commit)r rr!r!r"rs  zCSCSigner.commit)rc sTz:z||j|jIdH}|jj}|d}|j }|j ||jj |d|j d4IdH}| IdH}W5QIdHRX|d}t|} t|j} | | krtd| d| dd |D} | |_Wnvtk rYnbtttfk r } ztd | W5d} ~ XYn0tjk r8} ztd | W5d} ~ XYnXW5d|_|jXdS) zc Internal commit routine that skips error handling and concurrency checks. Nzsignatures/signHashTrB signaturesz Expected z signatures, got cSsg|]}t|qSr!)rPrQ)rRsigr!r!r"rS6sz(CSCSigner._do_commit..z3Expected response with b64-encoded signature valueszSignature request failed)rrsetrrrrr>r#r=rFr&rrDr~rrr]r\r`rGrH) r rrKrrJr=rLr3Zsig_b64sZ actual_len expected_lenrrMr!r!r"rsL     zCSCSigner._do_commit)rFTNTNr)F)r'r(r)r*rG ClientSessionrr9r:r r+rqrr r;rrrrrrrrr!r!rr"rSs@(  0 )r<)3r*abcrrPloggingZ dataclassesrrrrtypingrrrr r rZ asn1cryptor r Zcryptography.hazmat.primitivesr Zpyhanko_certvalidator.registryrrZ pyhanko.signrZpyhanko.sign.generalrrrG ImportError__all__ getLoggerr'rrrrr9rrIrr+rlrABCrrrrr!r!r!r"s^T    =6 )6 5%