Package com.tccc.kos.commons.kab

Class KabOutputStream

java.lang.Object

java.io.OutputStream

java.io.FilterOutputStream

com.tccc.kos.commons.kab.KabOutputStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class KabOutputStream
extends FilterOutputStream

Output stream for creating a KAB file. This functions conceptually similar to how ZipOutputStream works, in that an entry is added to the stream and then the contents of the entry is written. The KAB is constructed by repeating this process for all the files that need to added.

It is possible to enable per-entry encryption support by calling setEncryptionKey() with a private RSA key. Once the key is set, addFile(name, encrypt) can be used to indicate that a given file should be encrypted or not. Encrypted entries are flagged and when using KabFile it is possible to identify encrypted entries.

Reading encrypted entries from a KAB using KabFile will return the encrypted content unless setDecryptionKey() is called with the correct public key. Once the public key is set, reading the contents of an encrypted entry will return the decrypted content, although the file entry length will still reflect the encrypted size.

Version:

Jun-18-22

Constructor Summary

Constructors

Constructor	Description
KabOutputStream(OutputStream os, String type, String tag, String name, String version, KeySet keySet, KabAccessProvider accessProvider)	Create an output stream that writes a kab file.

Method Summary

Modifier and Type	Method	Description
void	addDir(String path)	Create a new dir entry.
void	addDir(String path, String user, String group, int permissions)	Create a new dir entry owned by the specified user and group, with the specified permissions.
void	addFile(String path)	Create a new file entry.
void	addFile(String path, boolean encrypt)	Create a new file entry.
void	addFile(String path, boolean encrypt, String user, String group, int permissions)	Create a new file entry.
void	close()	Close the output stream which forces the digital signature to be added to the resulting KAB.
void	copy(InputStream is)	Copy the specified input stream to the output stream.
void	removeEntry(String path)	Remove an existing entry.
void	setEncryptionKey(PrivateKey privateKey)	Enable encrypted content in the kab using the specified private key.
void	write(byte[] b, int off, int len)	Write a buffer to the current KAB entry.
void	write(int b)	Write a byte to the current KAB entry.

Methods inherited from class java.io.FilterOutputStream

flush, write

Methods inherited from class java.io.OutputStream

nullOutputStream

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

KabOutputStream

public KabOutputStream(OutputStream os,
 String type,
 String tag,
 String name,
 String version,
 KeySet keySet,
 KabAccessProvider accessProvider)
                throws IOException

Create an output stream that writes a kab file. The certPath and key parameters much match in that key must be the private key for the first cert in certPath as the private key is used to generate the signature and the certPath is used to verify it.

Typically this is not called directly. Use KabOutputStreamBuilder for a fluent interface for configuring an output stream.

Parameters:

os - the underlying output stream to write to

type - kab type

tag - user specified tag

name - display name

version - version of kab contents

keySet - used to sign the kab

accessProvider - provide access control data to entries (optional)

Throws:

IOException - if there is an underlying stream error

Method Details

setEncryptionKey

public void setEncryptionKey(PrivateKey privateKey)
                      throws IOException

Enable encrypted content in the kab using the specified private key. This allows encryption of kab content at the file level. Once the encryption key is set, individual files may be marked as encrypted and the encrypted contents will be written to the kab. The file entry will contain the encrypted bytes and have a file length corresponding to the encrypted content, which may differ from the original file size.

Throws:

IOException

addFile

public void addFile(String path)

Create a new file entry. If the path is the same as a previous entry, it will replace it but won't delete the content from the output stream.

Parameters:

path - the path of the file

addFile

public void addFile(String path,
 boolean encrypt)

Create a new file entry. If the path is the same as a previous entry, it will replace it but won't delete the content from the output stream. Optionally encrypt the content of the file. Encryption requires that a private key be set.

Any parent directories contained in the path will automatically be added to the kab.

Parameters:

path - the path of the file

addFile

public void addFile(String path,
 boolean encrypt,
 String user,
 String group,
 int permissions)

Create a new file entry. If the path is the same as a previous entry, it will replace it but won't delete the content from the output stream. Optionally encrypt the content of the file. Encryption requires that a private key be set. The resulting file will be owned by the specified user and group and will have the specified permissions.

Any parent directories contained in the path will automatically be added to the kab and will be owned by root and have standard directory permissions.

Parameters:

path - the path of the file

encrypt - if true, encrypt the file

user - the owner name of the file

group - the group name of the file

permissions - unix permission bits for the file

addDir

public void addDir(String path)

Create a new dir entry. Any missing parent directories will automatically be added. The resulting directory will be owned by root and will have standard directory permissions. This api can be used to create empty directories.

Parameters:

path - the path of the directory

addDir

public void addDir(String path,
 String user,
 String group,
 int permissions)

Create a new dir entry owned by the specified user and group, with the specified permissions. Any missing parent directories will automatically be added using the same ownership and permissions. Any directories. This api can be used to create empty directories.

Parameters:

path - the path of the directory

user - the owner name of the directory

group - the group name of the directory

permissions - unix permission bits for the directory

removeEntry

public void removeEntry(String path)

Remove an existing entry. This simply removes the entry from the master archive directory but leaves the bytes in the file which makes them unaccessible.

Parameters:

path - the path of the entry to remove

copy

public void copy(InputStream is)
          throws IOException

Copy the specified input stream to the output stream. This is an easy way to create an entry and then copy a file to the kab. This does not close the input stream when done.

Parameters:

is - the input stream to copy to the kab

Throws:

IOException

write

public void write(int b)
           throws IOException

Write a byte to the current KAB entry.

Overrides:

write in class FilterOutputStream

Throws:

IOException

write

public void write(byte[] b,
 int off,
 int len)
           throws IOException

Write a buffer to the current KAB entry.

Overrides:

write in class FilterOutputStream

Throws:

IOException

close

public void close()
           throws IOException

Close the output stream which forces the digital signature to be added to the resulting KAB.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class FilterOutputStream

Throws:

IOException