diff --git a/index.html b/index.html index 7a5e79b..eb06e0d 100644 --- a/index.html +++ b/index.html @@ -1,5 +1,5 @@ -Nippy 3.0.0-RC1

Project

Namespaces

Nippy 3.0.0-RC1

Released under the Eclipse Public License

High-performance serialization library for Clojure.

Installation

To install, add the following dependency to your project or build file:

[com.taoensso/nippy "3.0.0-RC1"]

Namespaces

taoensso.nippy

High-performance serialization library for Clojure

Public variables and functions:

taoensso.nippy.benchmarks

Public variables and functions:
taoensso.nippy.compression
Public variables and functions:
taoensso.nippy.crypto
Low-level crypto utils.
+Nippy 3.0.0-RC2
Project
Namespaces
Nippy 3.0.0-RC2
Released under the Eclipse Public License
High-performance serialization library for Clojure.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/nippy "3.0.0-RC2"]
Namespaces
taoensso.nippy
High-performance serialization library for Clojure
Public variables and functions:
taoensso.nippy.benchmarks
Public variables and functions:
taoensso.nippy.compression
Public variables and functions:
taoensso.nippy.crypto
Low-level crypto utils.
 Private & alpha, very likely to change!
Public variables and functions:
taoensso.nippy.encryption
Simple no-nonsense crypto with reasonable defaults
Public variables and functions:
taoensso.nippy.tools
Utils for 3rd-party tools that want to add user-configurable Nippy support.
 Used by Carmine, Faraday, etc.
Public variables and functions:
taoensso.nippy.utils
Public variables and functions:

\ No newline at end of file
diff --git a/taoensso.nippy.benchmarks.html b/taoensso.nippy.benchmarks.html
index 176b7a7..eb2f63d 100644
--- a/taoensso.nippy.benchmarks.html
+++ b/taoensso.nippy.benchmarks.html
@@ -1,3 +1,3 @@
 
-taoensso.nippy.benchmarks documentation
Project
Namespaces
Public Vars
taoensso.nippy.benchmarks
bench
(bench {:keys [reader? lzma2? fressian? laps], :or {laps 1}})
bench*
macro
(bench* & body)
bench1
(bench1 freezer thawer & [sizer])
data
fressian-freeze
(fressian-freeze value)
fressian-thaw
(fressian-thaw value)

\ No newline at end of file
+taoensso.nippy.benchmarks documentation
Project
Namespaces
Public Vars
taoensso.nippy.benchmarks
bench
(bench {:keys [reader? lzma2? fressian? laps], :or {laps 1}})
bench*
macro
(bench* & body)
bench1
(bench1 freezer thawer & [sizer])
data
fressian-freeze
(fressian-freeze value)
fressian-thaw
(fressian-thaw value)

\ No newline at end of file
diff --git a/taoensso.nippy.compression.html b/taoensso.nippy.compression.html
index ab755a3..f3760eb 100644
--- a/taoensso.nippy.compression.html
+++ b/taoensso.nippy.compression.html
@@ -1,6 +1,6 @@
 
-taoensso.nippy.compression documentation
Project
Namespaces
Public Vars
taoensso.nippy.compression
ICompressor
protocol
members
compress
(compress compressor ba)
decompress
(decompress compressor ba)
header-id
(header-id compressor)
lz4-compressor
Default net.jpountz.lz4 compressor:
+taoensso.nippy.compression documentation
Project
Namespaces
Public Vars
taoensso.nippy.compression
ICompressor
protocol
members
compress
(compress compressor ba)
decompress
(decompress compressor ba)
header-id
(header-id compressor)
lz4-compressor
Default net.jpountz.lz4 compressor:
       Ratio: low.
 Write speed: very high.
  Read speed: very high.
diff --git a/taoensso.nippy.crypto.html b/taoensso.nippy.crypto.html
index 9a6c995..fd9e839 100644
--- a/taoensso.nippy.crypto.html
+++ b/taoensso.nippy.crypto.html
@@ -1,6 +1,6 @@
 
-taoensso.nippy.crypto documentation
Project
Namespaces
Public Vars
taoensso.nippy.crypto
Low-level crypto utils.
+taoensso.nippy.crypto documentation
Project
Namespaces
Public Vars
taoensso.nippy.crypto
Low-level crypto utils.
 Private & alpha, very likely to change!
cbc-cipher
(cbc-cipher)
cipher-kit-aes-cbc
Default CipherKit for AES CBC
 
cipher-kit-aes-gcm
Default CipherKit for AES GCM
 
decrypt
(decrypt {:keys [cipher-kit salt-size salt->key-fn enc-ba], :or {cipher-kit cipher-kit-aes-gcm}})
encrypt
(encrypt {:keys [cipher-kit ?salt-ba key-ba plain-ba rand-bytes-fn], :or {cipher-kit cipher-kit-aes-gcm, rand-bytes-fn rand-bytes}})
gcm-cipher
(gcm-cipher)
ICipherKit
protocol
members
get-cipher
(get-cipher _)
Returns a thread-safe `javax.crypto.Cipher` instance.
diff --git a/taoensso.nippy.encryption.html b/taoensso.nippy.encryption.html
index 7dc67e6..3389ec6 100644
--- a/taoensso.nippy.encryption.html
+++ b/taoensso.nippy.encryption.html
@@ -1,6 +1,6 @@
 
-taoensso.nippy.encryption documentation
Project
Namespaces
Public Vars
taoensso.nippy.encryption
Simple no-nonsense crypto with reasonable defaults
+taoensso.nippy.encryption documentation
Project
Namespaces
Public Vars
taoensso.nippy.encryption
Simple no-nonsense crypto with reasonable defaults
 
aes128-cbc-encryptor
Default 128bit AES-CBC encryptor with many-round SHA-512 key-gen.
 See also `aes-128-cbc-encryptor`.
aes128-gcm-encryptor
Default 128bit AES-GCM encryptor with many-round SHA-512 key-gen.
 
diff --git a/taoensso.nippy.html b/taoensso.nippy.html
index 73a01fd..44b453d 100644
--- a/taoensso.nippy.html
+++ b/taoensso.nippy.html
@@ -1,16 +1,16 @@
 
-taoensso.nippy documentation
Project
Namespaces
Public Vars
taoensso.nippy
High-performance serialization library for Clojure
+taoensso.nippy documentation
Project
Namespaces
Public Vars
taoensso.nippy
High-performance serialization library for Clojure
 
*auto-freeze-compressor*
dynamic
(fn [byte-array])->compressor used by `(freeze <x> {:compressor :auto}),
 nil => default
*custom-readers*
dynamic
{<hash-or-byte-id> (fn [data-input])->read}
 
*final-freeze-fallback*
dynamic
DEPRECATED: prefer `*freeze-fallback`.
 
*freeze-fallback*
dynamic
(fn [data-output x])->freeze, nil => default
 
*freeze-serializable-allowlist*
dynamic
Used when attempting to <freeze/thaw> an object that:
-  - Does not implement Nippy's Freezable    protocol.
-  - Does     implement Java's  Serializable interface.
+  - Does NOT implement Nippy's Freezable    protocol.
+  - DOES     implement Java's  Serializable interface.
 
-In this case, Java's Serializable interface will be permitted iff
-(<allowlist> <class-name>) predicate call returns true.
+In this case, the allowlist will be checked to see if Java's
+Serializable interface may be used.
 
 This is a security measure to prevent possible Remote Code Execution
 (RCE) when thawing malicious payloads. See [1] for details.
@@ -26,16 +26,19 @@ If `thaw`   encounters a disallowed Serialized class, it will:
     - Quarantined objects may be manually unquarantined with
       `read-quarantined-serializable-object-unsafe!`.
 
-There are 2x allowlists: *<freeze/thaw>-serializable-allowlist*.
+There are 2x allowlists:
+  - `*freeze-serializable-allowlist*` ; Checked when freezing
+  -   `*thaw-serializable-allowlist*` ; Checked when thawing
 
-Example values:
-  - (fn allow-class? [class-name] true)            ; Arbitrary fn
-  - #{"java.lang.Throwable", "clojure.lang.*"} ; Set of class-names
+Example allowlist values:
+  - `(fn allow-class? [class-name] true)`            ; Arbitrary predicate fn
+  - `#{"java.lang.Throwable", "clojure.lang.*"}` ; Set of class-names
+  - `"allow-and-record"`                           ; Special value, see [2]
 
   Note that class-names in sets may contain "*" wildcards.
 
 Default allowlist values are:
-  - default-freeze-serializable-allowlist ; {"*"} => allow any class
+  - default-freeze-serializable-allowlist ; `{"*"}` => allow any class
   -   default-thaw-serializable-allowlist ; A set of common safe classes
 
 Allowlist values may be overridden with `binding`, `alter-var-root`, or:
@@ -54,36 +57,25 @@ and formed into sets. Each initial allowlist value will then be:
     - The "base" property/var to replace Nippy's default allowlists.
     - The "add"  property/var to add to  Nippy's default allowlists.
 
-See also `taoensso.encore/compile-str-filter`, a util to help
-easily build more advanced predicate functions.
-
+The special `"allow-and-record"` value is also possible, see [2].
 
 Upgrading from an older version of Nippy and unsure whether you've been
-using Nippy's Serializable support? Here's a snippet to ALLOW and RECORD
-any class requesting Nippy's Serializable fallback:
-
-  ;; Deref for set of all class names that made use of Nippy's Serializable support:
-  (defonce observed-serializables_ (atom #{}))
-
-  (let [f (fn allow-class? [class-name]
-            (swap! observed-serializables_ conj class-name) ; Record class name
-            true ; Allow any class
-            )]
-
-    (alter-var-root #'*freeze-serializable-allowlist* (fn [_] f))
-    (alter-var-root   #'*thaw-serializable-allowlist* (fn [_] f)))
+using Nippy's Serializable support, or which classes to allow? See [2].
 
+See also `taoensso.encore/compile-str-filter` for a util to help easily
+build more advanced predicate functions.
 
 Thanks to Timo Mihaljov (@solita-timo-mihaljov) for an excellent report
 identifying this vulnerability.
 
-[1] https://github.com/ptaoussanis/nippy/issues/130
*incl-metadata?*
dynamic
Include metadata when freezing/thawing?
+[1] https://github.com/ptaoussanis/nippy/issues/130
+[2] See `allow-and-record-any-serializable-class-unsafe`.
*incl-metadata?*
dynamic
Include metadata when freezing/thawing?
 
*thaw-serializable-allowlist*
dynamic
Used when attempting to <freeze/thaw> an object that:
-  - Does not implement Nippy's Freezable    protocol.
-  - Does     implement Java's  Serializable interface.
+  - Does NOT implement Nippy's Freezable    protocol.
+  - DOES     implement Java's  Serializable interface.
 
-In this case, Java's Serializable interface will be permitted iff
-(<allowlist> <class-name>) predicate call returns true.
+In this case, the allowlist will be checked to see if Java's
+Serializable interface may be used.
 
 This is a security measure to prevent possible Remote Code Execution
 (RCE) when thawing malicious payloads. See [1] for details.
@@ -99,16 +91,19 @@ If `thaw`   encounters a disallowed Serialized class, it will:
     - Quarantined objects may be manually unquarantined with
       `read-quarantined-serializable-object-unsafe!`.
 
-There are 2x allowlists: *<freeze/thaw>-serializable-allowlist*.
+There are 2x allowlists:
+  - `*freeze-serializable-allowlist*` ; Checked when freezing
+  -   `*thaw-serializable-allowlist*` ; Checked when thawing
 
-Example values:
-  - (fn allow-class? [class-name] true)            ; Arbitrary fn
-  - #{"java.lang.Throwable", "clojure.lang.*"} ; Set of class-names
+Example allowlist values:
+  - `(fn allow-class? [class-name] true)`            ; Arbitrary predicate fn
+  - `#{"java.lang.Throwable", "clojure.lang.*"}` ; Set of class-names
+  - `"allow-and-record"`                           ; Special value, see [2]
 
   Note that class-names in sets may contain "*" wildcards.
 
 Default allowlist values are:
-  - default-freeze-serializable-allowlist ; {"*"} => allow any class
+  - default-freeze-serializable-allowlist ; `{"*"}` => allow any class
   -   default-thaw-serializable-allowlist ; A set of common safe classes
 
 Allowlist values may be overridden with `binding`, `alter-var-root`, or:
@@ -127,30 +122,19 @@ and formed into sets. Each initial allowlist value will then be:
     - The "base" property/var to replace Nippy's default allowlists.
     - The "add"  property/var to add to  Nippy's default allowlists.
 
-See also `taoensso.encore/compile-str-filter`, a util to help
-easily build more advanced predicate functions.
-
+The special `"allow-and-record"` value is also possible, see [2].
 
 Upgrading from an older version of Nippy and unsure whether you've been
-using Nippy's Serializable support? Here's a snippet to ALLOW and RECORD
-any class requesting Nippy's Serializable fallback:
-
-  ;; Deref for set of all class names that made use of Nippy's Serializable support:
-  (defonce observed-serializables_ (atom #{}))
-
-  (let [f (fn allow-class? [class-name]
-            (swap! observed-serializables_ conj class-name) ; Record class name
-            true ; Allow any class
-            )]
-
-    (alter-var-root #'*freeze-serializable-allowlist* (fn [_] f))
-    (alter-var-root   #'*thaw-serializable-allowlist* (fn [_] f)))
+using Nippy's Serializable support, or which classes to allow? See [2].
 
+See also `taoensso.encore/compile-str-filter` for a util to help easily
+build more advanced predicate functions.
 
 Thanks to Timo Mihaljov (@solita-timo-mihaljov) for an excellent report
 identifying this vulnerability.
 
-[1] https://github.com/ptaoussanis/nippy/issues/130
-cache-proxy
{[<x> <meta>] <idx>} for freezing, {<idx> <x-with-meta>} for thawing.
+[1] https://github.com/ptaoussanis/nippy/issues/130
+[2] See `allow-and-record-any-serializable-class-unsafe`.
-cache-proxy
{[<x> <meta>] <idx>} for freezing, {<idx> <x-with-meta>} for thawing.
 
aes128-cbc-encryptor
Default 128bit AES-CBC encryptor with many-round SHA-512 key-gen.
 See also `aes-128-cbc-encryptor`.
aes128-encryptor
Default 128bit AES-GCM encryptor with many-round SHA-512 key-gen.
 
@@ -273,7 +257,11 @@ types, extend the Clojure reader or see `extend-freeze`.
freeze-to-out!
(freeze-to-out! data-output x)
Serializes arg (any Clojure data type) to a DataOutput.
 This is a low-level util: in most cases you'll want `freeze` instead.
freeze-to-string
(freeze-to-string x)(freeze-to-string x freeze-opts)
Convenience util: like `freeze`, but returns a Base64-encoded string.
-See also `thaw-from-string`.
IFreezable1
protocol
members
-freeze-without-meta!
(-freeze-without-meta! x data-output)
IFreezable2
protocol
members
-freeze-with-meta!
(-freeze-with-meta! x data-output)
inspect-ba
(inspect-ba ba)(inspect-ba ba thaw-opts)
Alpha - subject to change
+See also `thaw-from-string`.
get-recorded-serializable-classes
(get-recorded-serializable-classes)
Returns {<class-name> <frequency>} of the <=1000 classes that ~most
+frequently made use of Nippy's Serializable support via
+`allow-and-record-any-serializable-class-unsafe`.
+
+See that function's docstring for more info.
IFreezable1
protocol
members
-freeze-without-meta!
(-freeze-without-meta! x data-output)
IFreezable2
protocol
members
-freeze-with-meta!
(-freeze-with-meta! x data-output)
inspect-ba
(inspect-ba ba)(inspect-ba ba thaw-opts)
Alpha - subject to change
 
lz4-compressor
Default net.jpountz.lz4 compressor:
       Ratio: low.
 Write speed: very high.
diff --git a/taoensso.nippy.tools.html b/taoensso.nippy.tools.html
index f11ce02..633199a 100644
--- a/taoensso.nippy.tools.html
+++ b/taoensso.nippy.tools.html
@@ -1,6 +1,6 @@
 
-taoensso.nippy.tools documentation
Project
Namespaces
Public Vars
taoensso.nippy.tools
Utils for 3rd-party tools that want to add user-configurable Nippy support.
+taoensso.nippy.tools documentation
Project
Namespaces
Public Vars
taoensso.nippy.tools
Utils for 3rd-party tools that want to add user-configurable Nippy support.
 Used by Carmine, Faraday, etc.
*freeze-opts*
dynamic
*thaw-opts*
dynamic
freeze
(freeze x)(freeze x default-opts)
Like `nippy/freeze` but merges opts from *freeze-opts*, `wrap-for-freezing`.
 
thaw
(thaw ba)(thaw ba default-opts)
Like `nippy/thaw` but merges opts  from `*thaw-opts*`.
 
with-freeze-opts
macro
(with-freeze-opts opts & body)
with-thaw-opts
macro
(with-thaw-opts opts & body)
wrap-for-freezing
(wrap-for-freezing x)(wrap-for-freezing x opts)
Ensures that given arg (any freezable data type) is wrapped so that
diff --git a/taoensso.nippy.utils.html b/taoensso.nippy.utils.html
index bdcc55e..3267936 100644
--- a/taoensso.nippy.utils.html
+++ b/taoensso.nippy.utils.html
@@ -1,6 +1,6 @@
 
-taoensso.nippy.utils documentation
Project
Namespaces
Public Vars
taoensso.nippy.utils
freezable?
(freezable? x)(freezable? x {:keys [allow-clojure-reader? allow-java-serializable?]})
Alpha - subject to change.
+taoensso.nippy.utils documentation
Project
Namespaces
Public Vars
taoensso.nippy.utils
freezable?
(freezable? x)(freezable? x {:keys [allow-clojure-reader? allow-java-serializable?]})
Alpha - subject to change.
 Returns truthy iff Nippy *appears* to support freezing the given argument.
 
 `:allow-clojure-reader?` and `:allow-java-serializable?` options may be