{"id":13506139,"url":"https://github.com/telefonicaid/fiware-aiakos","last_synced_at":"2026-03-01T04:34:56.181Z","repository":{"id":2536624,"uuid":"46782126","full_name":"telefonicaid/fiware-aiakos","owner":"telefonicaid","description":"Server with public API to manage ssh/gpg keys for the support user.","archived":false,"fork":false,"pushed_at":"2026-01-01T10:39:41.000Z","size":238,"stargazers_count":1,"open_issues_count":23,"forks_count":3,"subscribers_count":8,"default_branch":"develop","last_synced_at":"2026-01-06T07:54:10.256Z","etag":null,"topics":["fiware","fiware-ops","nodejs"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telefonicaid.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-11-24T09:48:35.000Z","updated_at":"2025-11-20T12:53:14.000Z","dependencies_parsed_at":"2024-03-29T23:36:07.657Z","dependency_job_id":"bcd04675-454d-4ef6-be56-69e2be4946a7","html_url":"https://github.com/telefonicaid/fiware-aiakos","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/telefonicaid/fiware-aiakos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-aiakos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-aiakos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-aiakos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-aiakos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telefonicaid","download_url":"https://codeload.github.com/telefonicaid/fiware-aiakos/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-aiakos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29960253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T01:47:18.291Z","status":"online","status_checked_at":"2026-03-01T02:00:07.437Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fiware","fiware-ops","nodejs"],"created_at":"2024-08-01T01:00:35.375Z","updated_at":"2026-03-01T04:34:56.164Z","avatar_url":"https://github.com/telefonicaid.png","language":"JavaScript","funding_links":[],"categories":["Legacy FIWARE Components"],"sub_categories":["Robotics"],"readme":".. _Top:\n\nFIWARE Aiakos\n*************\n\n|License Badge| |Documentation Badge| |Build Status| |Coverage Status|\n\n.. contents:: :local:\n\nIntroduction\n============\n\nServer with public API to manage ssh/gpg public keys for the support user of each\n`FIWARE Lab`_ node.\n\nThis project is part of FIWARE_.\n\nAny feedback on this documentation is highly welcome, including bugs, typos\nor things you think should be included but are not. You can use\n`github issues`_ to provide feedback.\n\n\nTop_\n\n\nOverall description\n===================\n\nAiakos is a service developed to store the public keys corresponding to each FIWARE\nLab node in order to secure the access to the virtual machines instantiated in the\nFIWARE Lab.\n\nEach region of FIWARE Lab must generate and provided a SSH public key and a GPG\npublic key. As a remainder,\nit is perfectly secure that people have access to public keys. Only the private\nkeys must remain secret.\n\nTop_\n\nWhy a SSH key and a GPG key are needed\n======================================\n\nThe new base images and all the images based on them, as the migrated GE images,\nhave a support account. There are two public keys with an important role in the\nsupport account:\n\n- a SSH public key: This is the only method to log in the virtual machine with\n  the support account via SSH (the password access is disabled).\n- a GPG public key: This key is used to encrypt the password of the support\n  account. That password is generated inside the VM and after the encryption\n  is printed to the console. The support account password allows to access the\n  VM via console, which is useful if the network is down. Besides, the password\n  is also needed to get full root privileges after connecting to the support\n  account both using console and ssh client due to, for security reasons, sudo is\n  configured for asking the password.\n\nAnother reason to require the support password and encrypt it is to make easy\nenforcing full control and audit of who have admin access to each VM. This is\nbecause the SSH public key is not specific of each VM, but the password yes. There\nare alternatives but more complex. For example, do not provide the SSH\nprivate key to the support staff but use an special designed ssh-agent that audit\neach access. This document describes the `protocol used by OpenSSH's ssh-agent`_.\n\nTop_\n\n\nWhy each region must use their own public keys\n==============================================\n\nThe region staff team are responsible of the virtual machines instantiated on their\nservers. Therefore each region staff should have the control of who access the virtual\nmachines for support purposes and set and enforce the corresponding policy. It is\nnot possible if the public keys are shared among all the regions. Additionally,\nit is also extremely insecure and a problem when a region leaves the federation.\n\nTop_\n\n\nHow the keys are injected inside the virtual machines. Limitations\n==================================================================\n\nThe support account is created by a script invoked at boot time. This script is named\n*activate_support_account.py* and it is available at `GlanceSync support scripts`_.\nInside this folder there is also documentation and all the material to create the base\nimages with the support account.\n\nThe script tries to download the userdata file from the metadata server. This is something\nthat cloudinit also do, but this script can do more attempts because it works in the\nbackground. However, if the metadata server is not accessible (e.g. because the network is\ndown) the script will finally give up. In this case, it will use a failback, a public SSH\nand public GPG keys hardcoded in the images. The failback keys are used also if the user\nmodify the userdata content and removes the part that provides the keys.\n\nOf course, the private key pairs hardcoded in the images cannot be shared among regions\nfor the same reasons it is recommended that each region has its own keys. However a\nprocedure could be activated to request that the support password of a specific virtual\nmachine is being encrypted using the public GPG key of the region asking for it.\n\nFinally, it must be considered that the support account can be disabled by the user, who\nhas full control of the virtual machine. For example, the support account can be deleted\nor its password changed. Also the script that create the support account can be modified\nor deleted. In those cases, the administrator looses the control over the support of the\nvirtual machine.\n\nNote that the script is run at boot time, but the support account and password only should\nbe generated in the first boot of the virtual machine. However, the encrypted password must\nbe printed at each boot, because the console logs are clean when the virtual machine is\nrebooted.\n\nIt is important to delete the support account before making a snapshot to be used as template\nof new images; indeed this is one of the steps than the procedure to create GE images do.\nOtherwise all the instantiated VMs will have the same password in the support account. The\nscript try to detect this checking if the UUID of the virtual machine has changed, but anyway\nduring a few minutes the password might remain unmodified.\n\nTop_\n\n\nHow to generate and use the keys\n================================\n\nSoftware vs hardware solution\n-----------------------------\n\nThis document only describes how to generate and use the keys through a software\nsolution, but it is also possible use a hardware device, as an smartcard.\nThe use of hardware solution is not documented here because it may be specific of\neach product, although some information will be provided AS IS to people\ninterested in an introduction and some references to start with.\n\nThe advantage of a hardware solution is that it provides better security. It\nalso make possible a full control and audit, because with a hardware solution\nthe person who uses the key cannot copy it. Most of the advantages of a\nhardware solution can be replicated using a dedicated host and an agent: this way\nsupport staff does not have access to the key and the cryptographic operations are\ndelegated to the agent.\n\nA hardware solution consists of a device that stores the private keys and does not\nallow extracting them. Most of these devices generate the keys by themselves\nand therefore nobody has a copy of the private key, while others allow storing\nan existing key. People do not need to access the private key to use it, because\nthe operations involving the key (e.g. to sign a challenge) are delegated to the\ndevice.\n\nSome hardware solutions\n-----------------------\n\nThere is neither an only solution nor standard. Some devices are intended for SSH\nkeys, other for GPG keys but also support SSH. Neither all devices are supported\nin Linux nor provided free/open source drivers.\n\n- An OpenPGP 2.0 card can be used with GPG and also with OpenSSH through the gpg-agent_.\n- The `gnuk project`_ allows using some very cheap STM32F103 microcontrollers with a USB\n  port (it installs a firmware supporting the OpenPGP 2.0 card specification). This option\n  is less secure than and smartcard or a specifically designed USB-token but safer than\n  a software solution.\n- The `OpenSC projects`_ is about using smartcards and USB-tokens through PKCS#11/PKCS#15\n  with Linux. This project does not work with GPG due to GPG does not speak PKCS#11.\n  However some devices might work with and old project (probably unmaintained) that do\n  a bridge between PCKS#11 and GPG.\n\nA very cheap solution (but not the more secure, most of the other devices are\ndesigned to resists more types of attacks, including analysing the power consume)\nis to use gnuk project with some STM32 devices. This software is designed\nfor GPG keys, but the documentation explains how to use with ssh through an\nagent.\n\nThese links are provided as reference only. The solutions described, including\nthe gnuk project commented before, have not been tested and therefore the information\nis provided AS IS, without any support.\n\nGenerating a SSH key\n--------------------\n\nA public key can be generated from different ways, including the generation of\nSSH keys from the FIWARE Lab Cloud Portal. For more details about it, we suggest\nto follow the indications in the presentation `Setting up your infrastructure using FIWARE Cloud`_\nbetween slides 19 and 23. A simple way to generate a ssh key is just running\nthis OpenSSH command:\n\n.. code::\n\n  ssh-keygen -N \"\" -f support_key\n\nThe file support_key will contain the private key. The file support_key.pub is the\nfile that contains the public key and have to be provided in to the Aiakos Service.\n\nGenerating a GPG key\n--------------------\n\nA gpg key can be generated with the following command:\n\n.. code::\n\n  gpg --gen-key\n\nIt is not convenient to run this command in a virtual machine, because it needs\na lot of entropy and the command will stop waiting for more information from\n/dev/random.\n\n**It is very important that the name of the key is *Fiware support \u003cregion\u003e*.**\nIf the key name does not start with *Fiware support* it is not detected by the\nscript that creates the support account.\n\nThe public key is exported with this command:\n\n.. code::\n\n  gpg --armor --output public.gpg --export \"Fiware support\"\n\nThe public.gpg is the file that must be provided in the Aiakos service. To decrypt\na message just execute the following command:\n\n.. code::\n\n  gpg -d message_file\n\nWhere message_file is the file in which we have found the encrypted text (in our case,\nit should be the text in the log file in which we see the encrypted password).\n\nTop_\n\n\nObtaining the password of the support account\n=============================================\n\nThe support account password is generated inside the VM, then encrypted with\nthe GPG public key and printed to the console. The console logs can be obtained\nby the owner of the VM or by an administrator using the command *nova console-log*\n\nThe following script (getpassword.sh) can be used to decrypt the password:\n\n.. code::\n\n  #!/bin/bash\n\n  export OS_AUTH_URL=http://130.206.112.3:5000/v2.0\n\n  cat \u003c\u003cEOF \u003e extract.awk\n  /-----BEGIN PGP MESSAGE-----/ {cp=1}\n  /-----END PGP MESSAGE-----/ {cp=0; msg=msg $0}\n  cp==1 {msg=msg $0 \"\\n\"} ; END {print msg}'\n  EOF\n  nova console-log $1 | awk -f ./extract.awk | gpg -d\n  rm extract.awk\n\nKeep in mind that the environment variables:\n\n.. code::\n\n  OS_REGION_NAME\n  OS_TENANT_NAME\n  OS_USERNAME\n  OS_PASSWORD\n  OS_AUTH_URL\n\nhave to be correctly configured. You can now check that the environment is\ncorrectly loaded, perform:\n\n.. code::\n  env | grep OS_\n\nTo run the script just write:\n\n.. code::\n\n  $ getpassword.sh \u003cUUID\u003e\n\nor\n\n.. code::\n\n  $ getpassword.sh \u003cvirtual machine name\u003e\n\nwhere the UUID is the UUID of the virtual machine.\n\nTop_\n\nAPI Overview\n============\n\nFirst of all, for POST request to Aiakos you need to fill x-auth-token header.\nThe header x-auth-token is mandatory because Aiakos have to validate against infrastructure the permissions to upload a key.\nThe token should be requested to keystone with a valid admin-\u003cregion\u003e user as follows:\n\n::\n\n    curl --request POST \\\n         --url http://cloud.lab.fi-ware.org:4731/v2.0/tokens \\\n         --header \"Accept: application/json\" \\\n         --header \"Content-Type: application/json\"\n         --data '{\"auth\":{\"tenantName\":\"admin\",\"passwordCredentials\":{\"username\":\"\u003cadmin-spain\u003e\",\"password\":\"zzzzzzzzzzzzz\"}}}'\n\nIn the json response, token with the value should be in *access.token.id*\n\nTo upload new/modified a gpg key to the server. You should send a POST like this:\n\n::\n\n    curl --request POST \\\n        --url http://aiakoshost/v1/support \\\n        --header 'accept: text/plain' \\\n        --header 'content-type: text/plain' \\\n        --header 'x-auth-token: 201dd9a13de844db905cb4f617cbc17d' \\\n        --data '-----BEGIN PGP PUBLIC KEY BLOCK-----\\nVersion: GnuPG v1\\n\\nmQENBFWnVCYBCADPeDMbTOkCM4MPbUMvtbAtGbUDnH3AHyZCEZZuyjeExATfT0Au\\n-----END PGP PUBLIC KEY BLOCK-----'\n\nThe result of this operation is a text/plain response with the generated key:\n\n::\n\n    -----BEGIN PGP PUBLIC KEY BLOCK-----\n    Version: GnuPG v1\n\n    mQENBFWnVCYBCADPeDMbTOkCM4MPbUMvtbAtGbUDnH3AHyZCEZZuyjeExATfT0Au\n    -----END PGP PUBLIC KEY BLOCK-----\n\n\nPlease have a look at the `API Reference Documentation`_ section below for more description and operations.\n\nAPI Reference Documentation\n---------------------------\n\n- `FIWARE Aiakos v1 (Apiary)`__\n\n__ `FIWARE Aiakos - Apiary`_\n\n\nTop_\n\n\nInstallation\n============\n\nUsing FIWARE package repository (recommended)\n--------------------------------------------\n\nRefer to the documentation of your Linux distribution to set up the URL of the\nrepository where FIWARE packages are available (and update cache, if needed).\nCurrently, ``http://repositories.lab.fiware.org/repo/rpm/x86_64``\n\nThen, use the package tool to install ``fiware-aiakos``::\n\n    $ sudo yum install fiware-aiakos\n\n\nConfiguration file\n------------------\n\nAlthough some options can be specified from the command line, as a general rule\nthe use of a configuration file is preferable:\n\n- ``/etc/sysconfig/aiakos.yml`` (when running system service)\n- ``{installation_path}/config/aiakos.yml`` (when running manually)\n\nSuch configuration file is self-documented, so you will find a description of\nevery configuration option there.\n\nAfter installing and configuring the service, you can execute the service with the following command::\n\n    $ sudo service fiware-aiakos start\n\nAnd to stop the service, run::\n\n    $ sudo service fiware-aiakos stop\n\n\nIn order to test the service is running, run::\n\n    $ curl http://localhost:3000/v1/support/example/sshkey\n\nTop_\n\nSSH and PGP keys\n----------------\n\nThe key files for aiakos are stored in the folder /opt/fiware-aiakos/lib/public/keys.\nThe naming must be \u003cregion_name\u003e.sshkey and \u003cregion_name\u003e.gpgkey (lowercase is mandatory)\n\nTop_\n\nUnit tests\n----------\n\nThe ``test`` target is used for running the unit tests in the component::\nFirst of all, install `grunt tools \u003chttp://gruntjs.com/installing-grunt\u003e`_. Previous to it, remove old versions of grunt and grunt-cli.\nInstall grunt as follow::\n\n   $ npm install\n   $ npm install -g grunt-cli\n\nNow, you can run the tests::\n\n    $ cd fiware-aiakos\n    $ grunt test\n\nTop_\n\nAcceptance tests\n----------------\n\nIn order to launch the acceptance test, there is a project developed in python+behave framework.\nPlease refer to `component, integration and e2e testing \u003ctest/acceptance/README.rst\u003e`_ for more information.\n\nTop_\n\nBuild\n-----\n\nUse the script provided for generate the package for the OS used::\n\n    $ tools/build/package.sh\n\nPlease refer to `4. Run PackageGenerator \u003cdocker/README.md\u003e`_ for more information about how to upload rpm to fiware\n repositories.\n\n\nTop_\n\nDocker image\n------------\n\nYou can use this `Dockerfile`_ to launch/execute the Docker image and container::\n\n    $ docker build -t fiwareaiakos .\n    $ docker run -p 3000:3000 -d fiwareaiakos\n\nIf you want to get more information about the use of docker see `How to use Aiakos with Docker \u003cdocker/README.md\u003e`_.\n\nTop_\n\n\nLicense\n=======\n\n\\(c) 2015 Telefónica I+D, Apache License 2.0\n\nTop_\n\n.. IMAGES\n\n.. |Build Status| image:: https://travis-ci.org/telefonicaid/fiware-aiakos.svg?branch=develop\n   :target: https://travis-ci.org/telefonicaid/fiware-aiakos\n   :alt: Build Status\n.. |Coverage Status| image:: https://coveralls.io/repos/github/telefonicaid/fiware-aiakos/badge.svg?branch=develop\n   :target: https://coveralls.io/github/telefonicaid/fiware-aiakos?branch=develop\n   :alt: Coverage Status\n.. |License Badge| image:: https://img.shields.io/badge/license-Apache_2.0-blue.svg\n   :target: LICENSE\n   :alt: Apache 2.0\n.. |Documentation Badge| image:: https://readthedocs.org/projects/fiware-aiakos/badge/?version=latest\n   :target: http://fiware-aiakos.readthedocs.org/en/latest/?badge=latest\n\n\n.. REFERENCES\n\n.. _FIWARE: http://www.fiware.org/\n.. _FIWARE Lab: https://www.fiware.org/lab/\n.. _`github issues`: https://github.com/telefonicaid/fiware-aiakos/issues\n.. _FIWARE Aiakos - Apiary: https://jsapi.apiary.io/apis/fiwareaiakos/reference.html\n.. _`Dockerfile`: docker/Dockerfile\n.. _protocol used by OpenSSH's ssh-agent: http://api.libssh.org/rfc/PROTOCOL.agent\n.. _`GlanceSync support scripts`: https://github.com/telefonicaid/fiware-glancesync/tree/develop/fiwareglancesync/scripts/support\n.. _gpg-agent: https://gnupg.org/documentation/manuals/gnupg-2.0/Invoking-GPG_002dAGENT.html\n.. _`Setting up your infrastructure using FIWARE Cloud`: http://www.slideshare.net/flopezaguilar/setting-up-your-virtual-infrastructure-using-fi-lab-cloud-32388357\n.. _`gnuk project`: http://www.fsij.org/doc-gnuk/intro.html\n.. _`OpenSC projects`: https://github.com/OpenSC/OpenSC/wiki/Frequently-Asked-Questions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelefonicaid%2Ffiware-aiakos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelefonicaid%2Ffiware-aiakos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelefonicaid%2Ffiware-aiakos/lists"}