{"id":21388096,"url":"https://github.com/grisp/grisp_cryptoauth","last_synced_at":"2025-07-13T15:32:17.115Z","repository":{"id":45936832,"uuid":"344479049","full_name":"grisp/grisp_cryptoauth","owner":"grisp","description":"Secure Element for GRiSP2","archived":false,"fork":false,"pushed_at":"2024-07-29T14:31:59.000Z","size":173,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-30T16:55:46.478Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grisp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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}},"created_at":"2021-03-04T13:11:59.000Z","updated_at":"2024-07-29T14:31:44.000Z","dependencies_parsed_at":"2024-06-12T15:28:20.646Z","dependency_job_id":"84b91cf2-07ad-41f5-89bd-3e3537a0461f","html_url":"https://github.com/grisp/grisp_cryptoauth","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grisp%2Fgrisp_cryptoauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grisp%2Fgrisp_cryptoauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grisp%2Fgrisp_cryptoauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grisp%2Fgrisp_cryptoauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grisp","download_url":"https://codeload.github.com/grisp/grisp_cryptoauth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225893696,"owners_count":17540918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-22T12:15:57.465Z","updated_at":"2024-11-22T12:15:58.177Z","avatar_url":"https://github.com/grisp.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"grisp_cryptoauth\n================\n\nSecure Element (Microchip ATECC608B) support for GRiSP2 based on cryptoauthlib.\n\nUsing `grisp_cryptoauth` it is possible to set up TLS connections using private\nkeys and certificates stored within the ATECC608B. Both PKCS11 (using Erlang's\ncrypto engines) and 'plain' access to the device can be used. The latter currently\nrequires an additional patch. RTEMS based GRiSP2 applications can't use PKCS11\ndue to restrictions on dynamic libraries.\n\n\nBuild\n-----\n\nThis is meant to be build within the GRiSP2 toolchain or on a linux distribution\nwith cryptoauthlib installed, build within the `grisp_linux_builder`.\n\nJust add it as dependency in rebar3 in your main application.\n\n\nDevelopment\n-----------\n\nWhen included as a dependency in an application, is is possible to define\nthe macro ENUMATE_CRYPTOAUTH using overrides:\n\n        {overrides, [\n            {add, grisp_cryptoauth, [{erl_opts, [{d, 'EMULATE_CRYPTOAUTH'}]}]}\n        ]},\n\nWith this defined, the extra configuration keys `client_cert`, `client_key` and\n`tls_verify` can be specified to be used instead of the secure element.\n\nThis allow an application depending on grisp_cryptoauth to run tests and local\nshell.\n\n\nDevice Support\n--------------\n\nThis library follows the ATECC608B-TFLXTLS configuration, that means in particular:\n\n* one unchangable primary private key\n* three changable secondary private keys\n* sign and verify operations on the keys above\n* two (primary and secondary) changable slots for compressed certificates\n* possibility to lock slots if you really want to\n* high quality random byte generator\n\nMore to come :).\n\n\nConfiguring TLS Options\n-----------------------\n\nBy configuring grisp_cryptoauth, multiple application can request the TLS\noptions required to connect to a given server, assuming that all the servers\nhave the same security requirments. The following options are used to build\nthe TLS options:\n\n\n* `tls_use_client_certificate`\n\nConfigures if TLS cponnections should use the client certificate. Default: true.\n\n\n* `tls_client_trusted_certs`\n\nConfigures the client trusted certificates.\n\nShould provide all the additional certificates required to validate to the\nclient root CA, alongside the `tls_client_trusted_certs_cb` option.\n\nPoint to a directory from where all the `.pem` and `.crt` files will be loaded,\nor to a single PEM file that could contain multiple certificates.\n\nThe configuration could either be an absolute path, a path relative to the\n`priv` directory of a given application, or a path relative to an application\n`test` directory.\n\nIf not specified, it will use the default certificate chain matching the\nclient certificate.\n\ne.g.\n\n```Erlang\n{tls_client_trusted_certs, \"/absolute/path/to/directory\"}\n{tls_client_trusted_certs, \"/absolute/path/to/single.pem\"}\n{tls_client_trusted_certs, {priv, my_app, \"relative/path/to/directory\"}}\n{tls_client_trusted_certs, {priv, my_app, \"relative/path/to/single.pem\"}}\n{tls_client_trusted_certs, {test, my_app, \"relative/path/to/directory\"}}\n{tls_client_trusted_certs, {test, my_app, \"relative/path/to/single.pem\"}}\n```\n\n* `tls_client_trusted_certs_cb`\n\nConfigures the client trusted certificates.\n\nShould provide all the additional certificates required to validate to the\nclient root CA, alongside the `tls_client_trusted_certs` option.\n\nDefine a callback function the will return the client trusted certificates\nas a list of DER encoded certificates.\n\ne.g.\n\n```Erlang\n{tls_client_trusted_certs_cb, {my_mod, my_fun}}}\n{tls_client_trusted_certs_cb, {my_mod, my_fun, [some, arguments]}}}\n```\n\n* `tls_server_trusted_certs`\n\nConfigures the server trusted certificates.\n\nShould provide the certification chain for veryfying the server certificates,\nalongside the `tls_server_trusted_certs_cb` option.\n\nPoint to a directory that should contain a PEM file with extension `.pem`\nor `.crt` with the name of the domain the TLS connection is for. If multiple\ncertificates are required, the file must contain the full chain.\nIf the path is set to `/foo/bar`, and the server doain name is `grisp.org`,\nthe TLS configuration will try the certificate `/foo/bar/grisp.org.pem` or\n`/foo/bar/grisp.org.crt` if any exists.\n\nThe configuration could either be an absolute path, a path relative to the\n`priv` directory of a given application, or a path relative to an application\n`test` directory.\n\ne.g.\n\n```Erlang\n{tls_server_trusted_certs, \"/absolute/path/to/directory\"}\n{tls_server_trusted_certs, {priv, my_app, \"relative/path/to/directory\"}}\n{tls_server_trusted_certs, {test, my_app, \"relative/path/to/directory\"}}\n```\n\n* `tls_server_trusted_certs_cb`\n\nConfigures the server trusted certificates.\n\nShould provide the certification chain for veryfying the server certificates,\nalongside the `tls_server_trusted_certs` option.\n\nDefine a callback function the will return the client trusted certificates\nas a list of DER encoded certificates.\n\ne.g.\n\n```Erlang\n{tls_server_trusted_certs_cb, {certifi, cacerts}}}\n{tls_server_trusted_certs_cb, {my_mod, my_fun, [some, arguments]}}}\n```\n\n* `client_certs`\n\nWhen EMULATE_CRYPTOAUTH macro is defined, this configures the certificate to\nuse instead of the secure element's one when generating TLS options.\n\nThe configuration could either be an absolute path, a path relative to the\n`priv` directory of a given application, or a path relative to an application\n`test` directory.\n\ne.g.\n\n```Erlang\n{client_certs, \"/absolute/path/to/some.pem\"}\n{client_certs, {priv, my_app, \"relative/path/to/some.crt\"}}\n{client_certs, {test, my_app, \"relative/cert.pem\"}}\n```\n\n* `client_key`\n\nWhen EMULATE_CRYPTOAUTH macro is defined, this configures the private key to\nuse instead of the secure element's one when generating TLS options.\n\nThe configuration could either be an absolute path, a path relative to the\n`priv` directory of a given application, or a path relative to an application\n`test` directory.\n\ne.g.\n\n```Erlang\n{client_key, \"/absolute/path/to/some.pem\"}\n{client_key, {priv, my_app, \"relative/path/to/some.key\"}}\n{client_key, {test, my_app, \"relative/key.pem\"}}\n```\n\n* `tls_verify`\n\nWhen EMULATE_CRYPTOAUTH macro is defined, this allow overriding server\ncertificate verification for development or testing. By default it is\n`verify_peer` but can be set to `verify_none`.\n\ne.g.\n\n```Erlang\n{tls_verify, verify_none}\n```\n\n\nSetting Up TLS Manually\n-----------------------\n\nErlang's `ssl` library is used for setting up TLS/mTLS. For the device\nyou need to honor at least the following options:\n#### OTP \u003e= 27\n```\n{certs_keys, [#{\n    cert =\u003e ClientChain,\n    key =\u003e #{\n        algorithm =\u003e ecdsa,\n        sign_fun =\u003e fun grisp_cryptoauth:sign_fun/3\n    }\n}]}\n```\n#### Legacy tls options: OTP =\u003c 26\nThere is a patch necessary to make use of `grisp_cryptoauth` for TLS. This\npatch is included in this repository and is tested for Erlang `23.3.4.10`, this patch has been adapted and maintained until OTP 26. We do not apply any SSL patch from OTP 27.\n\n```\n%% device certificate\n{cert, grisp_cryptoauth:read_cert(primary, der)}\n\n%% access to primary private key for TLS handshake\n{key, #{algorithm =\u003e ecdsa, sign_fun =\u003e {grisp_cryptoauth, sign_fun}}}\n```\n\nDon't forget to also add the appropriate CA certificates using e.g. the\n`cacerts` option! You can read the CA certificate files using e.g.\n\n```\ngrisp_cryptoauth_cert:decode_pem_file(\"path/to/file\", der)\n```\n\nThere have been problems in erlang 23 with mTLS. If (and only if) problems\noccur try adding one or both of the following options to enforce proper behaviour:\n\n```\n{signature_algs, [{sha256, ecdsa}]}\n{signature_algs_cert, [ecdsa_secp256r1_sha256]}\n```\n\n\nWriting Certificates\n--------------------\n\n```\nPrivateKey = public_key:generate_key({namedCurve, secp256r1}).\nCert = grisp_cryptoauth_cert:sign(test, PrivateKey).\ngrisp_cryptoauth:write_cert(primary, test, Cert).\n```\n\n\nOutlook\n-------\n\nThis library currently contains functionalities that should be split into\na couple of new libraries, in particular:\n\n* NIF based library for `cryptoauthlib` supporting more devices\n* certificate handling library, nice glue for Erlang certificate records\n* client package for supporting GRiSP2 SaaS system\n\n\nNotes\n-----\n\n* We follow Microchips compressed certificate format [1] and OpenSSL 'best practice'\n* The signature size is 64 bytes max, hence you should sign the device certificate over the P-256 curve\n* The above point means that you need to use a P-256 based CA key\n* The validity dates must align with an expire time of years, e.g. multiples of 365 days\n* Like OpenSSL we use utcTime before (including) 2049 and generalTime afterwards for certificate validity\n\n[1] https://ww1.microchip.com/downloads/en/Appnotes/20006367A.pdf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrisp%2Fgrisp_cryptoauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrisp%2Fgrisp_cryptoauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrisp%2Fgrisp_cryptoauth/lists"}