extra/sodium/secure-memory/secure-memory-docs.factor

   1 ! Copyright (C) 2020 Alexander Ilin.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: destructors help.markup help.syntax kernel math sodium sodium.ffi
   4 quotations ;
   5 IN: sodium.secure-memory
   6
   7 ABOUT: "sodium.secure-memory"
   8
   9 ARTICLE: "sodium.secure-memory" "Secure memory"
  10 "The " { $vocab-link "sodium.secure-memory" } " vocab provides a simple wrapper around some of the libsodium's Secure memory functions, see " { $url "https://libsodium.gitbook.io/doc/memory_management" } "." $nl
  11 "The class for securely allocated alien memory:"
  12 { $subsections secure-memory new-secure-memory with-new-secure-memory }
  13 "Temporary memory access combinators:"
  14 { $subsections with-read-access with-write-access }
  15 "Memory access restriction setters:"
  16 { $subsections allow-no-access allow-read-access allow-write-access } ;
  17
  18 HELP: secure-memory
  19 { $class-description "The " { $link disposable } " class wrapping some secure memory allocated by libsodium. This class has two slots:"
  20   { $list
  21     { { $slot "underlying" } " - pointer to memory allocated by libsodium's " { $link sodium_malloc } ";" }
  22     { { $slot "size" } " - memory block size in bytes." }
  23   }
  24   "New instances must be constructed with " { $link new-secure-memory } " or using " { $link clone } ". The cloned objects have an independent copy of a newly allocated secure memory block (deep copy), so read access to the source memory must be granted prior to cloning. The cloned memory doesn't inherit the current access right of the source, instead it starts with the same access rights which are normally granted by calling " { $link new-secure-memory } "." } ;
  25
  26 HELP: new-secure-memory
  27 { $values
  28   { "size" integer }
  29   { "obj" secure-memory }
  30 }
  31 { $description "Allocates a new instance of " { $link secure-memory } " with " { $snippet "size" } " bytes of freshly allocated alien memory pointed by the " { $slot "underlying" } " slot. Follow the " { $link "destructors-using" } " protocol to release the memory." $nl
  32   "In case the memory could not be allocated, " { $link sodium-malloc-error } " is thrown." $nl
  33   "Initial memory contents are not zero, see documentation at " { $url "https://libsodium.gitbook.io/doc/memory_management" } ". The memory is initially in the read-write mode, but is protected against swapping out by the OS (if supported) and against out of boundary access. Call " { $link allow-no-access } " to restrict access after your own initialization." } ;
  34
  35 HELP: with-new-secure-memory
  36 { $values
  37   { "size" number }
  38   { "quot" { $quotation ( ..a secure-memory -- ..b ) } }
  39 }
  40 { $description "Call " { $snippet "quot" } " with a newly allocated " { $link secure-memory } " instance of the given " { $snippet "size" } ". When the quotation is called, the memory is writable. After the call the access is restricted using " { $link allow-no-access } ". This combinator is especially useful when you need to initialize and lock a new memory region. The " { $snippet "quot" } " should save a reference to the memory for subsequent disposal." } ;
  41
  42 { new-secure-memory with-new-secure-memory } related-words
  43
  44 HELP: allow-no-access
  45 { $values
  46     { "secure-memory" secure-memory }
  47 }
  48 { $description "Disable both read and write access to the " { $snippet "secure-memory" } ". Any subsequent access to the memory will raise a memory protection exception." } ;
  49
  50 HELP: allow-read-access
  51 { $values
  52   { "secure-memory" secure-memory }
  53 }
  54 { $description "Allow read-only access to the " { $snippet "secure-memory" } ". Any subsequent write to the memory will raise a memory protection exception." } ;
  55
  56 HELP: allow-write-access
  57 { $values
  58     { "secure-memory" secure-memory }
  59 }
  60 { $description "Allow read and write access to the " { $snippet "secure-memory" } "." } ;
  61
  62 HELP: with-read-access
  63 { $values
  64   { "secure-memory" secure-memory }
  65   { "quot" { $quotation ( ..a secure-memory -- ..b ) } }
  66 }
  67 { $description "Temporarily allow read-only access to the " { $snippet "secure-memory" } " for the duration of the " { $snippet "quot" } " call. When the quotation terminates, disable the access using " { $link allow-no-access } "." } ;
  68
  69 HELP: with-write-access
  70 { $values
  71   { "secure-memory" secure-memory }
  72   { "quot" { $quotation ( ..a secure-memory -- ..b ) } }
  73 }
  74 { $description "Temporarily allow read and write access to the " { $snippet "secure-memory" } " for the duration of the " { $snippet "quot" } " call. When the quotation terminates, disable the access using " { $link allow-no-access } "." } ;
  75
  76 {
  77     allow-no-access allow-read-access allow-write-access
  78     with-read-access with-write-access
  79 } related-words
  80
  81 HELP: secure-memory=
  82 { $values
  83   { "a" secure-memory }
  84   { "b" secure-memory }
  85   { "?" boolean }
  86 }
  87 { $description "Compare the memory contents of the two memory regions and return " { $link t } " on full match. Both regions must be allocated, have equal " { $slot "size" } ", and the read access to the memory should be allowed." }
  88 { $notes "Comparison of secure memory blocks of equal size is performed in constant time using " { $link sodium_memcmp } "." } ;