Crypto API 레퍼런스

← Crypto 메인

CryptoOps

플랫폼별 암호화 연산 구현을 제공하는 메인 인터페이스입니다. JVM과 JavaScript 모두에서 동일한 API를 제공합니다.

keccak256

def keccak256(input: Array[Byte]): Array[Byte]

입력 바이트의 Keccak-256 해시를 계산합니다.

파라미터:

반환값:

특징:

예제:

val message = "Hello, World!".getBytes
val hash = CryptoOps.keccak256(message)
assert(hash.length == 32)

generate

def generate(): KeyPair

새로운 무작위 secp256k1 키 쌍을 생성합니다.

반환값:

특징:

예제:

val keyPair1 = CryptoOps.generate()
val keyPair2 = CryptoOps.generate()
assert(keyPair1.privateKey != keyPair2.privateKey)

fromPrivate

def fromPrivate(privateKey: BigInt): KeyPair

기존 개인키로부터 키 쌍을 유도합니다.

파라미터:

반환값:

특징:

예제:

import org.sigilaris.core.datatype.UInt256

val privateKey = UInt256.fromHex("0123456789abcdef...").toOption.get
val keyPair = CryptoOps.fromPrivate(privateKey.toBigInt)

sign

def sign(keyPair: KeyPair, transactionHash: Array[Byte]): Either[SigilarisFailure, Signature]

ECDSA로 메시지 해시에 서명합니다.

파라미터:

반환값:

특징:

예제:

val keyPair = CryptoOps.generate()
val message = "Sign this!".getBytes
val hash = CryptoOps.keccak256(message)

CryptoOps.sign(keyPair, hash) match {
  case Right(signature) => println(s"Signed: $signature")
  case Left(error) => println(s"Error: $error")
}

recover

def recover(signature: Signature, hashArray: Array[Byte]): Either[SigilarisFailure, PublicKey]

서명과 메시지 해시로부터 공개키를 복구합니다.

파라미터:

반환값:

특징:

예제:

val keyPair = CryptoOps.generate()
val hash = CryptoOps.keccak256("message".getBytes)
val signature = CryptoOps.sign(keyPair, hash).toOption.get

CryptoOps.recover(signature, hash) match {
  case Right(publicKey) =>
    assert(publicKey == keyPair.publicKey)
  case Left(error) =>
    println(s"Recovery failed: $error")
}

KeyPair

secp256k1 키 쌍을 나타내는 데이터 타입입니다.

final case class KeyPair(privateKey: UInt256, publicKey: PublicKey)

필드:

예제:

val keyPair = CryptoOps.generate()
println(s"Private: ${keyPair.privateKey}")
println(s"Public: ${keyPair.publicKey}")

관련 함수:

Signature

복구 파라미터를 포함한 secp256k1용 ECDSA 서명입니다.

final case class Signature(v: Int, r: UInt256, s: UInt256)

필드:

Low-S 정규화: 서명은 자동으로 Low-S 형태로 정규화되어 서명 변조(signature malleability)를 방지합니다.

예제:

val signature = Signature(
  v = 27,
  r = UInt256.fromHex("...").toOption.get,
  s = UInt256.fromHex("...").toOption.get
)

관련 함수:

Hash

타입 안전한 Keccak-256 해싱을 위한 타입 클래스입니다.

trait Hash[A]:
  def apply(a: A): Hash.Value[A]
  def contramap[B](f: B => A): Hash[B]

Hash.Value

해시의 소스 타입을 추적하는 UInt256을 감싸는 opaque 타입입니다.

opaque type Value[A] = UInt256

타입 파라미터:

Hash 인스턴스 생성

build

def build[A: ByteEncoder]: Hash[A]

ByteEncoder를 가진 모든 타입에 대한 Hash 인스턴스를 생성합니다.

예제:

import org.sigilaris.core.codec.byte.ByteEncoder

case class User(id: Long, name: String)

given Hash[User] = Hash.build[User]

val user = User(1L, "Alice")
val userHash = user.toHash

Extension 메서드

extension [A](a: A) def toHash(using h: Hash[A]): Hash.Value[A]
extension [A](value: Hash.Value[A]) def toUInt256: UInt256

예제:

import org.sigilaris.core.crypto.Hash.ops.*
import org.sigilaris.core.datatype.Utf8

val utf8 = Utf8("hello")
val hash: Hash.Value[Utf8] = utf8.toHash
val uint256: UInt256 = hash.toUInt256

기본 인스턴스

Utf8

given Hash[Utf8] = Hash.build

UTF-8 문자열에 대한 기본 Hash 인스턴스입니다.

예제:

import org.sigilaris.core.datatype.Utf8

val text = Utf8("Hello, World!")
val hash = text.toHash

PublicKey

secp256k1 공개키를 나타냅니다. 플랫폼별로 다른 구현을 가질 수 있지만 동일한 API를 제공합니다.

타입

공개키는 sealed trait로 구현되어 있으며, 두 가지 형태를 가질 수 있습니다:

  1. XY: 바이트 중심 표현 (x, y 좌표)
  2. Point: 타원곡선 점 중심 표현 (JVM 전용, 성능 최적화)

표현

특징

예제:

val keyPair = CryptoOps.generate()
val publicKey = keyPair.publicKey

// 공개키는 64바이트로 직렬화 가능
val bytes = publicKey.toBytes
assert(bytes.length == 64)

에러 처리

암호화 연산은 실패할 수 있으며, Either[SigilarisFailure, A]를 반환합니다.

일반적인 에러

서명 생성:

공개키 복구:

예제:

val result = CryptoOps.sign(keyPair, hash)
result match {
  case Right(signature) =>
    // 서명 사용
    println(s"Success: $signature")
  case Left(error) =>
    // 에러 처리
    println(s"Failed: ${error.message}")
}

사용 팁

1. 해시 재사용

같은 메시지를 여러 번 해시하지 마세요:

// 나쁜 예
val hash1 = CryptoOps.keccak256(message)
val hash2 = CryptoOps.keccak256(message)

// 좋은 예
val hash = CryptoOps.keccak256(message)
// hash를 여러 번 재사용

2. 타입 안전한 해싱

Hash 타입 클래스를 사용하여 타입 정보를 보존하세요:

import org.sigilaris.core.crypto.Hash.ops.*

case class Document(content: String)
given Hash[Document] = Hash.build[Document]

val doc = Document("important")
val docHash: Hash.Value[Document] = doc.toHash

3. 에러 처리

항상 Either의 실패 케이스를 처리하세요:

for {
  signature <- CryptoOps.sign(keyPair, hash)
  publicKey <- CryptoOps.recover(signature, hash)
} yield {
  // 성공 경로
  println(s"Recovered: $publicKey")
}

← Crypto 메인