[[riscv-doc-template]]
= RISC-V Cryptography Extensions Volume I: Scalar & Entropy Source Instructions
:description: The scalar cryptography and entropy source extensions for the RISC-V ISA.
:company: RISC-V.org
:revdate:  18'th Feb, 2022
:revnumber: v1.0.1
:revremark: Ratified
:url-riscv: http://riscv.org
:doctype: book
//:doctype: report
:preface-title: Preamble
:colophon:
:appendix-caption: Appendix
:imagesdir: images
:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center]
//:page-background-image: image:draft.svg[opacity=20%]
//:title-page-background-image: none
//:back-cover-image: image:circuit.png[opacity=25%]
// Settings:
:experimental:
:reproducible:
// needs to be changed? bug discussion started
:WaveDromEditorApp: wavedrom-cli
:imagesoutdir: images
:icons: font
:lang: en
:listing-caption: Listing
:sectnums:
:toc: left
:toclevels: 4
:source-highlighter: pygments
ifdef::backend-pdf[]
:source-highlighter: coderay
endif::[]
:data-uri:
:hide-uri-scheme:
:stem: latexmath
:footnote:
:xrefstyle: short
:bibtex-file: ../riscv-crypto-spec.bib
:bibtex-order: alphabetical
:bibtex-style: ieee

//:This is the preamble.

[colophon]
= Colophon

This document describes the Scalar Cryptography extensions to the 
RISC-V Instruction Set Architecture.

This document is in the link:http://riscv.org/spec-state[Ratified state].
No changes are allowed. Any desired or needed changes can be the subject of a
follow-on new extension. Ratified extensions are never revised.
For more information, see link:http://riscv.org/spec-state[here].

[NOTE]
.Copyright and licensure:
This work is licensed under a
link:http://creativecommons.org/licenses/by/4.0/[Creative Commons Attribution 4.0 International License]

[NOTE]
.Document Version Information:
====
include::git-commit.adoc[]

See link:https://github.com/riscv/riscv-crypto[github.com/riscv/riscv-crypto]
for more information.
====

[acknowledgments]
== Acknowledgments

Contributors to all versions of the specification (in alphabetical order)
include: +
Alexander Zeh,
Andy Glew,
Barry Spinney,
link:mailto:benmarshall@pqshield.com[Ben Marshall] (Editor),
Daniel Page,
Derek Atkins,
Ken Dockser,
Markku-Juhani O. Saarinen,
Nathan Menhorn,
L Peter Deutsch,
Richard Newell,
Claire Wolf

We are all very grateful to the huge number of other people who have
helped to improve this specification through their comments, reviews,
feedback and questions.

[changelog]
== Changelog

[cols="1,5"]
|===
| Version | Changes

| `v1.0.1` 
| Fix typos to show that 
  `c.srli`, `c.srai`, and `c.slli` are Zkt instructions in RV64.

| `v1.0.0` 
| Initial Release
|===


// ------------------------------------------------------------

include::riscv-crypto-scalar-introduction.adoc[]
include::riscv-crypto-scalar-audience.adoc[]
include::riscv-crypto-scalar-sail-specifications.adoc[]
include::riscv-crypto-scalar-policies.adoc[]

// ------------------------------------------------------------

[[crypto_scalar_extensions]]
== Extensions Overview

The group of extensions introduced by the Scalar Cryptography Instruction Set
Extension is listed here.

Detection of individual cryptography extensions uses the
unified software-based RISC-V discovery method.

[NOTE]
====
At the time of writing, these discovery mechanisms are still a work in
progress.
====

.A note on extension rationale
[NOTE, caption="SH"]
====
Specialist encryption and decryption instructions are separated into different
functional groups because some use cases (e.g., Galois/Counter
Mode in TLS 1.3) do not require decryption functionality.

The NIST and ShangMi algorithms suites are separated because their
usefulness is heavily dependent on the countries a device is expected to
operate in. NIST ciphers are a part of most standardised internet
protocols, while ShangMi ciphers are required for use in China.
====

include::riscv-crypto-scalar-zbkb.adoc[]
include::riscv-crypto-scalar-zbkc.adoc[]
include::riscv-crypto-scalar-zbkx.adoc[]
include::riscv-crypto-scalar-zknd.adoc[]
include::riscv-crypto-scalar-zkne.adoc[]
include::riscv-crypto-scalar-zknh.adoc[]
include::riscv-crypto-scalar-zksed.adoc[]
include::riscv-crypto-scalar-zksh.adoc[]
include::riscv-crypto-scalar-zkr.adoc[]
include::riscv-crypto-scalar-zkn.adoc[]
include::riscv-crypto-scalar-zks.adoc[]
include::riscv-crypto-scalar-zk.adoc[]

=== `Zkt` - Data Independent Execution Latency

This extension allows CPU implementers to indicate to
cryptographic software developers that a subset of RISC-V instructions
are guaranteed to be implemented such that their execution latency
is independent of the data values they operate on.
A complete description of this extension is found in
<<crypto_scalar_zkt>>.

// ------------------------------------------------------------

[[crypto_scalar_insns, reftext="Scalar Cryptography Instructions"]]
== Instructions
include::insns/aes32dsi.adoc[]
<<<
include::insns/aes32dsmi.adoc[]
<<<
include::insns/aes32esi.adoc[]
<<<
include::insns/aes32esmi.adoc[]
<<<
include::insns/aes64ds.adoc[]
<<<
include::insns/aes64dsm.adoc[]
<<<
include::insns/aes64es.adoc[]
<<<
include::insns/aes64esm.adoc[]
<<<
include::insns/aes64im.adoc[]
<<<
include::insns/aes64ks1i.adoc[]
<<<
include::insns/aes64ks2.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/andn.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/brev8.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/clmul.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/clmulh.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/orn.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/pack.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/packh.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/packw.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/rev8.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/rol.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/rolw.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/ror.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/rori.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/roriw.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/rorw.adoc[]
<<<
include::insns/sha256sig0.adoc[]
<<<
include::insns/sha256sig1.adoc[]
<<<
include::insns/sha256sum0.adoc[]
<<<
include::insns/sha256sum1.adoc[]
<<<
include::insns/sha512sig0h.adoc[]
<<<
include::insns/sha512sig0l.adoc[]
<<<
include::insns/sha512sig1h.adoc[]
<<<
include::insns/sha512sig1l.adoc[]
<<<
include::insns/sha512sum0r.adoc[]
<<<
include::insns/sha512sum1r.adoc[]
<<<
include::insns/sha512sig0.adoc[]
<<<
include::insns/sha512sig1.adoc[]
<<<
include::insns/sha512sum0.adoc[]
<<<
include::insns/sha512sum1.adoc[]
<<<
include::insns/sm3p0.adoc[]
<<<
include::insns/sm3p1.adoc[]
<<<
include::insns/sm4ed.adoc[]
<<<
include::insns/sm4ks.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/unzip.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/xnor.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/xperm8.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/xperm4.adoc[]
<<<
include::../../extern/riscv-bitmanip/bitmanip/insns/zip.adoc[]

include::riscv-crypto-scalar-entropy-source.adoc[]
include::riscv-crypto-scalar-zkt.adoc[]

[[bibliography]]
== Bibliography

bibliography::../riscv-crypto-spec.bib[ieee]

include::riscv-crypto-scalar-appx-rationale.adoc[]
include::riscv-crypto-scalar-appx-entropy-source.adoc[]
include::riscv-crypto-scalar-appx-materials.adoc[]
include::riscv-crypto-scalar-appx-sail.adoc[]

