https://github.com/cedarcode/cose-ruby
Ruby implementation of RFC 8152 CBOR Object Signing and Encryption (COSE)
https://github.com/cedarcode/cose-ruby
cbor cose cose-key rfc ruby signing
Last synced: 5 months ago
JSON representation
Ruby implementation of RFC 8152 CBOR Object Signing and Encryption (COSE)
- Host: GitHub
- URL: https://github.com/cedarcode/cose-ruby
- Owner: cedarcode
- License: mit
- Created: 2018-06-08T21:49:54.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-02-21T19:18:03.000Z (8 months ago)
- Last Synced: 2025-04-16T06:30:35.397Z (6 months ago)
- Topics: cbor, cose, cose-key, rfc, ruby, signing
- Language: Ruby
- Homepage: https://rubygems.org/gems/cose
- Size: 300 KB
- Stars: 17
- Watchers: 3
- Forks: 9
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Security: SECURITY.md
Awesome Lists containing this project
README
# cose-ruby
Ruby implementation of RFC [8152](https://tools.ietf.org/html/rfc8152) CBOR Object Signing and Encryption (COSE)
[](https://rubygems.org/gems/cose)
[](https://github.com/cedarcode/cose-ruby/actions)
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'cose'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install cose
## Usage
### Key Objects
#### Deserialization (from CBOR to Ruby objects)
```ruby
cbor_data = "..."
key = COSE::Key.deserialize(cbor_data)
```
Once you have a `COSE::Key` instance you can either access key parameters directly and/or convert it to an
`OpenSSL::PKey::PKey` instance (if supported for the key type) for operating with it
(encrypting/decrypting, signing/verifying, etc).
```ruby
# Convert to an OpenSSL::PKey::PKey
if key.respond_to?(:to_pkey)
openssl_pkey = key.to_pkey
end
# Access COSE key parameters
case key
when COSE::Key::OKP
key.crv
key.x
key.d
when COSE::Key::EC2
key.crv
key.x
key.y
key.d
when COSE::Key::RSA
key.n
key.e
key.d
key.p
key.q
key.dp
key.dq
key.qinv
when COSE::Key::Symmetric
key.k
end
```
If you already know which COSE key type is encoded in the CBOR data, then:
```ruby
okp_key_cbor = "..."
cose_okp_key = COSE::Key::OKP.deserialize(okp_key_cbor)
cose_okp_key.crv
cose_okp_key.x
cose_okp_key.d
```
```ruby
ec2_key_cbor = "..."
cose_ec2_key = COSE::Key::EC2.deserialize(ec2_key_cbor)
cose_ec2_key.crv
cose_ec2_key.x
cose_ec2_key.y
cose_ec2_key.d
# or
ec_pkey = cose_ec2_key.to_pkey # Instance of an OpenSSL::PKey::EC
```
```ruby
symmetric_key_cbor = "..."
cose_symmetric_key = COSE::Key::Symmetric.deserialize(symmetric_key_cbor)
cose_symmetric_key.k
```
```ruby
rsa_key_cbor = "..."
cose_rsa_key = COSE::Key::RSA.deserialize(rsa_key_cbor)
cose_rsa_key.n
cose_rsa_key.e
cose_rsa_key.d
cose_rsa_key.p
cose_rsa_key.q
cose_rsa_key.dp
cose_rsa_key.dq
cose_rsa_key.qinv
# or
rsa_pkey = cose_rsa_key.to_pkey # Instance of an OpenSSL::PKey::RSA
```
#### Serialization (from Ruby objects to CBOR)
```ruby
ec_pkey = OpenSSL::PKey::EC.new("prime256v1").generate_key
cose_ec2_key_cbor = COSE::Key.serialize(ec_pkey)
```
```ruby
rsa_pkey = OpenSSL::PKey::RSA.new(2048)
cose_rsa_key_cbor = COSE::Key.serialize(rsa_pkey)
```
### Signing Objects
#### COSE_Sign
```ruby
cbor_data = "..."
sign = COSE::Sign.deserialize(cbor_data)
# Verify by doing (key should be a COSE::Key):
sign.verify(key)
# or, if externally supplied authenticated data exists:
sign.verify(key, external_aad)
# Then access payload
sign.payload
```
#### COSE_Sign1
```ruby
cbor_data = "..."
sign1 = COSE::Sign1.deserialize(cbor_data)
# Verify by doing (key should be a COSE::Key):
sign1.verify(key)
# or, if externally supplied authenticated data exists:
sign1.verify(key, external_aad)
# Then access payload
sign1.payload
```
### MAC Objects
#### COSE_Mac
```ruby
cbor_data = "..."
mac = COSE::Mac.deserialize(cbor_data)
# Verify by doing (key should be a COSE::Key::Symmetric):
mac.verify(key)
# or, if externally supplied authenticated data exists:
mac.verify(key, external_aad)
# Then access payload
mac.payload
```
#### COSE_Mac0
```ruby
cbor_data = "..."
mac0 = COSE::Mac0.deserialize(cbor_data)
# Verify by doing (key should be a COSE::Key::Symmetric):
mac0.verify(key)
# or, if externally supplied authenticated data exists:
mac0.verify(key, external_aad)
# Then access payload
mac0.payload
```
### Encryption Objects
#### COSE_Encrypt
```ruby
cbor_data = "..."
encrypt = COSE::Encrypt.deserialize(cbor_data)
encrypt.protected_headers
encrypt.unprotected_headers
encrypt.ciphertext
encrypt.recipients.each do |recipient|
recipient.protected_headers
recipient.unprotected_headers
recipient.ciphertext
if recipient.recipients
recipient.recipients.each do |recipient|
recipient.protected_headers
recipient.unprotected_headers
recipient.ciphertext
end
end
end
```
#### COSE_Encrypt0
```ruby
cbor_data = "..."
encrypt0 = COSE::Encrypt0.deserialize(cbor_data)
encrypt0.protected_headers
encrypt0.unprotected_headers
encrypt0.ciphertext
```
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/cedarcode/cose-ruby.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).