1 #ifndef LIBRARIES_CRYPTOSTORAGE_H
    2 #define LIBRARIES_CRYPTOSTORAGE_H
    3 
    4 /*
    5 	cryptostorage.library include
    6 
    7 	Copyright © 2017-2021 The MorphOS Development Team, All Rights Reserved.
    8 */
    9 
   10 #ifndef EXEC_TYPES_H
   11 # include <exec/types.h>
   12 #endif
   13 
   14 #ifndef UTILITY_TAGITEM_H
   15 # include <utility/tagitem.h>
   16 #endif
   17 
   18 #pragma pack(2)
   19 
   20 struct CryptoStorageCtx;
   21 
   22 /*
   23  * Function return values
   24  */
   25 enum
   26 {
   27 	CSS_OK,                 /* Success */
   28 	CSS_BADFORMAT,          /* Bad storage format */
   29 	CSS_NOMEM,              /* Out of memory */
   30 	CSS_IO_ERROR,           /* Disk I/O error, including file not found */
   31 	CSS_LOCKED,             /* Operation attempted on a locked storage */
   32 	CSS_BAD_PASSPHRASE,     /* Decrypt error, likely due to wrong passphrase */
   33 	CSS_NOKEY,              /* Specific key not found */
   34 	CSS_BUFFER_OVERFLOW,    /* Buffer would have overflown */
   35 };
   36 
   37 /*
   38  * CryptoStorageOpen tags
   39  *
   40  * CST_FileName         CONST_STRPTR
   41  *
   42  *     Full path to the crypto storage. Omitting this tag creates a memory
   43  *     only storage. The memory only storage won't be stored to a file,
   44  *     and will be destroyed at CryptoStorageClose() call.
   45  *
   46  * CST_Passphrase       CONST_STRPTR
   47  *
   48  *    Passphrase to encrypt/decrypt the values in the storage. Note that
   49  *    keys themselves are not encrypted. This tag can be omitted if the
   50  *    storage is unlocked with the CryptoStorageUnlock() call when needed.
   51  *
   52  *    This tag is also applicaple to CryptoStorageUnlockA() and
   53  *    CryptoStorageChangePassphraseA() calls.
   54  *
   55  *    Note that the caller should memset the passphrase string to all zero
   56  *    as soon as possible to avoid leaking the password in memory.
   57  *
   58  * CST_RawHexKey        BOOL   (Default: FALSE)
   59  *
   60  *    String passed in CST_Passphrase is interpreted as a hex string
   61  *    representing the raw encryption key. Note that the key should *not*
   62  *    be generated by some fast hashing algorithm in order to prevent brute
   63  *    force attacks. The string shpuld be at least 64 hex digits (32 bytes)
   64  *    long. If TRUE CST_HashRounds is ignored.
   65  *
   66  *    This tag is also applicaple to CryptoStorageUnlockA() and
   67  *    CryptoStorageChangePassphraseA() calls.
   68  *
   69  * CST_FailIfMissing    BOOL   (Default: FALSE)
   70  *
   71  *    Fail CryptoStorageOpen() call if the storage file is missing.
   72  *
   73  * CST_CreateNew        BOOL   (Default: FALSE)
   74  *
   75  *    Wipe the storage empty if it already exists.
   76  *
   77  * CST_CommitAtStore    BOOL   (Default: FALSE)
   78  *
   79  *    Immediately commit new value fo the crypto storage after any
   80  *    successful CryptoStorageStore() call. Normally the file is only
   81  *    written out at CryptoStorageCommit() or CryptoStorageClose() call.
   82  *    Ignored for memory only storages.
   83  *
   84  * CST_HashRounds       ULONG  (Default: 50000)
   85  *
   86  *    Number of SHA256 rounds performed for the password hashing.
   87  *    For ultra high security you might want to use higher value
   88  *    than the default.
   89  *
   90  *    This tag is also applicaple to CryptoStorageChangePassphraseA()
   91  *    call. If specified the hashing rounds are changed to specified
   92  *    value.
   93  *
   94  * CST_OldPassphrase    CONST_STRPTR  (since V51.4)
   95  *
   96  *    Old passphrase to verify at CryptoStorageChangePassphrase(). If
   97  *    specified the passphrase needs to be correct to continue with
   98  *    passphrase change.
   99  *
  100  *    This tag is only valid for CryptoStorageChangePassphrase().
  101  *
  102  * CST_CloseRollback BOOL  (Default: TRUE) (since V52.5)
  103  *
  104  *    When set to TRUE CryptoStorageClose() will roll back the crypto
  105  *    storage in case of an I/O error and release resources associated
  106  *    with the context. If set to FALSE, the function instead will
  107  *    report the I/O error and keep the resources allocated.
  108  *
  109  */
  110 #define CST_TagBase             (TAG_USER + 0x1A0000)
  111 #define CST_FileName            (CST_TagBase + 1)
  112 #define CST_Passphrase          (CST_TagBase + 2)
  113 #define CST_RawHexKey           (CST_TagBase + 3)
  114 #define CST_FailIfMissing       (CST_TagBase + 4)
  115 #define CST_CreateNew           (CST_TagBase + 5)
  116 #define CST_CommitAtStore       (CST_TagBase + 6)
  117 #define CST_HashRounds          (CST_TagBase + 7)
  118 #define CST_OldPassphrase       (CST_TagBase + 8)
  119 #define CST_CloseRollback       (CST_TagBase + 9)
  120 
  121 #pragma pack()
  122 
  123 #endif /* LIBRARIES_CRYPTOSTORAGE_H */