Metadata-Version: 2.4
Name: pyfva
Version: 0.0.45
Summary: Cliente para conectar instituciones con BCCR FVA.
Home-page: https://github.com/solvo/pyfva
Author: Luis Zarate Montero
Author-email: Luis Zárate <luis.zarate@solvosoft.com>
Maintainer-email: Luis Zárate <luis.zarate@solvosoft.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/Solvosoft/pyfva
Project-URL: Documentation, https://pyfva.readthedocs.org
Project-URL: Repository, https://github.com/Solvosoft/pyfva.git
Project-URL: Issues, https://github.com/Solvosoft/pyfva/issues
Project-URL: Changelog, https://github.com/Solvosoft/pyfva/blob/master/CHANGELOG.md
Keywords: firma,digital,gaudi
Platform: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: pytz>=2025.2
Requires-Dist: requests>=2.31.0
Provides-Extra: soap
Requires-Dist: soapfish2>=0.7.2; extra == "soap"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: platform

pyfva
#######

Cliente para conectar instituciones con BCCR_ FVA.

Abstrae la comunicación entre los servicios SOAP del BCCR_  y python creando clientes de fácil uso, por ejemplo si se desea autenticar a una persona se realizaría como

.. code:: python

    from pyfva.clientes.autenticador import ClienteAutenticador

    authclient = ClienteAutenticador(1,1) # negocio, entidad

    if authclient.validar_servicio():
        data = authclient.solicitar_autenticacion('08-0888-0888')
    else:
        # warnings.warn("Auth BCCR No disponible", RuntimeWarning)
        data = authclient.DEFAULT_ERROR

.. _BCCR: http://www.bccr.fi.cr/

Enlaces de interés
#######################

Los siguientes enlaces son de proyectos de interés relacionados con el desarrollo de firma digital.

- `Receptor de Notificiaciones BCCR`_
- `Ventanas de Usuario`_
- `Pyfva: Cliente para integración con Python`_
- `Firmador Libre, aplicación de escritorio`_


.. _`Receptor de Notificiaciones BCCR`: https://git.ucr.ac.cr/firma_comunidad/receptor-de-notificaciones-del-bccr
.. _`Ventanas de Usuario`: https://git.ucr.ac.cr/firma_comunidad/ventanas_usuario
.. _`Pyfva: Cliente para integración con Python`: https://github.com/solvo/pyfva
.. _`Firmador Libre, aplicación de escritorio`: https://gitlab.com/firmador/firmador

Instalación
##############


Instale mediante pypi

.. code:: bash

    pip install pyfva[soap]

o usando el repositorio

.. code:: bash

    pip install git+https://github.com/solvo/pyfva.git

en caso de solo querer los servicios Rest

   pip install pyfva

Documentación
################

Por supuesto la documentoación está aquí_

.. _aquí: http://pyfva.readthedocs.io/

Parámetros de ambiente
#############################

Los siguientes parámetros pueden ser modificados usando variables de entorno o variables en django settings.

Los valores por defecto son:

* FVA_HOST = "http://bccr.fva.cr/"
* RECEPTOR_HOST = 'http://bccr.fva.cr/'

Ambos son direcciones del esquema, deben ser iguales al esquema del servicio WSDL.

* STUB_SCHEME = 'http'
* STUB_HOST = "localhost:8001"

Dirección y protocolo donde se ubica el servicio FVA.

* DEFAULT_BUSSINESS = 1
* DEFAULT_ENTITY = 1

.. note:: En la mayoría de los casos el DEFAULT_ENTITY será 1 y el DEFAULT_BUSSINESS corresponde al

Números de identificación en el servicio FVA. (en el simulador no son usados).

* RECEPTOR_CLIENT = 'pyfva.receptor.client'

Cliente para recibir las respuestas del FVA.

Configurando entorno del BCCR externo
#######################################
Las siguientes configuraciones son requeridas, los archivos deben estar en formato PEM

* REQUESTS_CA_BUNDLE=/<ruta de archivo>/ca_nacional_de_CR.pem
* REQUESTS_CA_PATH=/<ruta de archivo>/ca_nacional_de_CR.pem
* REQUESTS_CERT_PATH=/<ruta de archivo>/bccr_agent.pem
* REQUESTS_KEY_PATH=/<ruta de archivo>/bccr_agent_key.pem
* STUB_SCHEME = 'https'
* STUB_HOST = "firmadorexterno.bccr.fi.cr"


Para realizar pruebas de conexión es importante configurar una comunicación por ssl, los siguientes comándos pueden ser de ayuda

1. Unifica la cadena de certificados de confianza

Puede descargarse desde

- https://www.bccr.fi.cr/firma-digital/DocFirmaDigital/Jerarquia-Persona-Juridica-Produccion-entregar-entidades-externas.zip

Convierta los archivos a PEM

.. code:: bash

    openssl x509 -in 'CA POLITICA PERSONA JURIDICA - COSTA RICA v2.cer' -out 'CA POLITICA PERSONA JURIDICA - COSTA RICA v2.pem' -inform DER
    openssl x509 -in 'CA SINPE - PERSONA JURIDICA v2.cer' -out 'CA SINPE - PERSONA JURIDICA v2.pem' -inform DER
    openssl x509 -in 'CA RAIZ NACIONAL - COSTA RICA v2.cer' -out 'CA RAIZ NACIONAL - COSTA RICA v2.pem' -inform DER
    cp 'Certificado BANCO CENTRAL DE COSTA RICA (AGENTE ELECTRONICO).cer' 'Certificado BANCO CENTRAL DE COSTA RICA (AGENTE ELECTRONICO).pem'
    cp 'CA SINPE - PERSONA JURIDICA v2(1).crt' 'CA SINPE - PERSONA JURIDICA v2(1).pem'

.. code:: bash

    cat  'CA RAIZ NACIONAL - COSTA RICA v2.pem' 'CA POLITICA PERSONA JURIDICA - COSTA RICA v2.pem' 'CA SINPE - PERSONA JURIDICA v2.pem' 'CA SINPE - PERSONA JURIDICA v2(1).pem' > ca_nacional_de_CR.pem

2. Verifique que su certificado está validado por la CA que acaba de crear

.. code:: bash

    openssl verify -verbose -CAfile ca_nacional_de_CR.pem  bccr_agent.pem

3. Verifica que puede realizar una conexión con el BCCR autenticándose con el certificado

.. code:: bash

    curl --http1.1 --cert bccr_agent.pem --key bccr_agent_key.pem --cacert ca_nacional_de_CR.pem https://firmadorexterno.bccr.fi.cr:443/WebServices/Bccr.Fva.Entidades.AmbDePruebas.Sello.Ws.SI/SelladorElectronicoConControlDeLlave.asmx?wsdl

4. Verifique que puede puede recibir notificaciones

.. code:: bash

   openssl s_server -key bccr_agent_key.pem -cert bccr_agent.pem -CAfile ca_nacional_de_CR.pem -accept 8443 -www -tlsextdebug -debug -cipher ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA:AES128-SHA256:AES256-SHA256 -tls1_2 -named_curve P-256

Las siguientes funciones pueden ser de ayuda para deteminar los cálculos

.. code:: python

    def get_digest(digest_name):
        if 'sha256' == digest_name:
            return hashlib.sha256()
        elif 'sha384' == digest_name:
            return hashlib.sha384()
        elif 'sha512' == digest_name:
            return hashlib.sha512()
    def get_hash_sum(data, algorithm, b64=False):
        if type(data) == str:
            data = data.encode()
        digest = get_digest(algorithm)
        digest.update(data)
        if b64:
            return base64.b64encode(digest.digest()).decode()
        hashsum = digest.hexdigest()
        return hashsum

Para leer un archivo se puede utilizar algo como esto

.. code:: python

    with open('/<ruta al archivo>/test.docx', 'rb') as arch:
        FI = arch.read()
        ARCH = base64.b64encode(FI).decode()
        HASH = get_hash_sum(FI, 'sha512', b64=True)
        data = stampclient.firme(ARCH, 'msoffice', hash_doc=HASH)

Generar documentación
#############################

Instale Sphinx mediante pypi

.. code:: bash

    pip install -U Sphinx sphinx_rtd_theme

Cambiese de directorio y ejecute la creación de códigos

.. code:: bash

    cd docs
    bash build_doc.sh

Para regenerar la documentación, si no se tienen cambios en los códigos de error

.. code:: bash

    make html



Correr las pruebas
#############################

Cree una carpeta llamada  **certs** en la base del proyecto y ponga ahí los certificados y llaves privadas

* ca_nacional_de_CR.pem
* bccr_agent.pem
* bccr_agent_key.pem

Se necesita correr la aplicación que recibirá las peticiones desde el BCCR


.. code:: bash

    cd demo
    ./run_receptor.sh

En caso de correrse de forma local no olvidar

.. code:: bash

    python manage.py createcachetable

Luego sobre pyfva se ejecuta

.. code:: bash

    python -m unittest pyfva.tests


Crear y correr con Docker las pruebas
#######################################

note:: El archivo run_test.sh debe modificar el negocio y la entidad antes de generar la imagen

El receptor escucha el puerto 0.0.0.0:8443/notifica, esto debería estar registrado en central directo con el nombre de dominio
adecuado.

Para construir la imagen.

.. code:: bash

    docker build -t pyfva .



Para correr una instancia de pruebas.

.. code:: bash

    docker run --name pyfvatest -v  `pwd`/certs:/app/certs -p 8443:8443 pyfva

Para correr las pruebas.

.. code:: bash

    docker exec -ti  pyfvatest bash
    cd /app
    bash run_test.sh
