pkcs7-cryptographer 0.2.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6f89bcec7efd95afb71a4efdb3ba0ab85b87e38b71115f3b4081ee7e99bbea3
-  data.tar.gz: be8a8b20477ad48c2451b513f179f9652641981ef4ffa19876655e2dd3e9933d
+  metadata.gz: 0c4ad91179d8ddcac665a391f85dd03bb066a0fb14d8e09d997d5f363f9d5434
+  data.tar.gz: 24ef42a9ea9c625af0de5dffda7fdd178b48b1a94ec998a82d90d993f90101b3
 SHA512:
-  metadata.gz: 5e3b5c8eb9e520727c3aa6e9cc4f632c8b2272e991b0393dc1f7c94a0286cbc3eaffb8fd6f02e4864f9860dbf20bf6ceed0bde92625890678f8fdeb38af4d088
-  data.tar.gz: 6e7c13a7e6db27874f2bf2d31f05f54d614cda843c099419936f639e8c9c9274c7e355a5a0e0831b976afb5456fd1ba658af6474985ca50362ab3f3bc54a2927
+  metadata.gz: 88e9e776e81ceed455d41cb1bff2b7272725512ea0fa8121db0c6180d548639d6742326733f20853344cb08a7d7688509a6f5ced6126aa7a7bcb87e964cdbda4
+  data.tar.gz: 5c067348e4eadbb962c913ad1a8fa65037c03bb1cdabbd9305de7aef8ea4f2c5262a7aa6e15361763dc3d6a4f1791d05d6dbc1627676557a4b3b1becc117cc26

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pkcs7-cryptographer (0.2.3)
+    pkcs7-cryptographer (1.0.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -4,13 +4,12 @@
 ![main workflow](https://github.com/dmuneras/pkcs7-cryptographer/actions/workflows/main.yml/badge.svg)
 
 
-
-Cryptographer is an small utility to encrypt and decrypt messages
+Cryptographer is an small utility to encrypt, sign and decrypt messages
 using PKCS7.
 
 PKCS7 is used to store signed and encrypted data.This specific implementation
-uses aes-256-cbc as chipher in the encryption process. If you want to read more
-information about the involved data structures and theory around this,
+uses `aes-256-cbc` as chipher in the encryption process. If you want to read
+more information about the involved data structures and theory around this,
 please visit:
 
 - https://ruby-doc.org/stdlib-3.0.0/libdoc/openssl/rdoc/OpenSSL.html
@@ -37,6 +36,8 @@ Or install it yourself as:
 ```
 ## Usage
 
+### Using bare PKCS7::Cryptographer
+
 After installing the gem you will have the `PKCS7::Cryptographer` available.
 
 `PKCS7::Cryptographer` is a class that provides two public methods:
@@ -44,12 +45,13 @@ After installing the gem you will have the `PKCS7::Cryptographer` available.
 - `sign_and_encrypt`
 - `decrypt_and_verify`
 
-Read the following examples to get a better undertanding:
+If you want to use the barebones cryptographer, you can. Please look at the
+following example:
 
 
-### Using bare PKCS7::Cryptographer
 
 ```ruby
+  require 'pkcs7/cryptographer'
 
   # This script assumes you have a read_file method to read the certificates and
   # keys.
@@ -71,7 +73,7 @@ Read the following examples to get a better undertanding:
   # Only the client can read the message since the required public
   # certificate to read it is the client certificate.
 
-  # It could be read if the CA_STORE of the reader has certificate of the
+  # It could be read if the CA_STORE of the reader has the certificate of the
   # CA that signed the client certificate as trusted.
 
   cryptographer = PKCS7::Cryptographer.new
@@ -84,6 +86,8 @@ Read the following examples to get a better undertanding:
     public_certificate: CLIENT_CERTIFICATE
   )
 
+  # encrypted_data is a PEM formatted string
+
   # READ MESSAGE IN CLIENT
   # ----------------------------------------------------------------------------
   # Store of trusted certificates
@@ -103,8 +107,16 @@ Read the following examples to get a better undertanding:
 
 ### Using PKCS7::Cryptographer::Entity
 
+There is a possibility to use entities to communicate using encrypted data. In
+order to use it you have to import the entities implementation.
+
+Please look at the following example:
+
 ```ruby
 
+  require 'pkcs7/cryptographer'
+  require 'pkcs7/cryptographer/entity'
+
   # This script assumes you have a read_file method to read the certificates and
   # keys. If you have any question about how to generate the keys/certificates
   # check this post: https://mariadb.com/kb/en/certificate-creation-with-openssl/
@@ -129,24 +141,62 @@ Read the following examples to get a better undertanding:
   )
 
   client_entity = PKCS7::Cryptographer::Entity.new(
-    certificate: CLIENT_CERTIFICATE,
+    certificate: CLIENT_CERTIFICATE
   )
 
   # SEND MESSAGE TO THE CLIENT
   # ----------------------------------------------------------------------------
   data = "Victor Ibarbo"
-  encrypted_data = ca_entity.encrypt_data(data: data, to: client_entity)
+  encrypted_data = ca_entity.encrypt_data(data: data, receiver: client_entity)
 
   # READ MESSAGE IN CLIENT
   # ----------------------------------------------------------------------------
   decrypted_data = client_entity.decrypt_data(
     data: encrypted_data,
-    from: ca_entity
+    sender: ca_entity
   )
 
   # decrypted_data returns: "Victor Ibarbo"
 ```
 
+When using entities, all the complexity of knowing which PKI credentials to
+send to the cryptographer dissapears. You only need to initialize the
+entities and use the methods to indicate to whom the message will be sent.
+
+If you want to verify if certain entity you defined "trust" another one, use the
+`trustable_entity?(<the other entity>)`.
+
+```ruby
+  ca_entity = PKCS7::Cryptographer::Entity.new(
+    key: CA_KEY,
+    certificate: CA_CERTIFICATE,
+    ca_store: CA_STORE
+  )
+
+  client_entity = PKCS7::Cryptographer::Entity.new(
+    certificate: CLIENT_CERTIFICATE
+  )
+
+  ca_entity.trustable_entity?(client_entity)
+
+  # Returns true because the client certificate was signed by the root
+  # certificate of the ca_authority.
+```
+
+When sending data to an entity, you will most of the time initialize the entity
+only with the `certificate` keyword arguments. So, initializing a receiver will
+most of the time looks like this:
+
+```ruby
+  client_entity = PKCS7::Cryptographer::Entity.new(
+    certificate: CLIENT_CERTIFICATE
+  )
+```
+
+The entity above can't encrypt messages or decrypt them, if you want to decrypt
+and encrypt the entity should have its the key (private key), certificate and
+the list of trusted certificates of the entity (ca_store).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/pkcs7/cryptographer/entity.rb

@@ -32,24 +32,24 @@ module PKCS7
         @ca_store.verify(entity.certificate)
       end
 
-      def encrypt_data(data:, to:)
-        perform_safely(to) do
+      def encrypt_data(data:, receiver:)
+        perform_safely(receiver) do
           @cryptographer.sign_and_encrypt(
             data: data,
             key: @key,
             certificate: @certificate,
-            public_certificate: to.certificate
+            public_certificate: receiver.certificate
           )
         end
       end
 
-      def decrypt_data(data:, from:)
-        perform_safely(from) do
+      def decrypt_data(data:, sender:)
+        perform_safely(sender) do
           @cryptographer.decrypt_and_verify(
             data: data,
             key: @key,
             certificate: @certificate,
-            public_certificate: from.certificate,
+            public_certificate: sender.certificate,
             ca_store: @ca_store
           )
         end

data/lib/pkcs7/cryptographer/version.rb

@@ -2,6 +2,6 @@
 
 module PKCS7
   class Cryptographer
-    VERSION = "0.2.3"
+    VERSION = "1.0.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pkcs7-cryptographer
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Daniel Munera Sanchez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-03-25 00:00:00.000000000 Z
+date: 2021-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler