offapi/com/sun/star/packages/XPackageEncryption.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21 module com {  module sun {  module star {  module packages {
  22
  23
  24 /** Allows to transparently plug-in crypto for PackageStreams.
  25
  26     @since LibreOffice 7.0
  27  */
  28 interface XPackageEncryption: com::sun::star::uno::XInterface
  29 {
  30     /** Read package crypto information
  31
  32         @param rStreams
  33         Substreams of the package (in the case of MS encryption, those
  34         are OLE substorage streams).
  35
  36         @returns
  37         True if crypto info could be retrieved, and engine initialised. False otherwise.
  38      */
  39     boolean readEncryptionInfo([in] sequence < com::sun::star::beans::NamedValue > rStreams);
  40
  41     /** Set or refresh encryption key
  42
  43         @param rPassword
  44         Optional password to use for generating encryption key.
  45
  46         @returns
  47         True if key setup was successful. False otherwise.
  48      */
  49     boolean generateEncryptionKey([in] string rPassword);
  50
  51     /** Decrypt document content
  52
  53         After crypto setup via readEncryptionInfo(), pipe package bits through
  54         encryption engine.
  55
  56         @param rxInputStream
  57         Input data (encrypted)
  58
  59         @param rxOutputStream
  60         Output data (decrypted)
  61
  62         @returns
  63         True if decryption finished without error. False otherwise.
  64      */
  65     boolean decrypt([in] com::sun::star::io::XInputStream rxInputStream,
  66                     [out] com::sun::star::io::XOutputStream rxOutputStream);
  67
  68     /** Create key-value list of encryption meta data
  69
  70         After generateEncryptionKey() succeeded in setting up crypto,
  71         use this method to create requisite meta data. Depending on
  72         underlying crypto, this can be a salt, init vector, or other
  73         algorithm-specific information that needs to be stored
  74         alongside an encrypted document
  75
  76         @param rPassword
  77         Same password as provided to generateEncryptionKey
  78
  79         @returns
  80         Sequence of opaque key-value pairs needed for decrypting this
  81         setup. Can be passed back into other instances of this service
  82         via setupEncryption()
  83      */
  84     sequence<com::sun::star::beans::NamedValue> createEncryptionData([in] string rPassword);
  85
  86     /** Set key-value list of encryption meta data
  87
  88         Use this method to setup requisite encryption meta
  89         data. Depending on the underlying crypto, this can be a salt, init
  90         vector, or other algorithm-specific information that needs to
  91         be stored alongside an encrypted document
  92
  93         @returns
  94         True if encryption algo setup finished without error. False otherwise.
  95      */
  96     boolean setupEncryption([in] sequence<com::sun::star::beans::NamedValue> rMediaEncData);
  97
  98     /** Encrypt given stream
  99
 100         After setting up crypto via setupEncryption(), use this method to encrypt content.
 101
 102         @returns
 103         Sequence of named output streams, specific to the crypto
 104         provider. The names of sequence entry denote the substream
 105         identifiers, if any. In the case of MS OLE storage, it's the
 106         substorage names.
 107      */
 108     sequence<com::sun::star::beans::NamedValue> encrypt([in] com::sun::star::io::XInputStream rxInputStream);
 109
 110     /** Check if decryption meta data is valid
 111
 112         Some implementations might for example check HMAC values
 113         here. Call this before trusting encrypted data.
 114
 115         @returns
 116         True if decryption algo setup finished without error and
 117         consistency checks have passed. False otherwise.
 118      */
 119     boolean checkDataIntegrity();
 120 };
 121
 122
 123 }; }; }; };
 124
 125 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */