Skip to content

Latest commit

 

History

History
114 lines (82 loc) · 4.78 KB

README.md

File metadata and controls

114 lines (82 loc) · 4.78 KB

Stringprep (RFC 3454) Java implementation

Maven Central Version Reproducible Builds GitHub License

Preparation of Internationalized Strings ("stringprep")

Overview

This project implements the RFC 3454 Preparation of Internationalized Strings ("stringprep") in pure Java.

Maven Central

The stringprep protocol does not stand on its own; it has to be used by other protocols at precisely-defined places in those other protocols.

Profiles

SASLprep (RFC 4013)

SASLprep is a profile of stringprep for user names and passwords (RFC 4013).

Import Maven dependency:

Maven Central

<dependency>
  <groupId>com.ongres.stringprep</groupId>
  <artifactId>saslprep</artifactId>
  <version>2.2</version>
</dependency>

Nameprep (RFC 3491)

Nameprep is a Stringprep Profile for Internationalized Domain Names (IDN) (RFC 3491).

Import Maven dependency:

Maven Central

<dependency>
  <groupId>com.ongres.stringprep</groupId>
  <artifactId>nameprep</artifactId>
  <version>2.2</version>
</dependency>

Usage

The normal usage is to import the dependency of the Stringprep profile to use, and lookup the provider service that contains the profile.

Example:

Import the SASLprep dependency, this transitively imports the Stringprep dependency.

<dependency>
  <groupId>com.ongres.stringprep</groupId>
  <artifactId>saslprep</artifactId>
  <version>2.2</version>
</dependency>

Get the SASLprep provider service:

Profile saslPrep = Stringprep.getProvider("SASLprep");
String prepared = saslPrep.prepareStored("I\u00ADX \u2168");
prepared.equals("IX IX"); // true

You could also (only) use the stringprep dependency to create your own profiles by implementing the Profile interface, just override the profile() method with the set of options.

Anonymous on-the-fly profile usage:

Profile saslPrep = () -> EnumSet.of(Option.NORMALIZE_KC, Option.MAP_TO_NOTHING);
String prepared = saslPrep.prepareStored("I\u00ADX ⑳");
prepared.equals("IX 20"); // true

Please note that when two protocols that use different profiles of stringprep interoperate, there may be conflict about what characters are and are not allowed in the final string. Thus, protocol developers should strongly consider re-using existing profiles of stringprep.

Java Modules (JPMS):

The Stringprep and profiles implementation are explicit Java modules with the names:

  • com.ongres.stringprep
  • com.ongres.saslprep
  • com.ongres.nameprep

If you depend on a specific profile (saslprep or nameprep) there is an implied readability on stringprep, so you will only need to declare in your module-info.java the profile module and get the service from the provider.

Example module-info.java:

module test.app {
  requires com.ongres.saslprep;
}

Goals

This project aims to provide a implementation of these algorithms. It is written in Java and provided in a modular, re-usable way, independent of other software or programs.

Current functionality includes:

  • Parsers with the different steps for preparing string. The data is obtained from files with the rules of the RFC.
  • Provide a Profile interface working as the base for implementing different profiles of Stringprep.
  • Include the preparation of two types of strings "stored strings" and "queries".
  • SASLprep profile with the specific options of Stringprep.
  • Nameprep profile with the specific options of Stringprep.
  • Tests with the RFC example and several tests of each steps.
  • Multi-release Modular JARs, compatible with Java 8+.
  • Zero-depdency, each profile depends only on the Stringprep module.
  • New Stringprep profiles could be implemented easily and even "on-the-fly".