1 /*=========================================================================== 2 * 3 * PUBLIC DOMAIN NOTICE 4 * National Center for Biotechnology Information 5 * 6 * This software/database is a "United States Government Work" under the 7 * terms of the United States Copyright Act. It was written as part of 8 * the author's official duties as a United States Government employee and 9 * thus cannot be copyrighted. This software/database is freely available 10 * to the public for use. The National Library of Medicine and the U.S. 11 * Government have not placed any restriction on its use or reproduction. 12 * 13 * Although all reasonable efforts have been taken to ensure the accuracy 14 * and reliability of the software and data, the NLM and the U.S. 15 * Government do not and cannot warrant the performance or results that 16 * may be obtained by using this software or data. The NLM and the U.S. 17 * Government disclaim all warranties, express or implied, including 18 * warranties of performance, merchantability or fitness for any particular 19 * purpose. 20 * 21 * Please cite the author in any work or product based on this material. 22 * 23 * =========================================================================== 24 * 25 */ 26 27 #ifndef _h_vfs_keyring_ 28 #define _h_vfs_keyring_ 29 30 #ifndef _h_vfs_extern_ 31 #include <vfs/extern.h> 32 #endif 33 34 #ifndef _h_klib_defs_ 35 #include <klib/defs.h> 36 #endif 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /* 43 * API for clients of a client/server KeyRing implementation. 44 * Client code can use this interface and fall back to using KKeyStore in some cases, e.g. to work with a project that has not been 45 * added to the keyring. This can be done behind KKeyRing interface (would have to define an object naming scheme that is compatible 46 * with project-id/type/object-id), or explicitly in the client code. 47 */ 48 typedef struct KKeyRing KKeyRing; 49 50 /* Make 51 * Open an IPC connection to a keyring server. Will start the server if none is running. 52 * KKeyRingMakeRead will reject Add/Delete operations 53 * dataDir [ IN, NULL OK ] = path to the directory with keyring database. NULL - use default location (~/.ncbi) 54 */ 55 VFS_EXTERN rc_t CC KKeyRingMakeRead( const KKeyRing** self, const char* dataDir ); 56 VFS_EXTERN rc_t CC KKeyRingMakeUpdate( KKeyRing** self, const char* dataDir ); 57 58 /* AddRef 59 * Release 60 * 61 * shutdown_server [ IN ] - if this is the last reference, send a Shutdown message to server before closing the IPC connection. 62 * This will not necessarily shut down the server immediately; if there are other active connections, the server will wait for them to close first. 63 * Use KKeyRingIsServerRunning() to check it the server is down. 64 */ 65 VFS_EXTERN rc_t CC KKeyRingAddRef ( const KKeyRing *self ); 66 VFS_EXTERN rc_t CC KKeyRingRelease ( KKeyRing *self, bool shutdown_server ); 67 68 /* 69 * retrieving download/encyprtion keys 70 */ 71 VFS_EXTERN rc_t CC KKeyRingGetDownloadTicket(const KKeyRing* self, const char* project_key, const char** dl_key); 72 VFS_EXTERN rc_t CC KKeyRingGetProjectEncryptionKey(const KKeyRing* self, const char* project_key, const char** enc_key); 73 74 /* 75 * managing projects 76 */ 77 VFS_EXTERN rc_t CC KKeyRingAddProject(KKeyRing* self, const char* project_key, const char* dl_key, const char* enc_key); 78 VFS_EXTERN rc_t CC KKeyRingDeleteProject(KKeyRing* self, const char* project_key); /* will delete all associated objects */ 79 80 /* 81 * managing objects 82 */ 83 VFS_EXTERN rc_t CC KKeyRingAddObject(KKeyRing* self, 84 const char* project_key, uint8_t object_type, const char* object_key, 85 const char* display_name, uint64_t size, const char* checksum); 86 VFS_EXTERN rc_t CC KKeyRingDeleteObject(KKeyRing* self, 87 const char* project_key, uint8_t object_type, const char* object_key); 88 89 /* KKeyRingReencrypt 90 * Server can refuse to reencrypt if it detects other active servers. 91 */ 92 VFS_EXTERN rc_t CC KKeyRingReencrypt(KKeyRing** self, const char* new_passwd); 93 94 /* IsServerRunning 95 * dataDir [ IN, NULL OK ] = path to the directory with keyring database. NULL - use default location (~/.ncbi) 96 */ 97 VFS_EXTERN bool CC KKeyRingIsServerRunning(const char* dataDir); 98 99 /* 100 * private API for libkrypto 101 */ 102 103 VFS_EXTERN rc_t CC KKeyRingGetObjectEncryptionKey(const KKeyRing* self, const char* project_key, 104 uint8_t object_type, const char* object_key, const char** enc_key); 105 106 107 #ifdef __cplusplus 108 } 109 #endif 110 111 #endif /* _h_vfs_keyring_ */ 112