The secrets is a library designed to generate cryptographically strong random numbers suitable for managing data such as passwords, account authentication, security tokens, and related secrets.

The secrets is an implementation of the secrets module from Python's standard library for Clojure.

See «Recipes and best practices» for usage examples.

Installation

Leiningen/Boot:

Add the following dependency to your project.clj file:

[likid_geimfari/secrets "1.0.0"]

Clojure CLI/deps.edn:

likid_geimfari/secrets {:mvn/version "1.0.0"}

Documentation

You can find the complete documentation on the cljdoc.

API

user=> (secrets.core/token-hex 32)
"2aa5430064918acf140bb423678cef7353f7055597bc61305414c5371106ebef"

user=> (secrets.core/token-urlsafe 32)
"kfbGVrB6jz6hyOl_2rX9UIHgiop2-rM_jo2XEK7oTj0"

user=> (secrets.core/token-bytes 16)
#object["[B" 0x3b2454e9 "[B@3b2454e9"]

user=> (secrets.core/randbelow 100)
71

user=> (secrets.core/choice [8 16 32 64 128])
8

user=> (secrets.core/choices [8 16 32 64 128] 2)
(128 16)

user=> (secrets.tools/uuid4)
"84e9c5c0-ceb4-4aab-9a58-668f59b9a9e5"

user=> (secrets.tools/unix-timestamp)
1601927558

There is a namespace secrets.constants with useful constants:

user=> secrets.constants/ascii-lowercase
"abcdefghijklmnopqrstuvwxyz"
user=> secrets.constants/ascii-uppercase
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
user=> secrets.constants/ascii-letters
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
user=> secrets.constants/digits
"0123456789"
user=> secrets.constants/hexdigits
"0123456789abcdefABCDEF"
user=> secrets.constants/octdigits
"01234567"
user=> secrets.constants/punctuation
"!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"

How many bytes should tokens use?

To be secure against brute-force attacks, tokens need to have sufficient randomness. You can explicitly specify how much randomness is used for tokens by giving an int argument to the various token-* functions.

Otherwise, if no argument is provided the token-* functions will use a reasonable default instead, namely — 32.

Recipes and best practices

This section shows recipes and best practices for using secrets to manage a basic level of security.

Generate an eight-character alphanumeric password:

(ns example.security
  (:use [clojure.string :only [join]]
    [secrets.core]
    [secrets.constants :only [ascii-letters digits]]))

(defn generate-password [n]
  (join "" (secrets.core/choices (str ascii-letters digits)) n))

example.security=> (generate-password 8)
"7gHY2N4s"

Note: Applications should not store passwords in a recoverable format, whether plain text or encrypted. They should be salted and hashed using a cryptographically-strong one-way (irreversible) hash function.

Generate an XKCD-style passphrase:

(ns example.security
  (:use [secrets.core]
        [clojure.string :only [join lower-case split-lines]))

(def words
  (-> (slurp "/usr/share/dict/words")
      (split-lines)))

(defn generate-passphrase [n]
  (-> (join " " (secrets.core/choices words n))
      (lower-case)))

example.security=> (generate-passphrase 5)
"uniaxally intercarrier straddleback basihyoid unhusk"

Generate a hard-to-guess temporary URL containing a security token suitable for password recovery applications:

(ns example.security
  (:use [secrets.core :only [token-urlsafe]]))

(defn generate-password-recovery-url [n]
  (str "https://mydomain.com/reset=" (token-urlsafe n)))

example.security=> (generate-password-recovery-url 32)
"https://mydomain.com/reset=3kOJuScK1mHyxXWnuMBAUQaIEdsBUluQBR-3Zlvv8XQ"

License

MIT License. See LICENSE for more information.