From ee775b55132aa448699386e4e043d3459a778c73 Mon Sep 17 00:00:00 2001
From: Daniel <mail@h3po.de>
Date: Mon, 3 Jun 2019 23:00:55 +0200
Subject: [PATCH] Add an example for dealing with DATA objects to the readme

@danni Just a proposal, I guess you might want to keep the documentation focused on dealing with public key crypto. I am developing with a proprietary pkcs11 library on a token with a proprietary pkcs15 applet, so I'd be happy if you could test this with your nitrokey or other opensc compatible token. It'll be a while before I can test with a standard card or token. This ObjectClass.DATA stuff is coming from me because I'm in the progress of writing a fuse fs driver capable of mounting a pkcs11 token with the goal of storing zfs disk encryption keys on there.
---
 README.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/README.rst b/README.rst
index 829e4d7..9d07e57 100644
--- a/README.rst
+++ b/README.rst
@@ -213,6 +213,51 @@ Elliptic-Curve Diffie-Hellman
             KeyType.AES, 128,
             mechanism_param=(KDF.NULL, None, other_value))
 
+Raw Data Objects
+~~~~~~~~~~~~~~~~~~
+
+This can be useful for storing symmetric encryption keys and the like. Be sure to set the Attribute PRIVATE to True, otherwise the Objects will be readable even without Pin login.
+
+import os, pkcs11
+
+    lib = pkcs11.lib(os.environ["PKCS11_MODULE"])
+    token = lib.get_token(token_label="DEMO")
+
+    demoapp = "python-pkcs11 demo"
+    demolabel = "testobject"
+    demodata = "Hello World!".encode("ascii")
+
+    with token.open(user_pin="1111") as session:
+
+        #write data into an object
+        session.create_object(
+            attrs={
+                pkcs11.Attribute.CLASS: pkcs11.ObjectClass.DATA,
+                pkcs11.Attribute.APPLICATION: demoapp,
+                pkcs11.Attribute.LABEL: demolabel,
+                pkcs11.Attribute.VALUE: demodata,
+                pkcs11.Attribute.TOKEN: True
+            })
+
+        #retrieve an object
+        objectfilter = {
+                pkcs11.Attribute.CLASS: pkcs11.ObjectClass.DATA,
+                pkcs11.Attribute.LABEL: demolabel
+        }
+
+        #objects are not uniquely identified by their attributes
+        #the result might be a list of multiple objects with "demolabel"
+        objects = list(session.get_objects(attrs=objectfilter))
+        print(objects)
+
+        #extract information from an object
+        print(objects[-1][pkcs11.Attribute.VALUE])
+
+        #change an object
+        objects[-1][pkcs11.Attribute.VALUE] = "testdata".encode("ascii")
+        print(objects[-1][pkcs11.Attribute.VALUE])
+
+
 Tested Compatibility
 --------------------