Target releaseV 0.1 Release Candidate 1 (RC1)
Document status
Document owner
DesignerJohn McCane-Whitney
DevelopersHoward Kitto


  • Successful release first RC1 candidate of baseline Milagro Server, strictly following Apache's release process.
  • Create foundation install script/process by which specific services can be initialized to run within the Milagro Server.
  • Expose a RESTful API to potential Milagro Server users so they can comment and feedback to contributors and PPMC.
  • Include key functional requirements.
    • PKCS#11 integration
    • Basic implementation of Elliptic Curve addition cryptosystem for digital asset custody. This will be nascent capability, but proves cryptographic functionality.
  • Include decentralized public key infrastructure based on IPFS
  • Include 'encrypted envelope' formatted messages for distributing secrets and keys generated by Milagro Servers for secure messaging between servers. Initial version will use IPFS pubsub but other transport mechanisms will be supported in future versions.

Background and strategic fit

Apache Milagro (incubating) needs a general purpose 'Milagro Server' that can encapsulate all the required components to bring up and distributed / decentralized core security services. As an example, in the current Python versioned M-Pin server I believe there does not exist any flag on whether to run this as a D-TA (serving shares of secrets) or as an M-Pin Server. This means someone building a fully fledged M-Pin protocol based implementation needs to construct their own D-TA services, which is causing implementation drag.

An install script that can pull down various components and complete installation according to config/install scripts is required.

Milagro should address use cases within the digital asset space that deliver on the security requirements for decentralized networks, in addition to the enterprise and IoT spaces. There is much interest from these communities for open source platforms that can secure escrow of private keys used to store value and transact cryptocurrencies (custody) but operate in a decentralized manner - capability that is native to Milagro crypto libraries already.

Milagro will incorporate a distributed, immutable file system called IPFS, an immutable, operation-based conflict-free replicated data structure (CRDT) for distributed systems with MIT license. On top of IPFS, a decentralized public key infrastructure that does away with certificates and certificate authorities. This decentralized public key infrastructure enables an encrypted messaging over IPFS pubsub. We propose to call this the 'Milagro encrypted envelope' format.

This functionality is required to enable Milagro Servers to distribute secrets over a decentralized infrastructure - as an example, a D-TA operating in this manner and distributing shares of M-Pin secrets to clients would work across use deployment sectors (IoT, enterprise, decentralized, etc.)

RC1 Candidate

The Milagro server will use the encrypted envelope format to distribute Elliptic Curve keys between instances of Milagro Servers. This EC keys are ultimately used to create cryptocurrency wallet addresses, or create private keys used to control digital assets inside a cryptocurrency wallet.

This capability is also critical for D-TAs, so that decentralized D-TA services can distributed shares of M-Pin protocol based private/server keys to authenticated endpoints/clients using the message format independent of channel (VPN, TLS, etc.) so that data is secured even over a transport with no security.


  • This RC1 candidate will be used by people who have some technical skill
  • This will not have a user interface, but a command line interface
  • Current M-Pin servers have to be refactored to fit within this construct, and it should be the goal that all existing services (MFA, D-TA) are refactored to fit this environment.


#TitleUser StoryImportanceNotes
1Create ID DocumentAs user, I want my Milagro Server to initialize and register an Must Have
  • See issue

MILAGRO-31 - Getting issue details... STATUS

2PKCS#11 IntegrationAs a user, I want my Milagro Server's secrets to be protected with an HSM.Nice to Have
  • See issue

MILAGRO-32 - Getting issue details... STATUS

3Docker Container SupportAs a user, I want my Milagro Server to be able to be deployed via DockerNice to Have
  • See issue

MILAGRO-33 - Getting issue details... STATUS

4Install/Config MethodAs a user, I want to have a configuration/install method that sets up the instance of the Milagro Server for my intended use.Must Have
  • See issues

MILAGRO-34 - Getting issue details... STATUS

5Decentralized CustodyAs a user, I want to use a configuration of decentralized Milagro Servers to provide a wallet address, and then provide the private key to the wallet address.Must Have
  • See issue

MILAGRO-35 - Getting issue details... STATUS

User interaction and design

For RC1, the user interaction happens over command line.

The user interaction also requires that the user setup, manually, which Milagro servers act as beneficiaries, fiduciaries and principals.

Principal, Beneficiary and Fiduciary workflow


Below is a list of questions to be addressed as a result of this requirements document:


Not Included in RC1

  • MFA - work needs to be done to either re-factor or rebuild fresh authentication services using M-Pin protocol to fit in this paradigm