Metadata-Version: 2.4
Name: pyorchis
Version: 2026.8.0a0
Summary: ORCHIDs for Internet Applications & Protocols.
Author-email: Adam Wiethuechter <atw.ietf@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Repository, https://github.com/kc2rxo/pyorchis.git
Keywords: orchid,cose,jose,hip,drip,rfc7401,rfc9374,rfc7343
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING.txt
Requires-Dist: cbor2>=6.1.4
Requires-Dist: pycryptodome>3.23.0
Provides-Extra: drip
Requires-Dist: cryptography>=50.0.0; extra == "drip"
Provides-Extra: all
Requires-Dist: cbor2>=6.1.4; extra == "all"
Requires-Dist: pycryptodome>3.23.0; extra == "all"
Requires-Dist: cryptography>=50.0.0; extra == "all"
Dynamic: license-file

# ORCHIDs for Internet Applications & Protocols

Overlay Routable Cryptographic Hash IDentifiers (ORCHIDs) are valid non-routable addresses that are found under 
specific IANA assigned prefixes out of the IPv6 Special Purpose Address Space. They encode cryptographic
agility and optional additional information (such as hierarchy) while acting as a handle to the public portion 
of an asymmetric keypair.

An ORCHID is formed with the following general procedure:

1. Select an application specific Suite ID (selecting a key algorithm family and hash algorithm)
2. Generate an asymmetric key pair using the specified Suite ID algorithm family
3. Construct hash input string per application specification with public key
4. With the specified hash algorithm of Suite ID and application Context ID hash previous steps output
5. Assemble ORCHID using application provided prefix, Suite ID and resulting hash

The main protocols using ORCHIDs are:

- Host Identity Protocol (HIP, [RFC7401](https://datatracker.ietf.org/doc/html/rfc7401)) with 
the Host Identity Tag (HIT)
- Drone Remote ID Protocol (DRIP, [RFC9374](https://datatracker.ietf.org/doc/html/rfc9374)) with the 
DRIP Entity Tag (DET), a form of Hierarchical HIT (HHIT)

More on ORCHIDs can be found in [RFC7343](https://datatracker.ietf.org/doc/html/rfc7343).

This project is designed as a reference implementation for ORCHIDs and provides a simple interface to generate and 
import them in Internet based applications or protocols. It is not intended to be a complete solution but rather a 
general toolbox for using of ORCHIDs.

> The project (pyorchis) is named after the plant family and genus that [orchids](https://en.wikipedia.org/wiki/Orchid) 
> are from.

## Installing

```bash
pip3 install pyorchis # core ORCHID capabilities
pip3 install pyorchis[drip] # capabilities for DRIP
pip3 install pyorchis[all] # all capabilities
```

## Cryptography Matrix

This project relies on `pycryptodome` to provide its cryptographic capabilities in support of ORCHID generation and
utility functions for HIP and DRIP.
 
| [H]HIT Suite ID | HI Algorithm | Key Algorithm | Curve      | Hash Algorithm | Supported          |
|-----------------|--------------|---------------|------------|----------------|--------------------|
| 1               | 3            | DSA           | -          | SHA-256        | :white_check_mark: |
| 1               | 5            | RSA           | -          | SHA-256        | :white_check_mark: |
| 2               | 7            | ECDSA         | NIST P-256 | SHA-384        | :white_check_mark: |
| 2               | 7            | ECDSA         | NIST P-384 | SHA-384        | :white_check_mark: |
| 3               | 9            | ECDSA_LOW     | SECP160R1  | SHA-1          | :x:                |
| 5               | 13           | EdDSA         | Ed25519    | cSHAKE128      | :white_check_mark: |
| 5               | 13           | EdDSA         | Ed25519ph  | cSHAKE128      | :x:                |
| 5               | 13           | EdDSA         | Ed448      | cSHAKE128      | :white_check_mark: |
| 5               | 13           | EdDSA         | Ed448ph    | cSHAKE128      | :x:                |

Both RFC7401 prefix of `2001:20::/28` and RFC9374 prefix of `2001:30::/28` are supported.

## Import/Export Matrix

| Key Algorithm | Curve      | PEM/DER/OpenSSH    | Raw                | JSON Web Key       | COSE Key           |
|---------------|------------|--------------------|--------------------|--------------------|--------------------|
| DSA           | -          | :white_check_mark: | :x:                | :x:                | :x:                |
| RSA           | -          | :white_check_mark: | :x:                | :white_check_mark: | :white_check_mark: |
| ECDSA         | NIST P-256 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| ECDSA         | NIST P-384 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| EdDSA         | Ed25519    | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| ECDSA         | Ed448      | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |

[JSON Web Keys of RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) and 
[COSE Keys of RFC9052](https://datatracker.ietf.org/doc/html/rfc9052#section-7) are imported using their native 
encoded typing (`str`/`bytes`) and can be exported either encoded or in `dict[int, Any]` for COSE Key and `dict[str,
 Any]` for JWK.

When exported as COSE Key/JWK, a `Key ID` is set using the ORCHID of the key. When imported with a `Key ID` an 
attempt is made to convert it to an ORCHID or use the imported key to generate the ORCHID and set the `Orchid.ip`
attribute. A raw key import generates the ORCHID directly from incoming key material.

## HIP Capabilities

`Orchid.host_identity()` provides the "Host Identity" field for 
the [HOST_ID](https://datatracker.ietf.org/doc/html/rfc7401#section-5.2.9) parameter. This is used as part of the 
Base Exchange (BEX) when initiating a HIP connection. This structure is also used in the generation of an ORCHID as 
the primary data input for the hash algorithm.

## DRIP Capabilities

`Orchid.arpa()` returns the reverse lookup (i.e. nibble-reversed) IPv6 Fully Qualified Domain Name (FQDN) that is 
used by DRIP to enable lookups via [RFC9886](https://datatracker.ietf.org/doc/html/rfc9886).

---

`x509` is a module supporting X.509 functions around CertificateSigningRequests & Certificates. It follows the 
guidelines in
[DRIP Key Infrastructure (DKI)](https://datatracker.ietf.org/doc/html/draft-ietf-drip-dki/) and generalizes them 
away from the DRIP ecosystem/constraints.

It includes the use of `Subject Alternative Name: IP6` for holding the Subject ORCHID and the extension of
`Authority Key Identifier` for the Issuer ORCHID. These certificates are the "Canonical Registration Certificate" 
that are issued by levels of the hierarchy in DRIP and stored in the HHIT RRType of DNS.
