{"id":18892375,"url":"https://github.com/hf/nsm","last_synced_at":"2025-04-14T23:31:32.349Z","repository":{"id":46253113,"uuid":"326508709","full_name":"hf/nsm","owner":"hf","description":"Nitro Security Module for Go","archived":false,"fork":false,"pushed_at":"2022-09-30T14:01:12.000Z","size":35,"stargazers_count":19,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-06-18T18:49:30.890Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hf.png","metadata":{"files":{"readme":"README.md","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}},"created_at":"2021-01-03T21:59:54.000Z","updated_at":"2024-06-12T13:22:43.000Z","dependencies_parsed_at":"2022-09-07T17:02:33.826Z","dependency_job_id":null,"html_url":"https://github.com/hf/nsm","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hf%2Fnsm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hf%2Fnsm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hf%2Fnsm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hf%2Fnsm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hf","download_url":"https://codeload.github.com/hf/nsm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223651389,"owners_count":17179919,"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-08T08:01:39.672Z","updated_at":"2024-11-08T08:03:02.956Z","avatar_url":"https://github.com/hf.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nitro Security Module Interface for Go\n\n[![Go Report Card][go-reportcard-badge]][go-reportcard] [![Go Reference][pkg.go.dev-badge]][pkg.go.dev]\n\nThis is an implementation of the [AWS Nitro Security Module][nsm] interface for\nGo. Nitro Enclaves only support Linux OSs on X86 or X64, so this package is not\nintended to be used on other OSs or architectures.\n\n## Usage\n\nYou can import the package like so:\n\n```go\nimport (\n    \"github.com/hf/nsm\"\n)\n```\n\nThe NSM interface implements a request/response communication model. Consult\nthe `request` and `response` subpackages for all possible requests and\nresponses.\n\nYou open a communication channel with the NSM device by opening a new NSM\n`Session` like so:\n\n```go\nsess, err := nsm.OpenDefaultSession()\n```\n\nUse the `Send` function on the `Session` to send a new `Request` and receive\nits `Response`. The response struct always has one and only one field set with\na non-zero value. Regardless, always check the `Error` field for a possible\nerror message returned from the NSM driver.\n\n### Performance\n\nYou can open as many sessions as the OS will allow. You can send as many\nrequests on any session, from as many goroutines as resources allow. Sending\nto, reading from and closing a session at the same time is not thread safe;\nsending requests, and reading entropy at the same time is thread safe.\n\nEach `Send` and `Receive` reserve 16KB of memory per call. This is the way the\nNSM IOCTL interface is designed, so memory exhaustion may occur if you send a\nrequest or read entropy at once from many threads. Memory allocations are\namortized across multiple invocations, so GC pressure should not be a\nsignificant concern.\n\nSince the underlying transport is an IOCTL, each call performs a syscall with a\nblocking context switch on that thread. The NSM driver also context-switches on\nthe Nitro hypervisor, so each request is quite expensive. Use them sparingly.\nFor example, ask for an attestation only a couple of times within the\nimplementation of some protocol; use the random entropy to seed a [NIST\nSP800-90A DRBG][nist-sp800-90a].\n\n### Reading Entropy\n\nNitro Enclaves don't get access to `/dev/random` or `/dev/urandom`, but you can\nuse the NSM to generate cryptographically secure pseudo-random numbers\n(entropy). A `Session` is also an `io.Reader` that asks the NSM for random\nbytes.\n\nHere's an example how you can use the NSM for entropy:\n\n```go\nimport (\n    \"crypto/rand\"\n    \"math/big\"\n    \"github.com/hf/nsm\"\n)\n\nfunc generateBigPrime() (*big.Int, error) {\n    sess, err := nsm.OpenDefaultSession()\n    defer sess.Close()\n\n    if nil != err {\n        return nil, err\n    }\n\n    return rand.Prime(sess, 2048)\n}\n```\n\n### Obtaining an Attestation Document\n\nHere's an example of how you can get an [attestation \ndocument][aws-nitro-attestation]:\n\n```go\nimport (\n    \"errors\"\n    \"github.com/hf/nsm\"\n    \"github.com/hf/nsm/request\"\n)\n\nfunc attest(nonce, userData, publicKey []byte) ([]byte, error) {\n    sess, err := nsm.OpenDefaultSession()\n    defer sess.Close()\n\n    if nil != err {\n        return nil, err\n    }\n\n    res, err := sess.Send(\u0026request.Attestation{\n        Nonce: nonce,\n        UserData: userData,\n        PublicKey: publicKey,\n    })\n    if nil != err {\n        return nil, err\n    }\n\n    if \"\" != res.Error {\n        return nil, errors.New(string(res.Error))\n    }\n\n    if nil == res.Attestation || nil == res.Attestation.Document {\n        return nil, errors.New(\"NSM device did not return an attestation\")\n    }\n\n    return res.Attestation.Document, nil\n}\n```\n\nThere's a full example in `example/attestation`.\n\n## Reference Implementation\n\nThis implementation is based on the [Nitro Enclaves SDK][nitro-enclaves-sdk]\nfrom AWS, which is written in Rust. This implementation is a pure Go\nimplementation of the same interface; thus you can use it to prepare\nreproducible builds without relying on `cgo`.\n\n## License\n\nCopyright \u0026copy; 2021 Stojan Dimitrovski. Licensed under the MIT License. See\n`LICENSE` for more information.\n\n[go-reportcard-badge]: https://goreportcard.com/badge/github.com/hf/nsm\n[go-reportcard]: https://goreportcard.com/report/github.com/hf/nsm\n[pkg.go.dev-badge]: https://pkg.go.dev/badge/github.com/hf/nsm.svg\n[pkg.go.dev]: https://pkg.go.dev/github.com/hf/nsm\n\n[nsm]: https://github.com/aws/aws-nitro-enclaves-nsm-api\n[aws-nitro-attestation]: https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html\n[nitro-enclaves-sdk]: https://github.com/aws/aws-nitro-enclaves-nsm-api\n[nist-sp800-90a]: https://csrc.nist.gov/publications/detail/sp/800-90a/rev-1/final\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhf%2Fnsm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhf%2Fnsm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhf%2Fnsm/lists"}