PWSLIB3 Files

KSE-PWSLIB-3 Ver. 3-0-0

= KSE Password Safe V3 Library, README FILE

Project: Java Password-Safe file handling
File-Format: 3.13
Package-Version 3.0.0
Release: 29 May 2025
Author: (c) Wolfgang Keller, 2025
License: GNU LGPL 3.0
Library Platform: Java 1.8
Host: http://sourceforge.net/projects/pwslib3

== Status
A naming and algorithmic overhaul took place in the software and thus
a new major version number became mandatory. Java interfaces are downward
compatible but class naming changed (package base path). Applications of
earlier packages will have to adjust import naming and recompile. Other
problems are not expected. This release is operative and tested.
This package contains and applies strong encryption software using the
Twofish algorithm (Bruce Schneier et al.) with maximum key-length.

== Objective
This software enables to read and write encrypted Password-Safe password
databases in any format belonging to the "3" series. The package manages
file formats up to version 3.13. Moreover the PWS format tolerates unknown
(non-canonical) data elements which are preserved and thus stabilises the
application of database files from alien or later format handlers. The 
project offers a special interface for the adaption of different and 
potentially user-defined IO-contexts for addressing files. Available 
IO-contexts are file-system (r/w), HTTP (r), FTP (r/w).

== License of Usage
This project's creations are distributed under the GNU Lesser GPL 3.0,
see file "license.txt" for the details. It was formerly a part of the 
JPasswords project (JPWS) which is its first and most important application
(http://jpws.sourceforge.net).

== Contributions and Dependencies
The file format is from open-source project "Password Safe" 
(http://sourceforge.net/projects/passwordsafe). 
Encryption software is provided by The Cryptix Foundation, UK, under the 
BSD license, and by own development.

Two utility classes are required which come from the same author and under
same license: kse-util-cla1-0-13-0.jar, kse-util-cla2-0-13-0.jar. These
classes are contained in the project library.

The internal IO-adapter for FTP access requires external software to operate,
namely FTP4J from Sauron Software. A working package is included in the
project's library, the license is the LGPL. 

== Packaging
Javadoc API and source-files packages are available. All software, except
FTP4J, is available as Maven packages at Sonatype Central.

Available Packages of the Distribution
    pwslib3-kse-3.0.0.jar		project executable, LGPL 3
    pwslib3-kse-3.0.0-sources.jar	project sources (text files)
    pwslib3-kse-3.0.0-javadoc.jar	project Javadoc package
    pwslib3-kse-3.0.0.zip		distribution ZIP
    
    kse-util-cla1-0-13-0.jar		external Utilities-1, LGPL 3
    kse-util-cla2-0-13-0.jar		external Utilities-2, LGPL 3
    ftp4j-1.7.2.jar			external FTP module, LGPL 2

Declarations
JUtilClasses-0.13 published by Wolfgang Keller, 2025
ftp4j-1.7.2.jar published by Sauron Software 2007 - 2012.

== Sonatype Reference
<dependency>
    <groupId>io.github.kse2</groupId>
    <artifactId>pwslib3-kse</artifactId>
    <version>3.0.0</version>
</dependency>

== RELEASE SECURITY
Downloads are signed and can be verified using signature files and GPG (http://www.gnupg.org) or PGP. Public RSA key is: 06B66D2C2D62226C Wolfgang Keller <neolith@uber.space>, available at a public key server.

-------------------------------

PRODUCT DETAILS

This is a stable, complete library to access, modify and create encryption
protected databases for passwords in the format series 3 of the project 
"Password Safe" ("PWS" hereafter) by means of Java executable code. 

These are the main features of this software:

a)  Support of a recent security standard of Password Safe files 
    (format 3.13)

b)  cryptographic random generation: use of SecureRandom, system variables
    and SHA512

c)  Encryption technology used is Twofish ECB, CBC and SHA256 for V3 files

d)  Database security level can be set individually by assigning a number 
    of initial calculation loops

e)  Sensible text data, including all passwords, are kept encrypted in 
    memory in special secure text objects created by this project

f)  Reduced risk from memory analysing attacks through the use of special 
    methods to avoid decrypted "waste" material

g)  Abstract IO-interface allows application specific access to data 
    repositories or IO-channels

h)  A set of named canonical record fields allows quick access to commonly
    used data concerning password entries

i)  Non-canonical, user-defined field types may be introduced to amplify
    record structure 

j)  Up to 255 header data fields of variable length may be stored on 
    a database generic level (e.g. allowing for application environment
    specific data)

k)  A set of auxiliary classes allows sorted and filtered representation of
    a PWS file or record list

l)  Event dispatching PWS file class allows smart application design and 
    reaction to content modification

m)  All data is loaded into memory when a file is loaded. The library does
    not keep open file handles outside the load and save methods. Hence
    maximum processable number of records may be limited depending on user's
    runtime environment conditions

n)  Smartly tailored file socket classes allow user to develop other kind
    of applications using PWS encryption technology


(STATE OF MATURITY)

This version of the library is expected to operate stable in all sections.