From 828c0bec6b95a6dcfffd28d0a28caecf4f69addf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Sun, 4 Jan 2015 18:00:23 +0100 Subject: [PATCH] pk-crypto: Improve docstring of signature-related procedures. * guix/pk-crypto.scm (bytevector->hash-data, sign): Augment docstring. --- guix/pk-crypto.scm | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/guix/pk-crypto.scm b/guix/pk-crypto.scm index 71104128c1..e5d4dc9ecc 100644 --- a/guix/pk-crypto.scm +++ b/guix/pk-crypto.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2013, 2014 Ludovic Courtès +;;; Copyright © 2013, 2014, 2015 Ludovic Courtès ;;; ;;; This file is part of GNU Guix. ;;; @@ -254,9 +254,9 @@ Return #f if that element does not exist, or if it's a list." #:optional (hash-algo "sha256") #:key (key-type 'ecc)) - "Given BV, a bytevector containing a hash, return an s-expression suitable -for use as the data for 'sign'. KEY-TYPE must be a symbol: 'dsa, 'ecc, or -'rsa." + "Given BV, a bytevector containing a hash of type HASH-ALGO, return an +s-expression suitable for use as the 'data' argument for 'sign'. KEY-TYPE +must be a symbol: 'dsa, 'ecc, or 'rsa." (string->canonical-sexp (format #f "(data (flags ~a) (hash \"~a\" #~a#))" (case key-type @@ -289,8 +289,10 @@ Return #f if DATA does not conform." (let* ((ptr (libgcrypt-func "gcry_pk_sign")) (proc (pointer->procedure int ptr '(* * *)))) (lambda (data secret-key) - "Sign DATA (an s-expression) with SECRET-KEY (an s-expression whose car -is 'private-key'.)" + "Sign DATA, a canonical s-expression representing a suitable hash, with +SECRET-KEY (a canonical s-expression whose car is 'private-key'.) Note that +DATA must be a 'data' s-expression, as returned by +'bytevector->hash-data' (info \"(gcrypt) Cryptographic Functions\")." (let* ((sig (bytevector->pointer (make-bytevector (sizeof '*)))) (err (proc sig (canonical-sexp->pointer data) (canonical-sexp->pointer secret-key))))